Extending Access Control Docs

(This used to be commit c0a1069463ea7239ca603deb5c568151439fea3f)

1 files changed, 547 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/AccessControls.xml b/docs/docbook/projdoc/AccessControls.xml
new file mode 100644
index 0000000000..c903af4468
--- /dev/null
+++ b/docs/docbook/projdoc/AccessControls.xml
@@ -0,0 +1,547 @@
+<chapter id="AccessControls">
+<chapterinfo>
+	&author.jht;
+	&author.jeremy;
+	<pubdate>May 10, 2003</pubdate>
+</chapterinfo>
+<title>File, Directory and Share Access Controls</title>
+
+<para>
+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
+adminstrators are often confused regarding network access controls and what is the best way to
+provide users with the type of access they need while protecting resources from the consequences
+of untoward access capabilities.
+</para>
+
+<para>
+Unix administrators frequently are not familiar 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>
+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 can not completely hide, even
+though it does try to make the chasm transparent.
+</para>
+
+<para>
+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>
+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>
+This is an opportune point to mention that it should be borne in mind that Samba was created to
+provide a means of interoperability and interchange of data between two operating environments
+that are quite different. It was never the intent to make Unix/Linux like MS Windows NT. Instead
+the purpose was an is to provide a sufficient level of exchange of data between the two environments.
+What is available today extends well beyond early plans and expections, yet the gap continues to
+shrink.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+	<para>
+	Samba offers a lot of 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>
+		Unix file and directory permissions
+		</para></listitem>
+
+		<listitem><para>
+		Samba Share Definitions
+		</para></listitem>
+
+		<listitem><para>
+		Samba Share ACLs
+		</para></listitem>
+
+		<listitem><para>
+		MS Windows ACLs through Unix POSIX ACLs
+		</para></listitem>
+	</itemizedlist>
+
+</sect1>
+
+<sect1>
+<title>File System Access Controls</title>
+
+<para>
+Explain here how Unix file and permissions work
+</para>
+
+</sect1>
+
+<sect1>
+<title>Share Definition Access Controls</title>
+
+<para>
+Explain here about the smb.conf [share] parameters
+</para>
+
+</sect1>
+
+<sect1>
+<title>Access Controls on Shares</title>
+
+	<para>
+	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 a very 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 <emphasis>Everyone</emphasis> Full Control (ie: Full control, Change and Read).
+	</para>
+
+	<para>
+	At this time Samba does NOT provide a tool for configuring access control setting on the Share
+	itself. Samba does have the capacity to store and act on access control settings, but  the only
+	way to create those settings is to use either the NT4 Server Manager or the Windows 200x MMC for
+	Computer Management.
+	</para>
+
+	<para>
+	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: <userinput>tdbdump share_info.tdb</userinput>.
+	</para>
+
+	<sect2>
+	<title>Share Permissions Management</title>
+
+		<para>
+		The best tool for the task is platform dependant. Choose the best tool for your environmemt.
+		</para>
+
+			<sect3>
+			<title>Windows NT4 Workstation/Server</title>
+			<para>
+			The tool you need to use to manage share permissions on a Samba 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 Microsoft - see details below.
+			</para>
+
+			<procedure>
+			<title>Instructions</title>
+			<step><para>
+			Launch the NT4 Server Manager, click on the Samba server you want to administer, then from the menu
+			select Computer, then click on the Shared Directories entry.
+			</para></step>
+
+			<step><para>
+				Now click on the share that you wish to manage, then click on the Properties tab, next click on
+				the Permissions tab. Now you can Add or change access control settings as you wish.
+			</para></step>
+			</procedure>
+
+			</sect3>
+
+			<sect3>
+			<title>Windows 200x/XP</title>
+
+			<para>
+			On MS Windows NT4/200x/XP system access control lists on the share itself are set using native
+			tools, usually from filemanager. For example, in Windows 200x: right click on the shared folder,
+			then select 'Sharing', then click on 'Permissions'. The default Windows NT4/200x permission allows
+			<emphasis>Everyone</emphasis> Full Control on the Share.
+			</para>
+
+			<para>
+			MS Windows 200x and later all comes with a tool called the 'Computer Management' snap-in for the
+			Microsoft Management Console (MMC). This tool is located by clicking on <filename>Control Panel ->
+			Administrative Tools -> Computer Management</filename>.
+			</para>
+
+			<procedure>
+			<title>Instructions</title>
+			<step><para>
+				After launching the MMC with the Computer Management snap-in, click on the menu item 'Action',
+				select 'Connect to another computer'. 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 where already logged in with administrative privilidge this step is not offered.
+			</para></step>
+
+			<step><para>
+			If the Samba server is not shown in the Select Computer box, then type in the name of the target
+			Samba server in the field 'Name:'. Now click on the [+] next to 'System Tools', then on the [+]
+			next to 'Shared Folders' in the left panel.
+			</para></step>
+
+			<step><para>
+			Now in the right panel, double-click on the share you wish to set access control permissions on.
+			Then click on the tab 'Share Permissions'. It is now possible to add access control entities
+			to the shared folder. Do NOT forget 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 Everyone user without removing this user
+			then effectively no user will be able to access the share. This is a result of what is known as
+			ACL precidence. ie: Everyone with NO ACCESS means that MaryK who is part of the group Everyone
+			will have no access even if this user is given explicit full control access.
+			</para>
+			</warning>
+
+			</sect3>
+		</sect2>
+
+</sect1>
+
+<sect1>
+<title>MS Windows Access Control Lists and Unix Interoperability</title>
+
+	<sect2>
+		<title>Viewing and changing UNIX permissions using the NT 
+		security dialogs</title>
+
+		<para>Windows NT clients can use their native security settings 
+		dialog box to view and modify the underlying UNIX permissions.</para>
+
+		<para>Note that this ability is careful not to compromise 
+		the security of the UNIX host Samba is running on, and 
+		still obeys all the file permission rules that a Samba 
+		administrator can set.</para>
+
+		<note>
+		<para>
+		All access to Unix/Linux system file via Samba is controlled at
+		the operating system file access control level. When trying to
+		figure out file access problems it is vitally important to identify
+		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>How to view file security on a Samba share</title>
+
+		<para>From an NT4/2000/XP client, single-click with the right 
+		mouse button on any file or directory in a Samba mounted 
+		drive letter or UNC path. When the menu pops-up, click 
+		on the <emphasis>Properties</emphasis> entry at the bottom of 
+		the menu. This brings up the file properties dialog
+		box. Click on the tab <emphasis>Security</emphasis> and you 
+		will see three buttons, <emphasis>Permissions</emphasis>, 	
+		<emphasis>Auditing</emphasis>, and <emphasis>Ownership</emphasis>. 
+		The <emphasis>Auditing</emphasis> 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 which is 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 
+		non-functional with a Samba share at this time, as the only 
+		useful button, the <command>Add</command> button will not currently 
+		allow a list of users to be seen.</para>
+
+	</sect2>
+
+	<sect2>
+		<title>Viewing file ownership</title>
+
+		<para>Clicking on the <command>"Ownership"</command> button 
+		brings up a dialog box telling you who owns the given file. The 
+		owner name will be of the form :</para>
+
+		<para><command>"SERVER\user (Long name)"</command></para>
+
+		<para>Where <replaceable>SERVER</replaceable> is the NetBIOS name of 
+		the Samba server, <replaceable>user</replaceable> is the user name 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 <command>Close
+		</command> button to remove this dialog.</para>
+
+		<para>If the parameter <parameter>nt acl support</parameter>
+		is set to <constant>false</constant> then the file owner will 
+		be shown as the NT user <command>"Everyone"</command>.</para>
+
+		<para>The <command>Take Ownership</command> button will not allow 
+		you to change the ownership of this file to yourself (clicking on 
+		it will display a dialog box complaining that the user 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. As 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>There is an NT chown 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 filesystem or remote mounted NTFS 
+		or Samba drive. This is available as part of the <emphasis>Seclib
+		</emphasis> NT security library written by Jeremy Allison of 
+		the Samba Team, available from the main Samba ftp site.</para>
+
+	</sect2>
+
+	<sect2>
+		<title>Viewing file or directory permissions</title>
+
+		<para>The third button is the <command>"Permissions"</command> 
+		button. Clicking on this brings up a dialog box that shows both 
+		the permissions and the UNIX owner of the file or directory. 
+		The owner is displayed in the form :</para>
+
+		<para><command>"SERVER\user (Long name)"</command></para>
+
+		<para>Where <replaceable>SERVER</replaceable> is the NetBIOS name of 
+		the Samba server, <replaceable>user</replaceable> is the user name 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 <parameter>nt acl support</parameter>
+		is set to <constant>false</constant> then the file owner will 
+		be shown as the NT user <command>"Everyone"</command> and the 
+		permissions will be shown as NT "Full Control".</para>
+
+
+		<para>The permissions field is displayed differently for files 
+		and directories, so I'll describe the way file permissions 
+		are displayed first.</para>
+
+		<sect3>
+			<title>File Permissions</title>
+
+			<para>The standard UNIX user/group/world triple and 
+			the corresponding "read", "write", "execute" permissions 
+			triples are mapped by Samba into a three element NT ACL 
+			with the 'r', 'w', and 'x' bits mapped into the corresponding 
+			NT permissions. The UNIX world permissions are mapped into 
+			the global NT group <command>Everyone</command>, followed 
+			by the list of permissions allowed for UNIX world. The UNIX 
+			owner and group permissions are displayed as an NT 
+			<command>user</command> icon and an NT <command>local 
+			group</command> icon respectively followed by the list 
+			of permissions allowed for the UNIX user and group.</para>
+
+			<para>As many UNIX permission sets don't map into common 
+			NT names such as <command>"read"</command>, <command>
+			"change"</command> or <command>"full control"</command> then 
+			usually the permissions will be prefixed by the words <command>
+			"Special Access"</command> 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 "no permissions" to be seen and modified then Samba 
+			overloads the NT <command>"Take Ownership"</command> 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 will 
+			be 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 of permissions 
+			is the ACL set on the directory itself, this is usually displayed 
+			in the first set of parentheses in the normal <command>"RW"</command> 
+			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 <command>
+			"inherited"</command> permissions that any file created within 
+			this directory would inherit.</para>
+
+			<para>Samba synthesises 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 the <command>OK</command> button. 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 need to also be taken into account.</para>
+
+		<para>If the parameter <parameter>nt acl support</parameter>
+		is set to <constant>false</constant> then any attempt to set 
+		security permissions will fail with an <command>"Access Denied"
+		</command> message.</para>
+
+		<para>The first thing to note is that the <command>"Add"</command> 
+		button will not return a list of users in Samba (it will give 
+		an error message of <command>"The remote procedure call failed 
+		and did not execute"</command>). This means that you can only 
+		manipulate the current user/group/world permissions listed in 
+		the dialog box. This actually works quite well as these are the 
+		only permissions that UNIX actually has.</para>
+
+		<para>If a permission triple (either user, group, or world) 
+		is removed from the list of permissions in the NT dialog box, 
+		then when the <command>"OK"</command> button is pressed it will 
+		be applied as "no permissions" on the UNIX side. If you then 
+		view the permissions again the "no permissions" 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 triple component.</para>
+
+		<para>As UNIX supports only the "r", "w" and "x" bits of 
+		an NT ACL then if other NT security attributes such as "Delete 
+		access" are selected then 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 <command>"Replace 
+		permissions on existing files"</command> checkbox in the NT 
+		dialog before clicking <command>"OK"</command>.</para>
+
+		<para>If you wish to remove all permissions from a 
+		user/group/world  component then you may either highlight the 
+		component and click the <command>"Remove"</command> button, 
+		or set the component to only have the special <command>"Take
+		Ownership"</command> permission (displayed as <command>"O"
+		</command>) highlighted.</para>
+	</sect2>
+
+	<sect2>
+		<title>Interaction with the standard Samba create mask 
+		parameters</title>
+
+		<para>There are four parameters 
+		to control interaction with the standard Samba create mask parameters.
+		These are :</para>
+
+		<para><parameter>security mask</parameter></para>
+		<para><parameter>force security mode</parameter></para>
+		<para><parameter>directory security mask</parameter></para>
+		<para><parameter>force directory security mode</parameter></para>
+
+		<para>Once a user clicks <command>"OK"</command> to apply the 
+		permissions Samba maps the given permissions into a user/group/world 
+		r/w/x triple set, and then will check the changed permissions for a 
+		file against the bits set in the <ulink url="smb.conf.5.html#SECURITYMASK"> 
+		<parameter>security mask</parameter></ulink> parameter. Any bits that 
+		were changed that are not set to '1' in this parameter are left alone 
+		in the file permissions.</para>
+
+		<para>Essentially, zero bits in the <parameter>security mask</parameter>
+		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 set explicitly this parameter is set to the same value as 
+		the <ulink url="smb.conf.5.html#CREATEMASK"><parameter>create mask
+		</parameter></ulink> 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 <ulink url="smb.conf.5.html#FORCESECURITYMODE">
+		<parameter>force security mode</parameter></ulink> parameter. Any bits 
+		that were changed that correspond to bits set to '1' 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 'on'.</para>
+
+		<para>If not set explicitly this parameter is set to the same value 
+		as the <ulink url="smb.conf.5.html#FORCECREATEMODE"><parameter>force 
+		create mode</parameter></ulink> parameter.
+		To allow a user to modify all the user/group/world permissions on a file
+		with no restrictions set this parameter to 000.</para>
+
+		<para>The <parameter>security mask</parameter> and <parameter>force 
+		security mode</parameter> parameters are applied to the change 
+		request in that order.</para>
+
+		<para>For a directory Samba will perform the same operations as 
+		described above for a file except using 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 <parameter>directory security mask</parameter> 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 <parameter>force directory mode</parameter> parameter. </para>
+
+		<para>In this way Samba enforces the permission restrictions that 
+		an administrator can set on a Samba share, whilst 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
+		doesn't force any particular bits to be set 'on', then set the following
+		parameters in the &smb.conf; file in that share specific section :</para>
+
+		<para><parameter>security mask = 0777</parameter></para>
+		<para><parameter>force security mode = 0</parameter></para>
+		<para><parameter>directory security mask = 0777</parameter></para>
+		<para><parameter>force directory security mode = 0</parameter></para>
+	</sect2>
+
+	<sect2>
+		<title>Interaction with the standard Samba file attribute 
+		mapping</title>
+
+		<para>Samba maps some of the DOS attribute bits (such as "read 
+		only") 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>
+
+		<para>One way this can show up is if a file has no UNIX read access
+		for the owner it will show up as "read only" in the standard 
+		file attributes tabbed dialog. Unfortunately this dialog is
+		the same one that contains the security info in another tab.</para>
+
+		<para>What this can mean is that if the owner changes the permissions
+		to allow themselves read access using the security dialog, clicks
+		<command>"OK"</command> to get back to the standard attributes tab 
+		dialog, and then clicks <command>"OK"</command> 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 <command>"OK"</command> to get back to the 
+		attributes dialog you should always hit <command>"Cancel"</command> 
+		rather than <command>"OK"</command> to ensure that your changes 
+		are not overridden.</para>
+	</sect2>
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+Stuff here
+</para>
+
+</sect1>
+
+</chapter>