Fixups and more edits.
authorJohn Terpstra <jht@samba.org>
Sun, 18 May 2003 21:14:45 +0000 (21:14 +0000)
committerJohn Terpstra <jht@samba.org>
Sun, 18 May 2003 21:14:45 +0000 (21:14 +0000)
(This used to be commit c2501d2c14b3aa5dbd735400a5701c38c69e0b56)

docs/docbook/projdoc/AccessControls.xml

index 9c0b52638d237983c49ec45cf93ec5b86c145515..95eb6cebba9c2595d0aca2324a6506edb5d435bc 100644 (file)
@@ -374,245 +374,277 @@ The following parameters in the &smb.conf; file sections that define a share con
 Before using any of the following options please refer to the man page for &smb.conf;.
 </para>
 
-<table frame='all'><title>User and Group Based Controls</title>
-<tgroup cols='2'>
-        <thead>
-       <row>
-               <entry align="center">Control Parameter</entry>
-               <entry align="center">Description - Action - Notes</entry>
-       </row>
-       </thead>
-       <tbody>
-       <row>
-               <entry>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 super-user (root).  
-               Any user in this list will be able to do anything they like on the share,
-               irrespective of file permissions.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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>force user</entry>
-               <entry><para>
-               Specifies a UNIX user name 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>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>invalid users</entry>
-               <entry><para>
-               List of users that should not be allowed to login to this service.
-               </para></entry>
-       </row>
-       <row>
-               <entry>only user</entry>
-               <entry><para>
-               Controls whether connections with usernames not in the user list will be allowed.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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>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>valid users</entry>
-               <entry><para>
-               List of users that should be allowed to login to this service.
-               </para></entry>
-       </row>
-       <row>
-               <entry>write list</entry>
-               <entry><para>
-               List of users that are given read-write access to a service.
-               </para></entry>
-       </row>
-       </tbody>
-</tgroup>
-</table>
+       <sect2>
+       <title>User and Group Based Controls</title>
 
-<para>
-The following file and directory permission based controls, if misused, can result in considerable difficulty to
-diagnose the cause of mis-configuration. Use them sparingly and carefully. By gradually introducing each one by one
-undesirable side-effects may be detected. In the event of a problem, always comment all of them out and then gradually
-re-instroduce them in a controlled fashion.
-</para>
+       <para>
+       User and group based controls can prove very useful. In some situations it is distinctly desirable to affect all
+       file system operations as if a single user is doing this, the use of the <emphasis>force user</emphasis> and 
+       <emphasis>force group</emphasis> behaviour will achieve this. In other situations it may be necessary to affect a
+       paranoia level of control to ensure that only particular authorised persons will be able to access a share or
+       it's contents, here the use of the <emphasis>valid users</emphasis> or the <emphasis>invalid users</emphasis> may
+       be most useful.
+       </para>
+
+       <para>
+       As always, it is highly advisable to use the least difficult to maintain and the least ambiguous method for
+       controlling access. Remember, that when you leave the scene someone else will need to provide assistance and
+       if that person finds to great a mess, or if they do not understand what you have done then there is risk of
+       Samba being removed and an alternative solution being adopted.
+       </para>
+
+       <table frame='all'><title>User and Group Based Controls</title>
+       <tgroup cols='2'>
+               <thead>
+               <row>
+                       <entry align="center">Control Parameter</entry>
+                       <entry align="center">Description - Action - Notes</entry>
+               </row>
+               </thead>
+               <tbody>
+               <row>
+                       <entry>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 super-user (root).  
+                       Any user in this list will be able to do anything they like on the share,
+                       irrespective of file permissions.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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>force user</entry>
+                       <entry><para>
+                       Specifies a UNIX user name 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>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>invalid users</entry>
+                       <entry><para>
+                       List of users that should not be allowed to login to this service.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>only user</entry>
+                       <entry><para>
+                       Controls whether connections with usernames not in the user list will be allowed.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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>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>valid users</entry>
+                       <entry><para>
+                       List of users that should be allowed to login to this service.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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>
 
