Moving docs tree to docs-xml to make room for generated docs in the release tarball.

(This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14)

1 files changed, 1710 insertions, 0 deletions

diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml b/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml
new file mode 100644
index 0000000000..48f439dead
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml
@@ -0,0 +1,1710 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+
+<chapter id="AccessControls">
+<chapterinfo>
+	&author.jht;
+	&author.jeremy;
+	<author>&person.jelmer;<contrib>drawing</contrib></author>
+	<pubdate>May 10, 2003</pubdate>
+</chapterinfo>
+<title>File, Directory, and Share Access Controls</title>
+
+<para>
+<indexterm><primary>ACLs</primary></indexterm>
+<indexterm><primary>share</primary></indexterm>
+<indexterm><primary>network access controls</primary></indexterm>
+<indexterm><primary>unauthorized access</primary></indexterm>
+Advanced MS Windows users are frequently perplexed when file, directory, and share manipulation of
+resources shared via Samba do not behave in the manner they might expect. MS Windows network
+administrators are often confused regarding network access controls and how to
+provide users with the access they need while protecting resources from unauthorized access.
+</para>
+
+<para>
+<indexterm><primary>file access permissions</primary></indexterm>
+<indexterm><primary>directory access permissions</primary></indexterm>
+Many UNIX administrators are unfamiliar with the MS Windows environment and in particular
+have difficulty in visualizing what the MS Windows user wishes to achieve in attempts to set file
+and directory access permissions. 
+</para>
+
+<para>
+<indexterm><primary>bridge</primary></indexterm>
+<indexterm><primary>directory controls</primary></indexterm>
+<indexterm><primary>directory permissions</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+The problem lies in the differences in how file and directory permissions and controls work
+between the two environments. This difference is one that Samba cannot completely hide, even
+though it does try to bridge the chasm to a degree.
+</para>
+
+<para>
+<indexterm><primary>Extended Attributes</primary></indexterm>
+<indexterm><primary>ACLs</primary><secondary>POSIX</secondary></indexterm>
+<indexterm><primary>Access Control List</primary></indexterm>
+<indexterm><primary>commercial Linux products</primary></indexterm>
+POSIX Access Control List technology has been available (along with extended attributes)
+for UNIX for many years, yet there is little evidence today of any significant use. This
+explains to some extent the slow adoption of ACLs into commercial Linux products. MS Windows
+administrators are astounded at this, given that ACLs were a foundational capability of the now
+decade-old MS Windows NT operating system.
+</para>
+
+<para>
+<indexterm><primary>network administrator</primary></indexterm>
+The purpose of this chapter is to present each of the points of control that are possible with
+Samba-3 in the hope that this will help the network administrator to find the optimum method
+for delivering the best environment for MS Windows desktop users.
+</para>
+
+<para>
+<indexterm><primary>interoperability</primary></indexterm>
+<indexterm><primary>data interchange</primary></indexterm>
+This is an opportune point to mention that Samba was created to provide a means of interoperability
+and interchange of data between differing operating environments. Samba has no intent to change
+UNIX/Linux into a platform like MS Windows. Instead the purpose was and is to provide a sufficient
+level of exchange of data between the two environments. What is available today extends well
+beyond early plans and expectations, yet the gap continues to shrink.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+	<para>
+	Samba offers much flexibility in file system access management. These are the key access control
+	facilities present in Samba today:
+	</para>
+
+	<itemizedlist>
+	<title>Samba Access Control Facilities</title>
+		<listitem><para>
+		<indexterm><primary>permissions</primary><secondary>UNIX file and directory</secondary></indexterm>
+		<emphasis>UNIX File and Directory Permissions</emphasis>
+		</para>
+
+			<para>
+<indexterm><primary>UNIX file system access controls</primary></indexterm>
+<indexterm><primary>access controls</primary></indexterm>
+<indexterm><primary>permissions and controls</primary></indexterm>
+			Samba honors and implements UNIX file system access controls. Users
+			who access a Samba server will do so as a particular MS Windows user.
+			This information is passed to the Samba server as part of the logon or
+			connection setup process. Samba uses this user identity to validate
+			whether or not the user should be given access to file system resources
+			(files and directories). This chapter provides an overview for those
+			to whom the UNIX permissions and controls are a little strange or unknown.
+			</para>
+		</listitem>
+
+		<listitem><para>
+		<emphasis>Samba Share Definitions</emphasis>
+		</para>
+
+			<para>
+<indexterm><primary>share settings</primary></indexterm>
+			In configuring share settings and controls in the &smb.conf; file,
+			the network administrator can exercise overrides to native file
+			system permissions and behaviors. This can be handy and convenient
+			to effect behavior that is more like what MS Windows NT users expect,
+			but it is seldom the <emphasis>best</emphasis> way to achieve this.
+			The basic options and techniques are described herein.
+			</para>
+		</listitem>
+
+		<listitem><para>
+		<emphasis>Samba Share ACLs</emphasis>
+		<indexterm><primary>ACLs</primary><secondary>share</secondary></indexterm>
+		</para>
+
+			<para>
+<indexterm><primary>ACLs on shares</primary></indexterm>
+			Just as it is possible in MS Windows NT to set ACLs on shares
+			themselves, so it is possible to do in Samba.
+			Few people make use of this facility, yet it remains one of the
+			easiest ways to affect access controls (restrictions) and can often
+			do so with minimum invasiveness compared with other methods.
+			</para>
+		</listitem>
+
+		<listitem><para>
+				<indexterm><primary>ACLs</primary><secondary>POSIX</secondary></indexterm>
+				<indexterm><primary>ACLs</primary><secondary>Windows</secondary></indexterm>
+		<emphasis>MS Windows ACLs through UNIX POSIX ACLs</emphasis>
+		</para>
+
+			<para>
+<indexterm><primary>native ACLs</primary></indexterm>
+			The use of POSIX ACLs on UNIX/Linux is possible only if the underlying
+			operating system supports them. If not, then this option will not be
+			available to you. Current UNIX technology platforms have native support
+			for POSIX ACLs. There are patches for the Linux kernel that also provide
+			this support. Sadly, few Linux platforms ship today with native ACLs and
+			extended attributes enabled. This chapter has pertinent information
+			for users of platforms that support them.
+			</para>
+		</listitem>
+	</itemizedlist>
+
+</sect1>
+
+<sect1>
+<title>File System Access Controls</title>
+
+<para>
+Perhaps the most important recognition to be made is the simple fact that MS Windows NT4/200x/XP
+implement a totally divergent file system technology from what is provided in the UNIX operating system
+environment. First we consider what the most significant differences are, then we look
+at how Samba helps to bridge the differences.
+</para>
+
+	<sect2>
+	<title>MS Windows NTFS Comparison with UNIX File Systems</title>
+
+	<para>
+	<indexterm><primary>NTFS</primary></indexterm>
+	<indexterm><primary>File System</primary></indexterm>
+	<indexterm><primary>File System</primary><secondary>UNIX</secondary></indexterm>
+	<indexterm><primary>File System</primary><secondary>Windows</secondary></indexterm>
+	Samba operates on top of the UNIX file system. This means it is subject to UNIX file system conventions
+	and permissions. It also means that if the MS Windows networking environment requires file system
+	behavior, that differs from UNIX file system behavior then somehow Samba is responsible for emulating
+	that in a transparent and consistent manner.
+	</para>
+
+	<para>
+	It is good news that Samba does this to a large extent, and on top of that, provides a high degree
+	of optional configuration to override the default behavior. We look at some of these overrides,
+	but for the greater part we stay within the bounds of default behavior. Those wishing to explore
+	the depths of control ability should review the &smb.conf; man page.
+	</para>
+
+	<para>The following compares file system features for UNIX with those of MS Windows NT/200x:
+	<indexterm><primary>File System</primary><secondary>feature comparison</secondary></indexterm>
+	
+	</para>
+
+	<variablelist>
+		<varlistentry>
+			<term>Name Space</term>
+			<listitem>
+		<para>
+		MS Windows NT4/200x/XP file names may be up to 254 characters long, and UNIX file names
+		may be 1023 characters long. In MS Windows, file extensions indicate particular file types;
+		in UNIX this is not so rigorously observed because all names are considered arbitrary. 
+		</para>
+		<para>
+		What MS Windows calls a folder, UNIX calls a directory.
+		</para>
+			</listitem>
+		</varlistentry>
+
+		<varlistentry>
+			<term>Case Sensitivity</term>
+			<listitem>
+		<para>
+		<indexterm><primary>8.3 file names</primary></indexterm>
+		<indexterm><primary>File System</primary><secondary>case sensitivity</secondary></indexterm>
+		MS Windows file names are generally uppercase if made up of 8.3 (8-character file name
+		and 3 character extension. File names that are longer than 8.3 are case preserving and case
+		insensitive.
+		</para>
+
+		<para>
+		UNIX file and directory names are case sensitive and case preserving. Samba implements the
+		MS Windows file name behavior, but it does so as a user application. The UNIX file system
+		provides no mechanism to perform case-insensitive file name lookups. MS Windows does this
+		by default. This means that Samba has to carry the processing overhead to provide features
+		that are not native to the UNIX operating system environment.
+		</para>
+
+		<para>
+		Consider the following. All are unique UNIX names but one single MS Windows file name:
+		<screen>
+				MYFILE.TXT
+				MyFile.txt
+				myfile.txt
+		</screen></para>
+
+		<para>
+		So clearly, in an MS Windows file namespace these three files cannot co-exist, but in UNIX
+		they can.
+		</para>
+
+		<para>
+		So what should Samba do if all three are present? That which is lexically first will be
+		accessible to MS Windows users; the others are invisible and unaccessible &smbmdash; any
+		other solution would be suicidal. The Windows client will ask for a case-insensitive file
+		lookup, and that is the reason for which Samba must offer a consistent selection in the
+		event that the UNIX directory contains multiple files that would match a case insensitive
+		file listing.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Directory Separators</term>
+		<listitem><para>
+		<indexterm><primary>Directory Separators</primary></indexterm>
+		MS Windows and DOS use the backslash <constant>\</constant> as a directory delimiter, and UNIX uses
+		the forward-slash <constant>/</constant> as its directory delimiter. This is handled transparently by Samba.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Drive Identification</term>
+		<listitem><para>
+		<indexterm><primary>Drive Identification</primary></indexterm>
+		MS Windows products support a notion of drive letters, like <command>C:</command>, to represent
+		disk partitions. UNIX has no concept of separate identifiers for file partitions; each
+		such file system is mounted to become part of the overall directory tree.
+		The UNIX directory tree begins at <constant>/</constant> just as the root of a DOS drive is specified as
+		<constant>C:\</constant>.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>File Naming Conventions</term>
+		<listitem><para>
+		<indexterm><primary>File Naming Conventions</primary></indexterm>
+		MS Windows generally never experiences file names that begin with a dot (<constant>.</constant>), while in UNIX these
+		are commonly found in a user's home directory. Files that begin with a dot (<constant>.</constant>) are typically
+		startup files for various UNIX applications, or they may be files that contain
+		startup configuration data.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Links and Short-Cuts</term>
+		<listitem><para>
+		<indexterm><primary>Links</primary><secondary>hard</secondary></indexterm>
+		<indexterm><primary>Links</primary><secondary>soft</secondary></indexterm>
+		<indexterm><primary>Shortcuts</primary></indexterm>
+		MS Windows make use of <emphasis>links and shortcuts</emphasis> that are actually special types of files that will
+		redirect an attempt to execute the file to the real location of the file. UNIX knows of file and directory
+		links, but they are entirely different from what MS Windows users are used to.
+		</para>
+
+		<para>
+		Symbolic links are files in UNIX that contain the actual location of the data (file or directory). An
+		operation (like read or write) will operate directly on the file referenced. Symbolic links are also
+		referred to as <quote>soft links.</quote> A hard link is something that MS Windows is not familiar with. It allows
+		one physical file to be known simultaneously by more than one file name.
+		</para></listitem>
+		</varlistentry>
+	</variablelist>
+
+	<para>
+	There are many other subtle differences that may cause the MS Windows administrator some temporary discomfort
+	in the process of becoming familiar with UNIX/Linux. These are best left for a text that is dedicated to the
+	purpose of UNIX/Linux training and education.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Managing Directories</title>
+
+	<para>
+<indexterm><primary>create</primary></indexterm>
+<indexterm><primary>delete</primary></indexterm>
+<indexterm><primary>rename</primary></indexterm>
+	There are three basic operations for managing directories: <command>create</command>, <command>delete</command>,
+	<command>rename</command>. <link linkend="TOSH-Accesstbl">Managing Directories with UNIX and
+	Windows</link> compares the commands in Windows and UNIX that implement these operations.
+	</para>
+
+	<table frame="all" id="TOSH-Accesstbl">
+		<title>Managing Directories with UNIX and Windows</title>
+		<tgroup align="center" cols="3">
+		<thead>
+		<row><entry>Action</entry><entry>MS Windows Command</entry><entry>UNIX Command</entry></row>
+		</thead>
+	
+		<tbody>
+			<row><entry>create</entry><entry>md folder</entry><entry>mkdir folder</entry></row>
+			<row><entry>delete</entry><entry>rd folder</entry><entry>rmdir folder</entry></row>
+			<row><entry>rename</entry><entry>rename oldname newname</entry><entry>mv oldname newname</entry></row>
+		</tbody>
+	</tgroup>
+	</table>
+
+	</sect2>
+
+	<sect2>
+	<title>File and Directory Access Control</title>
+
+	<para>
+	<indexterm><primary>ACLs</primary><secondary>File System</secondary></indexterm>
+<indexterm><primary>POSIX ACLs</primary></indexterm>
+<indexterm><primary>EAs</primary></indexterm>
+	The network administrator is strongly advised to read basic UNIX training manuals and reference materials
+	regarding file and directory permissions maintenance. Much can be achieved with the basic UNIX permissions
+	without having to resort to more complex facilities like POSIX ACLs or extended attributes (EAs).
+	</para>
+
+	<para>
+	UNIX/Linux file and directory access permissions involves setting three primary sets of data and one control set.
+	A UNIX file listing looks as follows:
+<screen>
+&prompt;<userinput>ls -la</userinput>
+total 632
+drwxr-xr-x   13 maryo   gnomes      816 2003-05-12 22:56 .
+drwxrwxr-x   37 maryo   gnomes     3800 2003-05-12 22:29 ..
+dr-xr-xr-x    2 maryo   gnomes       48 2003-05-12 22:29 muchado02
+drwxrwxrwx    2 maryo   gnomes       48 2003-05-12 22:29 muchado03
+drw-rw-rw-    2 maryo   gnomes       48 2003-05-12 22:29 muchado04
+d-w--w--w-    2 maryo   gnomes       48 2003-05-12 22:29 muchado05
+dr--r--r--    2 maryo   gnomes       48 2003-05-12 22:29 muchado06
+drwsrwsrwx    2 maryo   gnomes       48 2003-05-12 22:29 muchado08
+----------    1 maryo   gnomes     1242 2003-05-12 22:31 mydata00.lst
+--w--w--w-    1 maryo   gnomes     7754 2003-05-12 22:33 mydata02.lst
+-r--r--r--    1 maryo   gnomes    21017 2003-05-12 22:32 mydata04.lst
+-rw-rw-rw-    1 maryo   gnomes    41105 2003-05-12 22:32 mydata06.lst
+&prompt;
+</screen>
+	</para>
+
+	<para>
+	The columns represent (from left to right) permissions, number of hard links to file, owner, group, size
+	(bytes), access date, time of last modification, and file name.
+	</para>
+
+	<para>
+	An overview of the permissions field is shown in <link linkend="access1">Overview of UNIX permissions
+	field</link>.
+	</para>
+
+	<figure id="access1">
+		<title>Overview of UNIX permissions field.</title>
+		<imagefile scale="40">access1</imagefile>
+	</figure>
+
+	<para>
+		Any bit flag may be unset. An unset bit flag is the equivalent of "cannot" and is represented
+		as a <quote>-</quote> character (see <link linkend="access2"/>)
+<indexterm><primary>read</primary></indexterm>
+<indexterm><primary>write</primary></indexterm>
+<indexterm><primary>execute</primary></indexterm>
+<indexterm><primary>user</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>other</primary></indexterm>
+	</para>
+
+<example id="access2">
+<title>Example File</title>
+<programlisting>
+-rwxr-x---   Means: 
+ ^^^                The owner (user) can read, write, execute
+    ^^^             the group can read and execute
+       ^^^          everyone else cannot do anything with it.
+</programlisting>
+</example>
+
+
+	<para>
+<indexterm><primary>character device</primary></indexterm>
+<indexterm><primary>block device</primary></indexterm>
+<indexterm><primary>pipe device</primary></indexterm>
+<indexterm><primary>UNIX Domain Socket</primary></indexterm>
+	Additional possibilities in the [type] field are c = character device, b = block device, p = pipe device,
+	s = UNIX Domain Socket.
+	</para>
+
+	<para>
+<indexterm><primary>read</primary></indexterm>
+<indexterm><primary>write</primary></indexterm>
+<indexterm><primary>execute</primary></indexterm>
+<indexterm><primary>SGID</primary></indexterm>
+<indexterm><primary>SUID</primary></indexterm>
+	The letters <constant>rwxXst</constant> set permissions for the user, group, and others as read (r), write (w),
+	execute (or access for directories) (x), execute  only  if  the  file  is a directory or already has execute
+	permission for some user (X), set user (SUID) or group ID (SGID) on execution (s), sticky (t).
+	</para>
+
+	<para>
+<indexterm><primary>sticky bit</primary></indexterm>
+<indexterm><primary>unlinked</primary></indexterm>
+<indexterm><primary>/tmp</primary></indexterm>
+<indexterm><primary>world-writable</primary></indexterm>
+	When the sticky bit is set on a directory, files in that directory may be unlinked (deleted) or renamed only by root or their owner. 
+	Without the sticky  bit, anyone able to write to the directory can delete or rename files. The sticky bit is commonly found on
+	directories, such as <filename>/tmp</filename>, that are world-writable.
+	</para>
+
+	<para>
+<indexterm><primary>write</primary></indexterm>
+<indexterm><primary>read</primary></indexterm>
+<indexterm><primary>setting up directories</primary></indexterm>
+<indexterm><primary>set user id</primary><see>SUID</see></indexterm>
+<indexterm><primary>set group id</primary><see>SGID</see></indexterm>
+	When the set user or group ID bit (s) is set on a directory, then all files created within it will be owned by the user and/or
+	group whose `set user or group' bit is set. This can be helpful in setting up directories for which it is desired that
+	all users who are in a group should be able to write to and read from a file, particularly when it is undesirable for that file
+	to be exclusively owned by a user whose primary group is not the group that all such users belong to.
+	</para>
+
+	<para>
+	When a directory is set <constant>d-wx--x---</constant>, the owner can read and create (write) files in it, but because
+	the (r) read flags are not set, files cannot be listed (seen) in the directory by anyone. The group can read files in the
+	directory but cannot create new files. If files in the directory are set to be readable and writable for the group, then
+	group members will be able to write to (or delete) them.
+	</para>
+
+	<sect3>
+	<title>Protecting Directories and Files from Deletion</title>
+
+	<para>
+<indexterm><primary>protect files</primary></indexterm>
+<indexterm><primary>protect directories</primary></indexterm>
+<indexterm><primary>access controls</primary></indexterm>
+<indexterm><primary>capability to delete</primary></indexterm>
+	People have asked on the Samba mailing list how is it possible to protect files or directories from deletion by users.
+	For example, Windows NT/2K/XP provides the capacity to set access controls on a directory into which people can
+	write files but not delete them. It is possible to set an ACL on a Windows file that permits the file to be written to
+	but not deleted. Such concepts are foreign to the UNIX operating system file space. Within the UNIX file system
+	anyone who has the ability to create a file can write to it. Anyone who has write permission on the
+	directory that contains a file and has write permission for it has the capability to delete it.
+	</para>
+
+	<para>
+<indexterm><primary>directory permissions</primary></indexterm>
+<indexterm><primary>delete a file</primary></indexterm>
+<indexterm><primary>write access</primary></indexterm>
+	For the record, in the UNIX environment the ability to delete a file is controlled by the permissions on
+	the directory that the file is in. In other words, a user can delete a file in a directory to which that
+	user has write access, even if that user does not own the file.
+	</para>
+	
+	<para>
+<indexterm><primary>file system capabilities</primary></indexterm>
+<indexterm><primary>inheritance</primary></indexterm>
+<indexterm><primary>POSIX ACLs</primary></indexterm>
+<indexterm><primary>extended attributes</primary></indexterm>
+	Of necessity, Samba is subject to the file system semantics of the host operating system. Samba is therefore
+	limited in the file system capabilities that can be made available through Windows ACLs, and therefore performs
+	a "best fit" translation to POSIX ACLs. Some UNIX file systems do, however support, a feature known
+	as extended attributes. Only the Windows concept of <emphasis>inheritance</emphasis> is implemented by Samba through
+	the appropriate extended attribute.
+	</para>	
+
+	<para>
+<indexterm><primary>extended attributes</primary></indexterm>
+<indexterm><primary>immutible</primary></indexterm>
+<indexterm><primary>chattr</primary></indexterm>
+<indexterm><primary>CAP_LINUX_IMMUTABLE</primary></indexterm>
+	The specific semantics of the extended attributes are not consistent across UNIX and UNIX-like systems such as Linux.
+	For example, it is possible on some implementations of the extended attributes to set a flag that prevents the directory
+	or file from being deleted. The extended attribute that may achieve this is called the <constant>immutible</constant> bit.
+	Unfortunately, the implementation of the immutible flag is NOT consistent with published documentation. For example, the
+	man page for the <command>chattr</command> on SUSE Linux 9.2 says:
+<screen>
+A file with the i attribute cannot be modified: it cannot be deleted
+or renamed, no link can be created to this file and no data can be
+written to the file. Only the superuser or a process possessing the
+CAP_LINUX_IMMUTABLE capability can set or clear this attribute.
+</screen>
+	A simple test can be done to check if the immutible flag is supported on files in the file system of the Samba host
+	server.
+	</para>
+
+	<procedure>
+	<title>Test for File Immutibility Support</title>
+
+	<step><para>
+	Create a file called <filename>filename</filename>.
+	</para></step>
+
+	<step><para>
+	Login as the <constant>root</constant> user, then set the immutibile flag on a test file as follows:
+<screen>
+&rootprompt; chattr +i `filename'
+</screen>
+	</para></step>
+
+	<step><para>
+	Login as the user who owns the file (not root) and attempt to remove the file as follows:
+<screen>
+mystic:/home/hannibal > rm filename
+</screen>
+	It will not be possible to delete the file if the immutible flag is correctly honored.
+	</para></step>
+	</procedure>
+
+	<para>
+	On operating systems and file system types that support the immutible bit, it is possible to create directories
+	that cannot be deleted. Check the man page on your particular host system to determine whether or not
+	immutable directories are writable. If they are not, then the entire directory and its contents will effectively
+	be protected from writing (file creation also) and deletion.
+	</para>
+
+	</sect3>
+
+	</sect2>
+
+</sect1>
+
+<sect1>
+<title>Share Definition Access Controls</title>
+
+
+	<para>
+	<indexterm><primary>permissions</primary><secondary>share</secondary></indexterm>
+	The following parameters in the &smb.conf; file sections define a share control or affect access controls.
+	Before using any of the following options, please refer to the man page for &smb.conf;.
+	</para>
+
+	<sect2>
+	<title>User- and Group-Based Controls</title>
+
+	<para>
+	User- and group-based controls can prove quite useful. In some situations it is distinctly desirable to
+	force all file system operations as if a single user were doing so. The use of the
+	<smbconfoption name="force user"/> and <smbconfoption name="force group"/> behavior will achieve this.
+	In other situations it may be necessary to use a paranoia level of control to ensure that only particular
+	authorized persons will be able to access a share or its contents. Here the use of the
+	<smbconfoption name="valid users"/> or the <smbconfoption name="invalid users"/> parameter may be useful.
+	</para>
+
+	<para>
+	As always, it is highly advisable to use the easiest to maintain and the least ambiguous method for
+	controlling access. Remember, when you leave the scene, someone else will need to provide assistance, and
+	if he or she finds too great a mess or does not understand what you have done, there is risk of
+	Samba being removed and an alternative solution being adopted.
+	</para>
+
+	<para>
+	<link linkend="ugbc">User and Group Based Controls</link> enumerates these controls.
+	</para>
+
+	<table frame='all' pgwide='0' id="ugbc"><title>User- and Group-Based Controls</title>
+	<tgroup cols='2'>
+		<colspec align="left"/>
+		<colspec align="justify" colwidth="1*"/>
+		<thead>
+		<row>
+			<entry align="center">Control Parameter</entry>
+			<entry align="center">Description, Action, Notes</entry>
+		</row>
+		</thead>
+		<tbody>
+		<row>
+			<entry><smbconfoption name="admin users"/></entry>
+			<entry><para>
+			List of users who will be granted administrative privileges on the share.
+			They will do all file operations as the superuser (root). 
+			Users in this list will be able to do anything they like on the share,
+			irrespective of file permissions.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="force group"/></entry>
+			<entry><para>
+			Specifies a UNIX group name that will be assigned as the default primary group
+			for all users connecting to this service.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="force user"/></entry>
+			<entry><para>
+			Specifies a UNIX username that will be assigned as the default user for all users connecting to this service.
+			This is useful for sharing files. Incorrect use can cause security problems.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="guest ok"/></entry>
+			<entry><para>
+			If this parameter is set for a service, then no password is required to connect to the service. Privileges will be 
+			those of the  guest account.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="invalid users"/></entry>
+			<entry><para>
+			List of users that should not be allowed to login to this service.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="only user"/></entry>
+			<entry><para>
+			Controls whether connections with usernames not in the user list will be allowed.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="read list"/></entry>
+			<entry><para>
+			List of users that are given read-only access to a service. Users in this list
+			will not be given write access, no matter what the  read-only  option is set to. 
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="username"/></entry>
+			<entry><para>
+			Refer to the &smb.conf; man page for more information; this is a complex and potentially misused parameter.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="valid users"/></entry>
+			<entry><para>
+			List of users that should be allowed to login to this service.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="write list"/></entry>
+			<entry><para>
+			List of users that are given read-write access to a service.
+			</para></entry>
+		</row>
+		</tbody>
+	</tgroup>
+	</table>
+
+	</sect2>
+
+	<sect2>
+	<title>File and Directory Permissions-Based Controls</title>
+
+	<para>
+	Directory permission-based controls, if misused, can result in considerable difficulty in diagnosing the causes of 
+	misconfiguration. Use them sparingly and carefully. By gradually introducing each, one at a time, undesirable side 
+	effects may be detected. In the event of a problem, always comment all of them out and then gradually reintroduce 
+	them in a controlled way.
+	</para>
+
+	<para>
+	Refer to <link linkend="fdpbc">File and Directory Permission Based Controls</link> for information 
+	regarding the parameters that may be used to set file and directory permission-based access controls.
+	</para>
+
+	<table frame='all' id="fdpbc"><title>File and Directory Permission-Based Controls</title>
+		<tgroup cols='2'>
+			<colspec align="left"/>
+			<colspec align="justify" colwidth="1*"/>
+		<thead>
+		<row>
+			<entry align="center">Control Parameter</entry>
+			<entry align="center">Description, Action, Notes</entry>
+		</row>
+		</thead>
+		<tbody>
+		<row>
+			<entry><smbconfoption name="create mask"/></entry>
+			<entry><para>
+			Refer to the &smb.conf; man page.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="directory mask"/></entry>
+			<entry><para>
+			The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories.
+			See also directory security mask.
+			</para></entry></row>
+		<row>
+			<entry><smbconfoption name="dos filemode"/></entry>
+			<entry><para>
+			Enabling this parameter allows a user who has write access to the file to modify the permissions on it.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="force create mode"/></entry>
+			<entry><para>
+			This parameter specifies a set of UNIX-mode bit permissions that will always be set on a file created by Samba.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="force directory mode"/></entry>
+			<entry><para>
+			This parameter specifies a set of UNIX-mode bit permissions that will always be set on a directory created by Samba.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="force directory security mode"/></entry>
+			<entry><para>
+			Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="force security mode"/></entry>
+			<entry><para>
+			Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="hide unreadable"/></entry>
+			<entry><para>
+			Prevents clients from seeing the existence of files that cannot be read.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="hide unwriteable files"/></entry>
+			<entry><para>
+			Prevents clients from seeing the existence of files that cannot be written to. Unwritable directories are shown as usual. 
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="nt acl support"/></entry>
+			<entry><para>
+			This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT ACLs.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="security mask"/></entry>
+			<entry><para>
+			Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file.
+			</para></entry>
+		</row>
+		</tbody>
+	</tgroup>
+	</table>
+
+	</sect2>
+
+	<sect2>
+	<title>Miscellaneous Controls</title>
+
+	<para>
+	The parameter documented in <link linkend="mcoc">Other Controls</link> are often used by administrators 
+	in ways that create inadvertent barriers to file access. Such are the consequences of not understanding the 
+	full implications of &smb.conf; file settings.
+	</para>
+
+	<table frame='all' id="mcoc"><title>Other Controls</title>
+	<tgroup cols='2'>
+		<colspec align="justify" colwidth="1*"/>
+		<colspec align="justify" colwidth="1*"/>
+		<thead>
+		<row>
+			<entry align="center">Control Parameter</entry>
+			<entry align="center">Description, Action, Notes</entry>
+		</row>
+		</thead>
+		<tbody>
+		<row>
+			<entry>
+			<smbconfoption name="case sensitive"/>,
+			<smbconfoption name="default case"/>,
+			<smbconfoption name="short preserve case"/>
+			</entry>
+			<entry><para>
+			This means that all file name lookup will be done in a case-sensitive manner. 
+			Files will be created with the precise file name Samba received from the MS Windows client.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="csc policy"/></entry>
+			<entry><para>
+			Client-side caching policy parallels MS Windows client-side file caching capabilities.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="dont descend"/></entry>
+			<entry><para>
+			Allows specifying a comma-delimited list of directories that the server should always show as empty.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="dos filetime resolution"/></entry>
+			<entry><para>
+			This option is mainly used as a compatibility option for Visual C++ when used against Samba shares.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="dos filetimes"/></entry>
+			<entry><para>
+			DOS and Windows allow users to change file timestamps if they can write to the file. POSIX semantics prevent this.
+			This option allows DOS and Windows behavior.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="fake oplocks"/></entry>
+			<entry><para>
+			Oplocks are the way that SMB clients get permission from a server to locally cache file operations. If a server grants an
+			oplock, the client is free to assume that it is the only one accessing the file, and it will aggressively cache file data.
+			</para></entry>
+		</row>
+		<row>
+			<entry>
+			<smbconfoption name="hide dot files"/>,
+			<smbconfoption name="hide files"/>,
+			<smbconfoption name="veto files"/>
+			</entry>
+			<entry><para>
+			Note: MS Windows Explorer allows override of files marked as hidden so they will still be visible.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="read only"/></entry>
+			<entry><para>
+			If this parameter is yes, then users of a service may not create or modify files in the service's directory.
+			</para></entry>
+		</row>
+		<row>
+			<entry><smbconfoption name="veto files"/></entry>
+			<entry><para>
+			List of files and directories that are neither visible nor accessible.
+			</para></entry>
+		</row>
+		</tbody>
+	</tgroup>
+	</table>
+
+	</sect2>
+
+</sect1>
+
+<sect1>
+<title>Access Controls on Shares</title>
+
+
+	<para>
+<indexterm><primary>per-share access control</primary></indexterm>
+<indexterm><primary>Everyone - Full Control</primary></indexterm>
+<indexterm><primary>specific restrictions</primary></indexterm>
+<indexterm><primary>share access</primary></indexterm>
+	<indexterm><primary>permissions</primary><secondary>share ACLs</secondary></indexterm>
+	This section deals with how to configure Samba per-share access control restrictions.
+	By default, Samba sets no restrictions on the share itself. Restrictions on the share itself
+	can be set on MS Windows NT4/200x/XP shares. This can be an effective way to limit who can
+	connect to a share. In the absence of specific restrictions, the default setting is to allow
+	the global user <constant>Everyone - Full Control</constant> (full control, change and read).
+	</para>
+
+	<para>
+<indexterm><primary>access control</primary></indexterm>
+<indexterm><primary>MMC</primary></indexterm>
+<indexterm><primary>Computer Management</primary></indexterm>
+	At this time Samba does not provide a tool for configuring access control settings on the share
+	itself the only way to create those settings is to use either the NT4 Server Manager or the Windows 200x
+	Microsoft Management Console (MMC) for Computer Management. There are currently no plans to provide
+	this capability in the Samba command-line tool set.
+	</para>
+
+	<para>
+<indexterm><primary>share_info.tdb</primary></indexterm>
+<indexterm><primary>/usr/local/samba/var</primary></indexterm>
+<indexterm><primary>tdbdump</primary></indexterm>
+<indexterm><primary>tdb files</primary></indexterm>
+	Samba stores the per-share access control settings in a file called <filename>share_info.tdb</filename>.
+	The location of this file on your system will depend on how Samba was compiled. The default location
+	for Samba's tdb files is under <filename>/usr/local/samba/var</filename>. If the <filename>tdbdump</filename>
+	utility has been compiled and installed on your system, then you can examine the contents of this file
+	by executing <command>tdbdump share_info.tdb</command> in the directory containing the tdb files.
+	</para>
+
+	<sect2>
+	<title>Share Permissions Management</title>
+
+		<para>
+		The best tool for share permissions management is platform-dependent. Choose the best tool for your environment.
+		</para>
+
+			<sect3>
+			<title>Windows NT4 Workstation/Server</title>
+			<para>
+<indexterm><primary>manage share permissions</primary></indexterm>
+<indexterm><primary>share permissions</primary></indexterm>
+<indexterm><primary>NT Server Manager</primary></indexterm>
+<indexterm><primary>Windows NT4</primary></indexterm>
+			The tool you need to manage share permissions on a Samba server from a Windows NT4 Workstation or Server
+			is the NT Server Manager.  Server Manager is shipped with Windows NT4 Server products but not with Windows
+			NT4 Workstation.  You can obtain the NT Server Manager for MS Windows NT4 Workstation from the Microsoft
+			web site <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;173673">support</ulink> section.
+			</para>
+
+			<procedure>
+			<title>Instructions</title>
+
+			<step><para>
+			Launch the <application>NT4 Server Manager</application> and click on the Samba server you want to
+			administer. From the menu select <guimenu>Computer</guimenu>, then click on
+			<guimenuitem>Shared Directories</guimenuitem>.
+			</para></step>
+
+			<step><para>
+			Click on the share that you wish to manage and click the <guilabel>Properties</guilabel> tab, then click
+			the <guilabel>Permissions</guilabel> tab. Now you can add or change access control settings as you wish.
+			</para></step>
+			</procedure>
+
+			</sect3>
+
+			<sect3>
+			<title>Windows 200x/XP</title>
+
+			<para>
+<indexterm><primary>Windows NT4/200x/XP</primary></indexterm>
+<indexterm><primary>ACLs on share</primary></indexterm>
+<indexterm><primary>Sharing</primary></indexterm>
+<indexterm><primary>Permissions</primary></indexterm>
+			On <application>MS Windows NT4/200x/XP</application> system, ACLs on the share itself are set using native
+			tools, usually from File Manager. For example, in Windows 200x, right-click on the shared folder,
+			then select <guimenuitem>Sharing</guimenuitem>, then click on <guilabel>Permissions</guilabel>. The default 
+			Windows NT4/200x permission allows "Everyone" full control on the share.
+			</para>
+
+			<para>
+<indexterm><primary>Computer Management</primary></indexterm>
+<indexterm><primary>MMC</primary></indexterm>
+<indexterm><primary>tool</primary></indexterm>
+			MS Windows 200x and later versions come with a tool called the <application>Computer Management</application>
+			snap-in for the MMC. This tool is located by clicking on <guimenu>Control Panel ->
+			Administrative Tools -> Computer Management</guimenu>.
+			</para>
+
+			<procedure>
+			<title>Instructions</title>
+			<step><para>
+			After launching the MMC with the Computer Management snap-in, click the menu item <guimenuitem>Action</guimenuitem>
+			and select <guilabel>Connect to another computer</guilabel>. If you are not logged onto a domain you will be prompted
+			to enter a domain login user identifier and a password. This will authenticate you to the domain.
+			If you are already logged in with administrative privilege, this step is not offered.
+			</para></step>
+
+			<step><para>
+			If the Samba server is not shown in the <guilabel>Select Computer</guilabel> box, type in the name of the target
+			Samba server in the field <guilabel>Name:</guilabel>. Now click the on <guibutton>[+]</guibutton> next to 
+			<guilabel>System Tools</guilabel>, then on the <guibutton>[+]</guibutton> next to
+			<guilabel>Shared Folders</guilabel> in the left panel.
+			</para></step>
+
+			<step><para>
+<indexterm><primary>Share Permissions</primary></indexterm>
+			In the right panel, double-click on the share on which you wish to set access control permissions.
+			Then click the tab <guilabel>Share Permissions</guilabel>. It is now possible to add access control entities
+			to the shared folder. Remember to set what type of access (full control, change, read) you
+			wish to assign for each entry.
+			</para></step>
+			</procedure>
+
+			<warning>
+			<para>
+			Be careful. If you take away all permissions from the <constant>Everyone</constant> user without removing
+			this user, effectively no user will be able to access the share. This is a result of what is known as
+			ACL precedence. Everyone with <emphasis>no access</emphasis> means that <constant>MaryK</constant> who is
+			part of the group <constant>Everyone</constant> will have no access even if she is given explicit full
+			control access.
+			</para>
+			</warning>
+
+			</sect3>
+		</sect2>
+
+</sect1>
+
+<sect1>
+<title>MS Windows Access Control Lists and UNIX Interoperability</title>
+
+	<sect2>
+		<title>Managing UNIX Permissions Using NT Security Dialogs</title>
+
+
+		<para>
+		<indexterm><primary>permissions</primary><secondary>file/directory ACLs</secondary></indexterm>
+		Windows NT clients can use their native security settings dialog box to view and modify the
+		underlying UNIX permissions.
+		</para>
+
+		<para>
+		This ability is careful not to compromise the security of the UNIX host on which Samba is running and 
+		still obeys all the file permission rules that a Samba administrator can set.
+		</para>
+
+		<para>
+		Samba does not attempt to go beyond POSIX ACLs, so the various finer-grained access control
+		options provided in Windows are actually ignored.
+		</para> 
+
+		<note>
+		<para>
+		All access to UNIX/Linux system files via Samba is controlled by the operating system file access controls.
+		When trying to figure out file access problems, it is vitally important to find the identity of the Windows
+		user as it is presented by Samba at the point of file access. This can best be determined from the
+		Samba log files.
+		</para>
+		</note>
+	</sect2>
+
+	<sect2>
+		<title>Viewing File Security on a Samba Share</title>
+
+		<para>
+		From an NT4/2000/XP client, right-click on any file or directory in a Samba-mounted drive letter
+		or UNC path. When the menu pops up, click on the <guilabel>Properties</guilabel> entry at the bottom
+		of the menu. This brings up the file <constant>Properties</constant> dialog box. Click on the 
+		<guilabel>Security</guilabel> tab and you will see three buttons: <guibutton>Permissions</guibutton>,
+		<guibutton>Auditing</guibutton>, and <guibutton>Ownership</guibutton>. The <guibutton>Auditing</guibutton>
+		button will cause either an error message <errorname>"A requested privilege is not held by the client"</errorname>
+		to appear if the user is not the NT administrator, or a dialog intended to allow an administrator
+		to add auditing requirements to a file if the user is logged on as the NT administrator. This dialog is
+		nonfunctional with a Samba share at this time, because the only useful button, the <guibutton>Add</guibutton>
+		button, will not currently allow a list of users to be seen.
+		</para>
+
+	</sect2>
+
+	<sect2>
+		<title>Viewing File Ownership</title>
+
+		<para>
+		Clicking on the <guibutton>Ownership</guibutton> button brings up a dialog box telling you who owns
+		the given file. The owner name will be displayed like this:
+		<screen>
+		<constant>SERVER\user (Long name)</constant>
+		</screen>
+		<replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server, <replaceable>user</replaceable>
+		is the username of the UNIX user who owns the file, and <replaceable>(Long name)</replaceable> is the
+		descriptive string identifying the user (normally found in the GECOS field of the UNIX password database).
+		Click on the <guibutton>Close</guibutton> button to remove this dialog.
+		</para>
+
+		<para>
+		If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>,
+		the file owner will be shown as the NT user <emphasis>Everyone</emphasis>.
+		</para>
+
+		<para>
+<indexterm><primary>Take Ownership</primary></indexterm>
+		The <guibutton>Take Ownership</guibutton> button will not allow you to change the ownership of this file to
+		yourself (clicking it will display a dialog box complaining that the user as whom you are currently logged onto
+		the NT client cannot be found). The reason for this is that changing the ownership of a file is a privileged
+		operation in UNIX, available only to the <emphasis>root</emphasis> user. Because clicking on this button causes
+		NT to attempt to change the ownership of a file to the current user logged into the NT client, this will
+		not work with Samba at this time.
+		</para>
+
+		<para>
+<indexterm><primary>chown</primary></indexterm>
+<indexterm><primary>ownership</primary></indexterm>
+<indexterm><primary>Seclib</primary></indexterm>
+		There is an NT <command>chown</command> command that will work with Samba and allow a user with administrator
+		privilege connected to a Samba server as root to change the ownership of files on both a local NTFS file system
+		or remote mounted NTFS or Samba drive. This is available as part of the <application>Seclib</application> NT
+		security library written by Jeremy Allison of the Samba Team and is downloadable from the main Samba FTP site.
+		</para>
+
+	</sect2>
+
+	<sect2>
+		<title>Viewing File or Directory Permissions</title>
+
+		<para>
+		The third button is the <guibutton>Permissions</guibutton> button. Clicking on it brings up a dialog box
+		that shows both the permissions and the UNIX owner of the file or directory. The owner is displayed like this:
+		</para>
+
+		<para><command><replaceable>SERVER</replaceable>\
+				<replaceable>user</replaceable> 
+				<replaceable>(Long name)</replaceable></command></para>
+
+		<para><replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server,
+		<replaceable>user</replaceable> is the username of the UNIX user who owns the file, and
+		<replaceable>(Long name)</replaceable> is the descriptive string identifying the user (normally found in the
+		GECOS field of the UNIX password database).</para>
+
+		<para>
+		If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>,
+		the file owner will be shown as the NT user <constant>Everyone</constant>, and the permissions will be
+		shown as NT <emphasis>Full Control</emphasis>.
+		</para>
+
+
+		<para>
+		The permissions field is displayed differently for files and directories. Both are discussed next.
+		</para>
+
+		<sect3>
+		<title>File Permissions</title>
+
+		<para>
+		The standard UNIX user/group/world triplet and the corresponding <constant>read, write,
+		execute</constant> permissions triplets are mapped by Samba into a three-element NT ACL with the
+		<quote>r</quote>, <quote>w</quote>, and <quote>x</quote> bits mapped into the corresponding NT
+		permissions. The UNIX world permissions are mapped into the global NT group <constant>Everyone</constant>, followed 
+		by the list of permissions allowed for the UNIX world. The UNIX owner and group permissions are displayed as an NT 
+		<guiicon>user</guiicon> icon and an NT <guiicon>local group</guiicon> icon, respectively, followed by the list 
+		of permissions allowed for the UNIX user and group.
+		</para>
+
+		<para>
+		Because many UNIX permission sets do not map into common NT names such as <constant>read</constant>,
+		<constant>change</constant>, or <constant>full control</constant>, usually the permissions will be prefixed
+		by the words <constant>Special Access</constant> in the NT display list.
+		</para>
+
+		<para>
+		But what happens if the file has no permissions allowed for a particular UNIX user group or world component?
+		In order to  allow <emphasis>no permissions</emphasis> to be seen and modified, Samba then overloads the NT
+		<constant>Take Ownership</constant> ACL attribute (which has no meaning in UNIX) and reports a component with
+		no permissions as having the NT <command>O</command> bit set.  This was chosen, of course, to make it look
+		like a zero, meaning zero permissions. More details on the decision behind this action are given below.
+		</para>
+
+		</sect3>
+		
+		<sect3>
+		<title>Directory Permissions</title>
+
+		<para>
+		Directories on an NT NTFS file system have two different sets of permissions. The first set is the ACL set on the
+		directory itself, which is usually displayed in the first set of parentheses in the normal <constant>RW</constant> 
+		NT style. This first set of permissions is created by Samba in exactly the same way as normal file permissions are, described 
+		above, and is displayed in the same way.
+		</para>
+
+		<para>
+		The second set of directory permissions has no real meaning in the UNIX permissions world and represents the <constant>
+		inherited</constant> permissions that any file created within this directory would inherit.
+		</para>
+
+		<para>
+		Samba synthesizes these inherited permissions for NT by returning as an NT ACL the UNIX permission mode that a new file 
+		created by Samba on this share would receive.
+		</para>
+
+		</sect3>
+
+	</sect2>
+		
+	<sect2>
+	<title>Modifying File or Directory Permissions</title>
+
+	<para>
+	Modifying file and directory permissions is as simple as changing the displayed permissions in the dialog box
+	and clicking on <guibutton>OK</guibutton>. However, there are limitations that a user needs to be aware of,
+	and also interactions with the standard Samba permission masks and mapping of DOS attributes that also need to
+	be taken into account.
+	</para>
+
+	<para>
+	If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>, any attempt to
+	set security permissions will fail with an <errorname>"Access Denied" </errorname> message.
+	</para>
+
+	<para>
+	The first thing to note is that the <guibutton>Add</guibutton> button will not return a list of users in Samba
+	(it will give an error message saying <errorname>"The remote procedure call failed and did not
+	execute"</errorname>). This means that you can only manipulate the current user/group/world permissions listed
+	in the dialog box. This actually works quite well because these are the only permissions that UNIX actually
+	has.
+	</para>
+
+	<para>
+	If a permission triplet (either user, group, or world) is removed from the list of permissions in the NT
+	dialog box, then when the <guibutton>OK</guibutton> button is pressed, it will be applied as <emphasis>no
+	permissions</emphasis> on the UNIX side. If you view the permissions again, the <emphasis>no
+	permissions</emphasis> entry will appear as the NT <command>O</command> flag, as described above. This allows
+	you to add permissions back to a file or directory once you have removed them from a triplet component.
+	</para>
+
+	<para>
+	Because UNIX supports only the <quote>r</quote>, <quote>w</quote>, and <quote>x</quote> bits of an NT ACL, if
+	other NT security attributes such as <constant>Delete Access</constant> are selected, they will be ignored
+	when applied on the Samba server.
+	</para>
+
+	<para>
+	When setting permissions on a directory, the second set of permissions (in the second set of parentheses) is
+	by default applied to all files within that directory. If this is not what you want, you must uncheck the
+	<guilabel>Replace permissions on existing files</guilabel> checkbox in the NT dialog before clicking on
+	<guibutton>OK</guibutton>.
+	</para>
+
+	<para>
+	If you wish to remove all permissions from a user/group/world  component, you may either highlight the
+	component and click on the <guibutton>Remove</guibutton> button or set the component to only have the special
+	<constant>Take Ownership</constant> permission (displayed as <command>O</command>) highlighted.
+	</para>
+
+	</sect2>
+
+<?latex \newpage ?>
+	<sect2>
+	<title>Interaction with the Standard Samba <quote>create mask</quote> Parameters</title>
+
+	<para>There are four parameters that control interaction with the standard Samba <parameter>create mask</parameter> parameters:
+	
+
+	<itemizedlist>
+		<listitem><para><smbconfoption name="security mask"/></para></listitem>
+		<listitem><para><smbconfoption name="force security mode"/></para></listitem>
+		<listitem><para><smbconfoption name="directory security mask"/></para></listitem>
+		<listitem><para><smbconfoption name="force directory security mode"/></para></listitem>
+	</itemizedlist>
+
+	</para>
+
+	<para>
+	When a user clicks on <guibutton>OK</guibutton> to apply the 
+	permissions, Samba maps the given permissions into a user/group/world 
+	r/w/x triplet set, and then checks the changed permissions for a 
+	file against the bits set in the  
+	<smbconfoption name="security mask"/> parameter. Any bits that 
+	were changed that are not set to <emphasis>1</emphasis> in this parameter are left alone 
+	in the file permissions.</para>
+
+	<para>
+	Essentially, zero bits in the <smbconfoption name="security mask"/>
+	may be treated as a set of bits the user is <emphasis>not</emphasis> 
+	allowed to change, and one bits are those the user is allowed to change.
+	</para>
+
+	<para>
+	If not explicitly set, this parameter defaults to the same value as 
+	the <smbconfoption name="create mask"/> parameter. To allow a user to modify all the
+	user/group/world permissions on a file, set this parameter to 0777.
+	</para>
+
+	<para>
+	Next Samba checks the changed permissions for a file against the bits set in the 
+	<smbconfoption name="force security mode"/> parameter. Any bits 
+	that were changed that correspond to bits set to <emphasis>1</emphasis> in this parameter 
+	are forced to be set.</para>
+
+	<para>
+	Essentially, bits set in the <parameter>force security mode</parameter> parameter
+	may be treated as a set of bits that, when modifying security on a file, the user 
+	has always set to be <emphasis>on</emphasis>.</para>
+
+	<para>
+	If not explicitly set, this parameter defaults to the same value 
+	as the <smbconfoption name="force create mode"/> parameter.
+	To allow a user to modify all the user/group/world permissions on a file
+	with no restrictions, set this parameter to 000. The
+	<smbconfoption name="security mask"/> and <parameter>force 
+	security mode</parameter> parameters are applied to the change 
+	request in that order.</para>
+
+	<para>
+	For a directory, Samba performs the same operations as 
+	described above for a file except it uses the parameter <parameter>
+	directory security mask</parameter> instead of <parameter>security 
+	mask</parameter>, and <parameter>force directory security mode
+	</parameter> parameter instead of <parameter>force security mode
+	</parameter>.</para>
+
+	<para>
+	The <smbconfoption name="directory security mask"/> parameter 
+	by default is set to the same value as the <parameter>directory mask
+	</parameter> parameter and the <parameter>force directory security 
+	mode</parameter> parameter by default is set to the same value as 
+	the <smbconfoption name="force directory mode"/> parameter.
+	In this way Samba enforces the permission restrictions that 
+	an administrator can set on a Samba share, while still allowing users 
+	to modify the permission bits within that restriction.</para>
+
+	<para>
+	If you want to set up a share that allows users full control
+	in modifying the permission bits on their files and directories and
+	does not force any particular bits to be set <emphasis>on</emphasis>,
+	then set the following parameters in the &smb.conf; file in that
+	share-specific section:
+	</para>
+
+<?latex \newpage ?>
+	<smbconfblock>
+		<smbconfoption name="security mask">0777</smbconfoption>
+		<smbconfoption name="force security mode">0</smbconfoption>
+		<smbconfoption name="directory security mask">0777</smbconfoption>
+		<smbconfoption name="force directory security mode">0</smbconfoption>
+	</smbconfblock>
+
+</sect2>
+
+<sect2>
+	<title>Interaction with the Standard Samba File Attribute Mapping</title>
+
+	<note>
+	<para>
+	Samba maps some of the DOS attribute bits (such as <quote>read-only</quote>)
+	into the UNIX permissions of a file. This means there can 
+	be a conflict between the permission bits set via the security 
+	dialog and the permission bits set by the file attribute mapping.
+	</para>
+	</note>
+
+	<para>
+	If a file has no UNIX read access for the owner, it will show up
+	as <quote>read-only</quote> in the standard file attributes tabbed dialog.
+	Unfortunately, this dialog is the same one that contains the security information
+	in another tab.
+	</para>
+
+	<para>
+	What this can mean is that if the owner changes the permissions
+	to allow himself or herself read access using the security dialog, clicks on
+	<guibutton>OK</guibutton> to get back to the standard attributes tab 
+	dialog, and clicks on <guibutton>OK</guibutton> on that dialog, then 
+	NT will set the file permissions back to read-only (as that is what 
+	the attributes still say in the dialog). This means that after setting 
+	permissions and clicking on <guibutton>OK</guibutton> to get back to the 
+	attributes dialog, you should always press <guibutton>Cancel</guibutton> 
+	rather than <guibutton>OK</guibutton> to ensure that your changes 
+	are not overridden.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Windows NT/200X ACLs and POSIX ACLs Limitations</title>
+
+	<para>
+	Windows administrators are familiar with simple ACL controls, and they typically
+	consider that UNIX user/group/other (ugo) permissions are inadequate and not
+	sufficiently fine-grained.
+	</para>
+
+	<para>
+	Competing SMB implementations differ in how they handle Windows ACLs. Samba handles
+	Windows ACLs from the perspective of UNIX file system administration and thus adopts
+	the limitations of POSIX ACLs. Therefore, where POSIX ACLs lack a capability of the
+	Windows NT/200X ACLs, the POSIX semantics and limitations are imposed on the Windows
+	administrator.
+	</para>
+
+	<para>
+	POSIX ACLs present an interesting challenge to the UNIX administrator and therefore
+	force a compromise to be applied to Windows ACLs administration. POSIX ACLs are not
+	covered by an official standard; rather, the latest standard is a draft standard
+	1003.1e revision 17. This is the POSIX document on which the Samba implementation has
+	been implemented.
+	</para>
+
+	<para>
+	UNIX vendors differ in the manner in which POSIX ACLs are implemented. There are a
+	number of Linux file systems that support ACLs. Samba has to provide a way to make
+	transparent all the differences between the various implementations of POSIX ACLs.
+	The pressure for ACLs support in Samba has noticeably increased the pressure to
+	standardize ACLs support in the UNIX world.
+	</para>
+
+	<para>
+	Samba has to deal with the complicated matter of handling the challenge of the Windows
+	ACL that implements <emphasis>inheritance</emphasis>, a concept not anticipated by POSIX
+	ACLs as implemented in UNIX file systems. Samba provides support for <emphasis>masks</emphasis>
+	that permit normal ugo and ACLs functionality to be overrided. This further complicates
+	the way in which Windows ACLs must be implemented.
+	</para>
+
+	<sect3>
+	<title>UNIX POSIX ACL Overview</title>
+
+	<para>
+	In examining POSIX ACLs we must consider the manner in which they operate for 
+	both files and directories. File ACLs have the following significance:
+<screen>
+# file: testfile      &lt;- the file name
+# owner: jeremy       &lt;-- the file owner
+# group: users        &lt;-- the POSIX group owner
+user::rwx             &lt;-- perms for the file owner (user)
+user:tpot:r-x         &lt;-- perms for the additional user `tpot'
+group::r--            &lt;-- perms for the file group owner (group)
+group:engrs:r--       &lt;-- perms for the additonal group `engineers'
+mask:rwx              &lt;-- the mask that is `ANDed' with groups
+other::---            &lt;-- perms applied to everyone else (other)
+</screen>
+	Directory ACLs have the following signficance:
+<screen>
+# file: testdir       &lt;-- the directory name
+# owner: jeremy       &lt;-- the directory owner
+# group: jeremy       &lt;-- the POSIX group owner
+user::rwx             &lt;-- directory perms for owner (user)
+group::rwx            &lt;-- directory perms for owning group (group)
+mask::rwx             &lt;-- the mask that is `ANDed' with group perms
+other:r-x             &lt;-- perms applied to everyone else (other)
+default:user::rwx     &lt;-- inherited owner perms
+default:user:tpot:rwx &lt;-- inherited extra perms for user `tpot'
+default:group::r-x    &lt;-- inherited group perms
+default:mask:rwx      &lt;-- inherited default mask
+default:other:---     &lt;-- inherited permissions for everyone (other)
+</screen>
+	</para>
+
+	</sect3>
+
+	<sect3>
+	<title>Mapping of Windows File ACLs to UNIX POSIX ACLs</title>
+
+	<para>
+	Microsoft Windows NT4/200X ACLs must of necessity be mapped to POSIX ACLs.
+	The mappings for file permissions are shown in <link linkend="fdsacls">How
+	Windows File ACLs Map to UNIX POSIX File ACLs</link>.
+	The # character means this flag is set only when the Windows administrator
+	sets the <constant>Full Control</constant> flag on the file.
+	</para>
+
+	<table frame='all' pgwide='0' id="fdsacls"><title>How Windows File ACLs Map to UNIX POSIX File ACLs</title>
+	<tgroup cols='2'>
+		<colspec align="left"/>
+		<colspec align="center"/>
+		<thead>
+		<row>
+			<entry align="left">Windows ACE</entry>
+			<entry align="center">File Attribute Flag</entry>
+		</row>
+		</thead>
+		<tbody>
+		<row>
+			<entry><para>Full Control</para></entry>
+			<entry><para>#</para></entry>
+		</row>
+		<row>
+			<entry><para>Traverse Folder/Execute File</para></entry>
+			<entry><para>x</para></entry>
+		</row>
+		<row>
+			<entry><para>List Folder/Read Data</para></entry>
+			<entry><para>r</para></entry>
+		</row>
+		<row>
+			<entry><para>Read Attributes</para></entry>
+			<entry><para>r</para></entry>
+		</row>
+		<row>
+			<entry><para>Read Extended Attribures</para></entry>
+			<entry><para>r</para></entry>
+		</row>
+		<row>
+			<entry><para>Create Files/Write Data</para></entry>
+			<entry><para>w</para></entry>
+		</row>
+		<row>
+			<entry><para>Create Folders/Append Data</para></entry>
+			<entry><para>w</para></entry>
+		</row>
+		<row>
+			<entry><para>Write Attributes</para></entry>
+			<entry><para>w</para></entry>
+		</row>
+		<row>
+			<entry><para>Write Extended Attributes</para></entry>
+			<entry><para>w</para></entry>
+		</row>
+		<row>
+			<entry><para>Delete Subfolders and Files</para></entry>
+			<entry><para>w</para></entry>
+		</row>
+		<row>
+			<entry><para>Delete</para></entry>
+			<entry><para>#</para></entry>
+		</row>
+		<row>
+			<entry><para>Read Permissions</para></entry>
+			<entry><para>all</para></entry>
+		</row>
+		<row>
+			<entry><para>Change Permissions</para></entry>
+			<entry><para>#</para></entry>
+		</row>
+		<row>
+			<entry><para>Take Ownership</para></entry>
+			<entry><para>#</para></entry>
+		</row>
+		</tbody>
+	</tgroup>
+	</table>
+
+	<para>
+	As can be seen from the mapping table, there is no one-to-one mapping capability, and therefore
+	Samba must make a logical mapping that will permit Windows to operate more-or-less the way
+	that is intended by the administrator.
+	</para>
+
+	<para>
+	In general the mapping of UNIX POSIX user/group/other permissions will be mapped to
+	Windows ACLs. This has precedence over the creation of POSIX ACLs. POSIX ACLs are necessary
+	to establish access controls for users and groups other than the user and group that
+	own the file or directory.
+	</para>
+
+	<para>
+	The UNIX administrator can set any directory permission from within the UNIX environment.
+	The Windows administrator is more restricted in that it is not possible from within 
+	Windows Explorer to remove read permission for the file owner.
+	</para>
+
+	</sect3>
+
+	<sect3>
+	<title>Mapping of Windows Directory ACLs to UNIX POSIX ACLs</title>
+
+	<para>
+	Interesting things happen in the mapping of UNIX POSIX directory permissions and
+	UNIX POSIX ACLs to Windows ACEs (Access Control Entries, the discrete components of
+	an ACL) are mapped to Windows directory ACLs.
+	</para>
+
+	<para>
+	Directory permissions function in much the same way as shown for file permissions, but
+	there are some notable exceptions and a few peculiarities that the astute administrator
+	will want to take into account in the setting up of directory permissions.
+	</para>
+
+	</sect3>
+
+	</sect2>
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+File, directory, and share access problems are common topics on the mailing list. The following
+are examples recently taken from the mailing list.
+</para>
+
+
+	<sect2>
+	<title>Users Cannot Write to a Public Share</title>
+
+	<para>
+	The following complaint has frequently been voiced on the Samba mailing list: 
+	<quote>
+	We are facing some troubles with file/directory permissions. I can log on the domain as admin user (root),
+	and there's a public share on which everyone needs to have permission to create/modify files, but only
+	root can change the file, no one else can. We need to constantly go to the server to
+	<userinput>chgrp -R users *</userinput> and <userinput>chown -R nobody *</userinput> to allow
+	other users to change the file.
+	</quote>
+	</para>
+
+	<para>
+	Here is one way the problem can be solved:
+	</para>
+
+	<procedure>
+		<step>
+			<para>
+			Go to the top of the directory that is shared.
+			</para>
+		</step>
+
+		<step>
+			<para>
+			Set the ownership to whatever public user and group you want
+<screen>
+&prompt;find `directory_name' -type d -exec chown user:group {}\;
+&prompt;find `directory_name' -type d -exec chmod 2775 {}\;
+&prompt;find `directory_name' -type f -exec chmod 0775 {}\;
+&prompt;find `directory_name' -type f -exec chown user:group {}\;
+</screen>
+			</para>
+
+			<note><para>
+			The above will set the <constant>SGID bit</constant> on all directories. Read your
+			UNIX/Linux man page on what that does. This ensures that all files and directories
+			that are created in the directory tree will be owned by the current user and will
+			be owned by the group that owns the directory in which it is created.
+			</para></note>
+		</step>
+		<step>
+			<para>
+			Directory is <replaceable>/foodbar</replaceable>:
+<screen>
+&prompt;<userinput>chown jack:engr /foodbar</userinput>
+</screen>
+			</para>
+
+			<note>
+			<para>This is the same as doing:</para>
+<screen>
+&prompt;<userinput>chown jack /foodbar</userinput>
+&prompt;<userinput>chgrp engr /foodbar</userinput>
+</screen>
+			</note>
+		</step>
+		<step>
+			<para>Now type: 
+
+<screen>
+&prompt;<userinput>chmod 2775 /foodbar</userinput>
+&prompt;<userinput>ls -al /foodbar/..</userinput>
+</screen>
+			</para>
+		
+			<para>You should see:
+<screen>
+drwxrwsr-x  2 jack  engr    48 2003-02-04 09:55 foodbar
+</screen>
+			</para>
+		</step>
+		<step>
+
+		<para>Now type:
+<screen>
+&prompt;<userinput>su - jill</userinput>
+&prompt;<userinput>cd /foodbar</userinput>
+&prompt;<userinput>touch Afile</userinput>
+&prompt;<userinput>ls -al</userinput>
+</screen>
+		</para>
+
+		<para>
+		You should see that the file <filename>Afile</filename> created by Jill will have ownership
+		and permissions of Jack, as follows:
+<screen>
+-rw-r--r--  1 jill  engr     0 2007-01-18 19:41 Afile
+</screen>
+		</para>
+		</step>
+
+		<step>
+		<para>
+		If the user that must have write permission in the directory is not a member of the group
+		<emphasis>engr</emphasis> set in the &smb.conf; entry for the share:
+		<smbconfblock>
+<smbconfoption name="force group">engr</smbconfoption>
+		</smbconfblock>
+		</para>
+	</step>
+	</procedure>
+	</sect2>
+
+
+	<sect2>
+		<title>File Operations Done as <emphasis>root</emphasis> with <emphasis>force user</emphasis> Set</title>
+
+		<para>
+		When you have a user in <smbconfoption name="admin users"/>, Samba will always do file operations for
+		this user as <emphasis>root</emphasis>, even if <smbconfoption name="force user"/> has been set.
+		</para>
+	</sect2>
+	
+	<sect2>
+		<title>MS Word with Samba Changes Owner of File</title>
+
+		<para>
+		<emphasis>Question:</emphasis> <quote>When user B saves a word document that is owned by user A,
+		the updated file is now owned by user B.  Why is Samba doing this? How do I fix this?</quote>
+		</para>
+
+		<para>
+		<emphasis>Answer:</emphasis> Word does the following when you modify/change a Word document: MS Word creates a new document with
+		a temporary name. Word then closes the old document and deletes it, then renames the new document to the original document name.
+		There is no mechanism by which Samba can in any way know that the new document really should be owned by the owners
+		of the original file. Samba has no way of knowing that the file will be renamed by MS Word. As far as Samba is able
+		to tell, the file that gets created is a new file, not one that the application (Word) is updating.
+		</para>
+
+		<para>
+		There is a workaround to solve the permissions problem. It involves understanding how you can manage file
+		system behavior from within the &smb.conf; file, as well as understanding how UNIX file systems work. Set on the directory
+		in which you are changing Word documents: <command>chmod g+s `directory_name'.</command> This ensures that all files will
+		be created with the group that owns the directory. In &smb.conf; share declaration section set:
+		</para>
+
+		<para>
+		<smbconfblock>
+                <smbconfoption name="force create mode">0660</smbconfoption>
+                <smbconfoption name="force directory mode">0770</smbconfoption>
+		</smbconfblock>
+		</para>
+
+		<para>
+		These two settings will ensure that all directories and files that get created in the share will be readable/writable by the
+		owner and group set on the directory itself.
+		</para>
+		
+	</sect2>
+
+</sect1>
+
+</chapter>