--- /dev/null
+<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>
+++ /dev/null
-<chapter id="unix-permissions">
-<chapterinfo>
- &author.jeremy;
- <pubdate>12 Apr 1999</pubdate>
-</chapterinfo>
-
-<title>UNIX Permission Bits and Windows NT Access Control Lists</title>
-
-<sect1>
- <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>
-</sect1>
-
-<sect1>
- <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>
-
-</sect1>
-
-<sect1>
- <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>
-
-</sect1>
-
-<sect1>
- <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>
-
- <sect2>
- <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>
- </sect2>
-
- <sect2>
- <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>
- </sect2>
-</sect1>
-
-<sect1>
- <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>
-</sect1>
-
-<sect1>
- <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>
-</sect1>
-
-<sect1>
- <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>
-</sect1>
-
-</chapter>
git.samba.org / tprouty / samba.git / commitdiff