-<table frame='all'><title>File and Directory Permission Based Controls</title>
-<tgroup cols='2'>
-        <thead>
-       <row>
-               <entry align="center">Control Parameter</entry>
-               <entry align="center">Description - Action - Notes</entry>
-       </row>
-       </thead>
-       <tbody>
-       <row>
-               <entry>create mask</entry>
-               <entry><para>
-               Refer to the &smb.conf; man page.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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>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>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>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>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>force security mode</entry>
-               <entry><para>
-               Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions.
-               </para></entry>
-       </row>
-       <row>
-               <entry>hide unreadable</entry>
-               <entry><para>
-               Prevents clients from seeing the existance of files that cannot be read.
-               </para></entry>
-       </row>
-       <row>
-               <entry>hide unwriteable files</entry>
-               <entry><para>
-               Prevents clients from seeing the existance of files that cannot be written to. Unwriteable directories are shown as usual. 
-               </para></entry>
-       </row>
-       <row>
-               <entry>nt acl support</entry>
-               <entry><para>
-               This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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>
-
-<table frame='all'><title>Other Controls</title>
-<tgroup cols='2'>
-        <thead>
-       <row>
-               <entry align="center">Control Parameter</entry>
-               <entry align="center">Description - Action - Notes</entry>
-       </row>
-       </thead>
-       <tbody>
-       <row>
-               <entry>case sensitive</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 filename Samba received from the MS Windows client.
-               See also: default case, short preserve case.
-               </para></entry>
-       </row>
-       <row>
-               <entry>csc policy</entry>
-               <entry><para>
-               Client Side Caching Policy - parallels MS Windows client side file caching capabilities.
-               </para></entry>
-       </row>
-       <row>
-               <entry>dont descend</entry>
-               <entry><para>
-               Allows to specify a comma-delimited list of directories that the server should always show as empty.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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>dos filetimes</entry>
-               <entry><para>
-               Under DOS and Windows, if a user can write to a file they can change the timestamp on it. Under POSIX semantics, only the
-               owner of the file or root may change the timestamp. By default, Samba runs with POSIX semantics and refuses to change the 
-               timestamp on a file if the user smbd is acting on behalf of is not the file owner. Setting this option to yes allows DOS 
-               semantics and smbd(8) will change the file timestamp as DOS requires.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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 (opportunistic lock) then the client is free to assume that it is the only one accessing the file and it will 
-               aggressively cache file data. With some oplock types the client may even cache file open/close operations. 
-               </para></entry>
-       </row>
-       <row>
-               <entry>hide dot files, hide files, veto files</entry>
-               <entry><para>
-               Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible.
-               </para></entry>
-       </row>
-       <row>
-               <entry>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>veto files</entry>
-               <entry><para>
-               List of files and directories that are neither visible nor accessible.
-               </para></entry>
-       </row>
-       </tbody>
-</tgroup>
-</table>
+       <para>
+       The following file and directory permission based controls, if misused, can result in considerable difficulty to
+       diagnose the cause of mis-configuration. Use them sparingly and carefully. By gradually introducing each one by one
+       undesirable side-effects may be detected. In the event of a problem, always comment all of them out and then gradually
+       re-instroduce them in a controlled fashion.
+       </para>
+
+       <table frame='all'><title>File and Directory Permission Based Controls</title>
+       <tgroup cols='2'>
+               <thead>
+               <row>
+                       <entry align="center">Control Parameter</entry>
+                       <entry align="center">Description - Action - Notes</entry>
+               </row>
+               </thead>
+               <tbody>
+               <row>
+                       <entry>create mask</entry>
+                       <entry><para>
+                       Refer to the &smb.conf; man page.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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>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>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>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>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>force security mode</entry>
+                       <entry><para>
+                       Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>hide unreadable</entry>
+                       <entry><para>
+                       Prevents clients from seeing the existance of files that cannot be read.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>hide unwriteable files</entry>
+                       <entry><para>
+                       Prevents clients from seeing the existance of files that cannot be written to. Unwriteable directories are shown as usual. 
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>nt acl support</entry>
+                       <entry><para>
+                       This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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 following are documented because of the prevalence of administrators creating inadvertant barriers to file
+       access by not understanding the full implications of &smb.conf; file settings.
+       </para>
+
+       <table frame='all'><title>Other Controls</title>
+       <tgroup cols='2'>
+               <thead>
+               <row>
+                       <entry align="center">Control Parameter</entry>
+                       <entry align="center">Description - Action - Notes</entry>
+               </row>
+               </thead>
+               <tbody>
+               <row>
+                       <entry>case sensitive, default case, 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 filename Samba received from the MS Windows client.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>csc policy</entry>
+                       <entry><para>
+                       Client Side Caching Policy - parallels MS Windows client side file caching capabilities.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>dont descend</entry>
+                       <entry><para>
+                       Allows to specify a comma-delimited list of directories that the server should always show as empty.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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>dos filetimes</entry>
+                       <entry><para>
+                       DOS and Windows allows users to change file time stamps if they can write to the file. POSIX semantics prevent this.
+                       This options allows DOS and Windows behaviour.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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 then 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>hide dot files, hide files, veto files</entry>
+                       <entry><para>
+                       Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible.
+                       </para></entry>
+               </row>
+               <row>
+                       <entry>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>veto files</entry>
+                       <entry><para>
+                       List of files and directories that are neither visible nor accessible.
+                       </para></entry>
+               </row>
+               </tbody>
+       </tgroup>
+       </table>
+
+       </sect2>
 
 </sect1>
 
@@ -729,8 +761,7 @@ re-instroduce them in a controlled fashion.
 <title>MS Windows Access Control Lists and Unix Interoperability</title>
 
        <sect2>
-               <title>Viewing and changing UNIX permissions using the NT 
-               security dialogs</title>
+               <title>Managing UNIX permissions Using 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>
@@ -753,7 +784,7 @@ re-instroduce them in a controlled fashion.
        </sect2>
 
        <sect2>
-               <title>How to view file security on a Samba share</title>
+               <title>Viewing 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 
@@ -816,7 +847,7 @@ re-instroduce them in a controlled fashion.
        </sect2>
 
        <sect2>
-               <title>Viewing file or directory permissions</title>
+               <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