From 79338d85cd08433b439e79d53c6b3abdb725be62 Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Sun, 18 May 2003 08:01:15 +0000 Subject: More Edits. (This used to be commit b4ffc25fcc158fd212f3104f584fb64007c973a8) --- docs/docbook/projdoc/AccessControls.xml | 243 +++++++++++++++++++++++++++++++- 1 file changed, 242 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/AccessControls.xml b/docs/docbook/projdoc/AccessControls.xml index 16057411e2..9c0b52638d 100644 --- a/docs/docbook/projdoc/AccessControls.xml +++ b/docs/docbook/projdoc/AccessControls.xml @@ -370,9 +370,250 @@ at how Samba helps to bridge the differences. Share Definition Access Controls -Explain here about the smb.conf [share] Access Control parameters, Mode and Mask parameters, force user/group, valid/invalid users, etc. +The following parameters in the &smb.conf; file sections that define a share control or affect access controls. +Before using any of the following options please refer to the man page for &smb.conf;. +User and Group Based Controls + + + + Control Parameter + Description - Action - Notes + + + + + admin users + + 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. + + + + force group + + Specifies a UNIX group name that will be assigned as the default primary group + for all users connecting to this service. + + + + force user + + 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. + + + + guest ok + + 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. + + + + invalid users + + List of users that should not be allowed to login to this service. + + + + only user + + Controls whether connections with usernames not in the user list will be allowed. + + + + read list + + 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. + + + + username + + Refer to the &smb.conf; man page for more information - this is a complex and potentially misused parameter. + + + + valid users + + List of users that should be allowed to login to this service. + + + + write list + + List of users that are given read-write access to a service. + + + + +
+ + +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. + + +File and Directory Permission Based Controls + + + + Control Parameter + Description - Action - Notes + + + + + create mask + + Refer to the &smb.conf; man page. + + + + directory mask + + The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories. + See also: directory security mask. + + + dos filemode + + Enabling this parameter allows a user who has write access to the file to modify the permissions on it. + + + + force create mode + + This parameter specifies a set of UNIX mode bit permissions that will always be set on a file created by Samba. + + + + force directory mode + + This parameter specifies a set of UNIX mode bit permissions that will always be set on a directory created by Samba. + + + + force directory security mode + + Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory + + + + force security mode + + Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions. + + + + hide unreadable + + Prevents clients from seeing the existance of files that cannot be read. + + + + hide unwriteable files + + Prevents clients from seeing the existance of files that cannot be written to. Unwriteable directories are shown as usual. + + + + nt acl support + + This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists. + + + + security mask + + Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file. + + + + +
+ +Other Controls + + + + Control Parameter + Description - Action - Notes + + + + + case sensitive + + 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. + + + + csc policy + + Client Side Caching Policy - parallels MS Windows client side file caching capabilities. + + + + dont descend + + Allows to specify a comma-delimited list of directories that the server should always show as empty. + + + + dos filetime resolution + + This option is mainly used as a compatibility option for Visual C++ when used against Samba shares. + + + + dos filetimes + + 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. + + + + fake oplocks + + 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. + + + + hide dot files, hide files, veto files + + Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible. + + + + read only + + If this parameter is yes, then users of a service may not create or modify files in the service's directory. + + + + veto files + + List of files and directories that are neither visible nor accessible. + + + + +
+ -- cgit From 89af28455012bc123db7a90fb212572e6c516fbf Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Sun, 18 May 2003 21:14:45 +0000 Subject: Fixups and more edits. (This used to be commit c2501d2c14b3aa5dbd735400a5701c38c69e0b56) --- docs/docbook/projdoc/AccessControls.xml | 513 +++++++++++++++++--------------- 1 file changed, 272 insertions(+), 241 deletions(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/AccessControls.xml b/docs/docbook/projdoc/AccessControls.xml index 9c0b52638d..95eb6cebba 100644 --- a/docs/docbook/projdoc/AccessControls.xml +++ b/docs/docbook/projdoc/AccessControls.xml @@ -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;. -User and Group Based Controls - - - - Control Parameter - Description - Action - Notes - - - - - admin users - - 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. - - - - force group - - Specifies a UNIX group name that will be assigned as the default primary group - for all users connecting to this service. - - - - force user - - 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. - - - - guest ok - - 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. - - - - invalid users - - List of users that should not be allowed to login to this service. - - - - only user - - Controls whether connections with usernames not in the user list will be allowed. - - - - read list - - 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. - - - - username - - Refer to the &smb.conf; man page for more information - this is a complex and potentially misused parameter. - - - - valid users - - List of users that should be allowed to login to this service. - - - - write list - - List of users that are given read-write access to a service. - - - - -
+ + User and Group Based Controls - -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. - + + 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 force user and + force group 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 valid users or the invalid users may + be most useful. + + + + 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. + + + User and Group Based Controls + + + + Control Parameter + Description - Action - Notes + + + + + admin users + + 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. + + + + force group + + Specifies a UNIX group name that will be assigned as the default primary group + for all users connecting to this service. + + + + force user + + 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. + + + + guest ok + + 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. + + + + invalid users + + List of users that should not be allowed to login to this service. + + + + only user + + Controls whether connections with usernames not in the user list will be allowed. + + + + read list + + 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. + + + + username + + Refer to the &smb.conf; man page for more information - this is a complex and potentially misused parameter. + + + + valid users + + List of users that should be allowed to login to this service. + + + + write list + + List of users that are given read-write access to a service. + + + + +
+ + + + + File and Directory Permissions Based Controls -File and Directory Permission Based Controls - - - - Control Parameter - Description - Action - Notes - - - - - create mask - - Refer to the &smb.conf; man page. - - - - directory mask - - The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories. - See also: directory security mask. - - - dos filemode - - Enabling this parameter allows a user who has write access to the file to modify the permissions on it. - - - - force create mode - - This parameter specifies a set of UNIX mode bit permissions that will always be set on a file created by Samba. - - - - force directory mode - - This parameter specifies a set of UNIX mode bit permissions that will always be set on a directory created by Samba. - - - - force directory security mode - - Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory - - - - force security mode - - Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions. - - - - hide unreadable - - Prevents clients from seeing the existance of files that cannot be read. - - - - hide unwriteable files - - Prevents clients from seeing the existance of files that cannot be written to. Unwriteable directories are shown as usual. - - - - nt acl support - - This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists. - - - - security mask - - Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file. - - - - -
- -Other Controls - - - - Control Parameter - Description - Action - Notes - - - - - case sensitive - - 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. - - - - csc policy - - Client Side Caching Policy - parallels MS Windows client side file caching capabilities. - - - - dont descend - - Allows to specify a comma-delimited list of directories that the server should always show as empty. - - - - dos filetime resolution - - This option is mainly used as a compatibility option for Visual C++ when used against Samba shares. - - - - dos filetimes - - 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. - - - - fake oplocks - - 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. - - - - hide dot files, hide files, veto files - - Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible. - - - - read only - - If this parameter is yes, then users of a service may not create or modify files in the service's directory. - - - - veto files - - List of files and directories that are neither visible nor accessible. - - - - -
+ + 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. + + + File and Directory Permission Based Controls + + + + Control Parameter + Description - Action - Notes + + + + + create mask + + Refer to the &smb.conf; man page. + + + + directory mask + + The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories. + See also: directory security mask. + + + dos filemode + + Enabling this parameter allows a user who has write access to the file to modify the permissions on it. + + + + force create mode + + This parameter specifies a set of UNIX mode bit permissions that will always be set on a file created by Samba. + + + + force directory mode + + This parameter specifies a set of UNIX mode bit permissions that will always be set on a directory created by Samba. + + + + force directory security mode + + Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory + + + + force security mode + + Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions. + + + + hide unreadable + + Prevents clients from seeing the existance of files that cannot be read. + + + + hide unwriteable files + + Prevents clients from seeing the existance of files that cannot be written to. Unwriteable directories are shown as usual. + + + + nt acl support + + This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists. + + + + security mask + + Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file. + + + + +
+ + + + + Miscellaneous Controls + + + 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. + + + Other Controls + + + + Control Parameter + Description - Action - Notes + + + + + case sensitive, default case, short preserve case + + 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. + + + + csc policy + + Client Side Caching Policy - parallels MS Windows client side file caching capabilities. + + + + dont descend + + Allows to specify a comma-delimited list of directories that the server should always show as empty. + + + + dos filetime resolution + + This option is mainly used as a compatibility option for Visual C++ when used against Samba shares. + + + + dos filetimes + + 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. + + + + fake oplocks + + 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. + + + + hide dot files, hide files, veto files + + Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible. + + + + read only + + If this parameter is yes, then users of a service may not create or modify files in the service's directory. + + + + veto files + + List of files and directories that are neither visible nor accessible. + + + + +
+ + @@ -729,8 +761,7 @@ re-instroduce them in a controlled fashion. MS Windows Access Control Lists and Unix Interoperability - Viewing and changing UNIX permissions using the NT - security dialogs + Managing UNIX permissions Using NT Security Dialogs Windows NT clients can use their native security settings dialog box to view and modify the underlying UNIX permissions. @@ -753,7 +784,7 @@ re-instroduce them in a controlled fashion. - How to view file security on a Samba share + Viewing File Security on a Samba Share 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. - Viewing file or directory permissions + Viewing File or Directory Permissions The third button is the "Permissions" button. Clicking on this brings up a dialog box that shows both -- cgit From fdaffbd7d0f1452b13807c4d1901b1df97d150d2 Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Tue, 20 May 2003 06:25:17 +0000 Subject: More edits - added example (This used to be commit 41c4bc4b8198797fef044eccad743550ccb43f06) --- docs/docbook/projdoc/AccessControls.xml | 102 +++++++++++++++++++++++++++++++- 1 file changed, 101 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/AccessControls.xml b/docs/docbook/projdoc/AccessControls.xml index 95eb6cebba..38c3475d34 100644 --- a/docs/docbook/projdoc/AccessControls.xml +++ b/docs/docbook/projdoc/AccessControls.xml @@ -1090,9 +1090,109 @@ Before using any of the following options please refer to the man page for &smb. Common Errors -Stuff from mailing lists here +File, Directory and Share access problems are very common on the mailing list. The following +are examples taken from the mailing list in recent times. + + + Users can not write to a public share + + + We are facing some troubles with file / directory permissions. I can log on the domain as admin user(root), + and theres 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 server to + chgrp -R users * and chown -R nobody * to allow others users to change the file. + + + + There are many ways to solve this problem, here are a few hints: + + + + Example Solution: + + + Go to the top of the directory that is shared + + + + + + Set the ownership to what ever public owner and group you want + + find 'directory_name' -type d -exec chown user.group {}\; + find 'directory_name' -type d -exec chmod 6775 'directory_name' + find 'directory_name' -type f -exec chmod 0775 {} \; + find 'directory_name' -type f -exec chown user.group {}\; + + + + + Note: The above will set the 'sticky bit' on all directories. Read your + Unix/Linux man page on what that does. It causes the OS to assign to all + files created in the directories the ownership of the directory. + + + + + Directory is: /foodbar + chown jack.engr /foodbar + + Note: This is the same as doing: + chown jack /foodbar + chgrp engr /foodbar + + Now do: + chmod 6775 /foodbar + ls -al /foodbar/.. + + You should see: + drwsrwsr-x 2 jack engr 48 2003-02-04 09:55 foodbar + + Now do: + su - jill + cd /foodbar + touch Afile + ls -al + + + + + You should see that the file 'Afile' created by Jill will have ownership + and permissions of Jack, as follows: + + -rw-r--r-- 1 jack engr 0 2003-02-04 09:57 Afile + + + + + + + Now in your smb.conf for the share add: + + force create mode = 0775 + force direcrtory mode = 6775 + + + + + Note: The above are only needed IF your users are NOT members of the group + you have used. ie: Within the OS do not have write permission on the directory. + + + + An alternative is to set in the smb.conf entry for the share: + + force user = jack + force group = engr + + + + + + + -- cgit From 1a1b742ca2f6f58b807f003c416bda06352d49ab Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Wed, 21 May 2003 06:58:16 +0000 Subject: A few small edits to the locking file. (This used to be commit dbe711f0fa2d77673de4c083740c2ce659b53ea1) --- docs/docbook/global.ent | 10 + docs/docbook/projdoc/locking.xml | 638 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 641 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/docbook/global.ent b/docs/docbook/global.ent index 6a494fcf2b..777848d050 100644 --- a/docs/docbook/global.ent +++ b/docs/docbook/global.ent @@ -93,6 +93,16 @@ '> + + EricRoseme + + HP Oplocks Usage Recommendations Whitepaper +
eric.roseme@hp.com + +'> + + diff --git a/docs/docbook/projdoc/locking.xml b/docs/docbook/projdoc/locking.xml index adb4356497..437f7756d9 100644 --- a/docs/docbook/projdoc/locking.xml +++ b/docs/docbook/projdoc/locking.xml @@ -3,16 +3,57 @@ &author.jeremy; &author.jelmer; &author.jht; + &author.eroseme; File and Record Locking + +One area which causes trouble for many network administrators is locking. +The extent of the problem is readily evident from searches over the internet. + + -Discussion +Features and Benefits + + +Samba provides all the same locking semantics that MS Windows clients expect +and that MS Windows NT4 / 200x servers provide also. + + + +The term locking has exceptionally broad meaning and covers +a range of functions that are all categorized under this one term. + + + +Opportunistic locking is a desirable feature when it can enhance the +perceived performance of applications on a networked client. However, the +opportunistic locking protocol is not robust, and therefore can +encounter problems when invoked beyond a simplistic configuration, or +on extended, slow, or faulty networks. In these cases, operating +system management of opportunistic locking and/or recovering from +repetitive errors can offset the perceived performance advantage that +it is intended to provide. + -One area which sometimes causes trouble is locking. +The MS Windows network administrator needs to be aware that file and record +locking semantics (behaviour) can be controlled either in Samba or by way of registry +settings on the MS Windows client. + + +Sometimes it is necessary to disable locking control settings BOTH on the Samba +server as well as on each MS Windows client! + + + + + + +Discussion + There are two types of locking which need to be performed by a SMB server. The first is record locking which allows a client to lock @@ -62,11 +103,431 @@ access should be allowed simultaneously with its open. A client may ask for DENY_NONE, DENY_READ, DENY_WRITE or DENY_ALL. There are also special compatibility modes called DENY_FCB and DENY_DOS. + + +Opportunistic Locking Overview + + +OPPORTUNISTIC LOCKING (Oplocks) is invoked by the Windows file system +(as opposed to an API) via registry entries (on the server AND client) +for the purpose of enhancing network performance when accessing a file +residing on a server. Performance is enhanced by caching the file +locally on the client which allows: + + + + Read-ahead: + + The client reads the local copy of the file, eliminating network latency + + + + Write caching: + + The client writes to the local copy of the file, eliminating network latency + + + + Lock caching: + + The client caches application locks locally, eliminating network latency + + + + + +The performance enhancement of oplocks is due to the opportunity of +exclusive access to the file - even if it is opened with deny-none - +because Windows monitors the file's status for concurrent access from +other processes. + + + +Windows defines 4 kinds of Oplocks: + Level1 Oplock: + + The redirector sees that the file was opened with deny + none (allowing concurrent access), verifies that no + other process is accessing the file, checks that + oplocks are enabled, then grants deny-all/read-write/ex- + clusive access to the file. The client now performs + operations on the cached local file. + + + + If a second process attempts to open the file, the open + is deferred while the redirector "breaks" the original + oplock. The oplock break signals the caching client to + write the local file back to the server, flush the + local locks, and discard read-ahead data. The break is + then complete, the deferred open is granted, and the + multiple processes can enjoy concurrent file access as + dictated by mandatory or byte-range locking options. + However, if the original opening process opened the + file with a share mode other than deny-none, then the + second process is granted limited or no access, despite + the oplock break. + + + + Level2 Oplock: + + Performs like a level1 oplock, except caching is only + operative for reads. All other operations are performed + on the server disk copy of the file. + + + + Filter Oplock: + + Does not allow write or delete file access + + + + Batch Oplock: + + Manipulates file openings and closings - allows caching + of file attributes + + + + + +An important detail is that oplocks are invoked by the file system, not +an application API. Therefore, an application can close an oplocked +file, but the file system does not relinquish the oplock. When the +oplock break is issued, the file system then simply closes the file in +preparation for the subsequent open by the second process. + + + +Opportunistic Locking is actually an improper name for this feature. +The true benefit of this feature is client-side data caching, and +oplocks is merely a notification mechanism for writing data back to the +networked storage disk. The limitation of opportunistic locking is the +reliability of the mechanism to process an oplock break (notification) +between the server and the caching client. If this exchange is faulty +(usually due to timing out for any number of reasons) then the +client-side caching benefit is negated. + + + +The actual decision that a user or administrator should consider is +whether it is sensible to share amongst multiple users data that will +be cached locally on a client. In many cases the answer is no. +Deciding when to cache or not cache data is the real question, and thus +"opportunistic locking" should be treated as a toggle for client-side +caching. Turn it "ON" when client-side caching is desirable and +reliable. Turn it "OFF" when client-side caching is redundant, +unreliable, or counter-productive. + + + +Opportunistic locking is by default set to "on" by Samba on all +configured shares, so careful attention should be given to each case to +determine if the potential benefit is worth the potential for delays. +The following recommendations will help to characterize the environment +where opportunistic locking may be effectively configured. + + + +Windows Opportunistic Locking is a lightweight performance-enhancing +feature. It is not a robust and reliable protocol. Every +implementation of Opportunistic Locking should be evaluated as a +tradeoff between perceived performance and reliability. Reliability +decreases as each successive rule above is not enforced. Consider a +share with oplocks enabled, over a wide area network, to a client on a +South Pacific atoll, on a high-availability server, serving a +mission-critical multi-user corporate database, during a tropical +storm. This configuration will likely encounter problems with oplocks. + + + +Oplocks can be beneficial to perceived client performance when treated +as a configuration toggle for client-side data caching. If the data +caching is likely to be interrupted, then oplock usage should be +reviewed. Samba enables opportunistic locking by default on all +shares. Careful attention should be given to the client usage of +shared data on the server, the server network reliability, and the +opportunistic locking configuration of each share. +n mission critical high availability environments, data integrity is +often a priority. Complex and expensive configurations are implemented +to ensure that if a client loses connectivity with a file server, a +failover replacement will be available immediately to provide +continuous data availability. + + + +Windows client failover behavior is more at risk of application +interruption than other platforms because it is dependant upon an +established TCP transport connection. If the connection is interrupted +- as in a file server failover - a new session must be established. +It is rare for Windows client applications to be coded to recover +correctly from a transport connection loss, therefore most applications +will experience some sort of interruption - at worst, abort and +require restarting. + + + +If a client session has been caching writes and reads locally due to +opportunistic locking, it is likely that the data will be lost when the +application restarts, or recovers from the TCP interrupt. When the TCP +connection drops, the client state is lost. When the file server +recovers, an oplock break is not sent to the client. In this case, the +work from the prior session is lost. Observing this scenario with +oplocks disabled, and the client was writing data to the file server +real-time, then the failover will provide the data on disk as it +existed at the time of the disconnect. + + + +In mission critical high availability environments, careful attention +should be given to opportunistic locking. Ideally, comprehensive +testing should be done with all affected applications with oplocks +enabled and disabled. + + + +Exclusively Accessed Shares + + +Opportunistic locking is most effective when it is confined to shares +that are exclusively accessed by a single user, or by only one user at +a time. Because the true value of opportunistic locking is the local +client caching of data, any operation that interrupts the caching +mechanism will cause a delay. + + + +Home directories are the most obvious examples of where the performance +benefit of opportunistic locking can be safely realized. + + + + + +Multiple-Accessed Shares or Files + + +As each additional user accesses a file in a share with opportunistic +locking enabled, the potential for delays and resulting perceived poor +performance increases. When multiple users are accessing a file on a +share that has oplocks enabled, the management impact of sending and +receiving oplock breaks, and the resulting latency while other clients +wait for the caching client to flush data, offset the performance gains +of the caching user. + + + +As each additional client attempts to access a file with oplocks set, +the potential performance improvement is negated and eventually results +in a performance bottleneck. + + + + + +Unix or NFS Client Accessed Files + + +Local Unix and NFS clients access files without a mandatory +file locking mechanism. Thus, these client platforms are incapable of +initiating an oplock break request from the server to a Windows client +that has a file cached. Local Unix or NFS file access can therefore +write to a file that has been cached by a Windows client, which +exposes the file to likely data corruption. + + + +If files are shared between Windows clients, and either loca Unix +or NFS users, then turn opportunistic locking off. + + + + + +Slow and/or Unreliable Networks + + +The biggest potential performance improvement for opportunistic locking +occurs when the client-side caching of reads and writes delivers the +most differential over sending those reads and writes over the wire. +This is most likely to occur when the network is extremely slow, +congested, or distributed (as in a WAN). However, network latency also +has a very high impact on the reliability of the oplock break +mechanism, and thus increases the likelihood of encountering oplock +problems that more than offset the potential perceived performance +gain. Of course, if an oplock break never has to be sent, then this is +the most advantageous scenario to utilize opportunistic locking. + + + +If the network is slow, unreliable, or a WAN, then do not configure +opportunistic locking if there is any chance of multiple users +regularly opening the same file. + + + + + +Multi-User Databases + + +Multi-user databases clearly pose a risk due to their very nature - +they are typically heavily accessed by numerous users at random +intervals. Placing a multi-user database on a share with opportunistic +locking enabled will likely result in a locking management bottleneck +on the Samba server. Whether the database application is developed +in-house or a commercially available product, ensure that the share +has opportunistic locking disabled. + + + + + +PDM Data Shares + + +Process Data Management (PDM) applications such as IMAN, Enovia, and +Clearcase, are increasing in usage with Windows client platforms, and +therefore SMB data stores. PDM applications manage multi-user +environments for critical data security and access. The typical PDM +environment is usually associated with sophisticated client design +applications that will load data locally as demanded. In addition, the +PDM application will usually monitor the data-state of each client. +In this case, client-side data caching is best left to the local +application and PDM server to negotiate and maintain. It is +appropriate to eliminate the client OS from any caching tasks, and the +server from any oplock management, by disabling opportunistic locking on +the share. + + + + + +Beware of Force User + + +Samba includes an smb.conf parameter called "force user" that changes +the user accessing a share from the incoming user to whatever user is +defined by the smb.conf variable. If opportunistic locking is enabled +on a share, the change in user access causes an oplock break to be sent +to the client, even if the user has not explicitly loaded a file. In +cases where the network is slow or unreliable, an oplock break can +become lost without the user even accessing a file. This can cause +apparent performance degradation as the client continually reconnects +to overcome the lost oplock break. + + + +Avoid the combination of the following: + + + + + force user in the &smb.conf; share configuration. + + + + Slow or unreliable networks + + + + Opportunistic Locking Enabled + + + + + + +Advanced Samba Opportunistic Locking Parameters + + +Samba provides opportunistic locking parameters that allow the +administrator to adjust various properties of the oplock mechanism to +account for timing and usage levels. These parameters provide good +versatility for implementing oplocks in environments where they would +likely cause problems. The parameters are: oplock break wait time, +oplock contention limit. + + + +For most users, administrators, and environments, if these parameters +are required, then the better option is to simply turn oplocks off. +The samba SWAT help text for both parameters reads "DO NOT CHANGE THIS +PARAMETER UNLESS YOU HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE." +This is good advice. + + + + + +Mission Critical High Availability + + +In mission critical high availability environments, data integrity is +often a priority. Complex and expensive configurations are implemented +to ensure that if a client loses connectivity with a file server, a +failover replacement will be available immediately to provide +continuous data availability. + + + +Windows client failover behavior is more at risk of application +interruption than other platforms because it is dependant upon an +established TCP transport connection. If the connection is interrupted +- as in a file server failover - a new session must be established. +It is rare for Windows client applications to be coded to recover +correctly from a transport connection loss, therefore most applications +will experience some sort of interruption - at worst, abort and +require restarting. + + + +If a client session has been caching writes and reads locally due to +opportunistic locking, it is likely that the data will be lost when the +application restarts, or recovers from the TCP interrupt. When the TCP +connection drops, the client state is lost. When the file server +recovers, an oplock break is not sent to the client. In this case, the +work from the prior session is lost. Observing this scenario with +oplocks disabled, and the client was writing data to the file server +real-time, then the failover will provide the data on disk as it +existed at the time of the disconnect. + + + +In mission critical high availability environments, careful attention +should be given to opportunistic locking. Ideally, comprehensive +testing should be done with all affected applications with oplocks +enabled and disabled. + + + + Samba Opportunistic Locking Control + +Opportunistic Locking is a unique Windows file locking feature. It is +not really file locking, but is included in most discussions of Windows +file locking, so is considered a defacto locking feature. +Opportunistic Locking is actually part of the Windows client file +caching mechanism. It is not a particularly robust or reliable feature +when implemented on the variety of customized networks that exist in +enterprise computing. + + + +Like Windows, Samba implements Opportunistic Locking as a server-side +component of the client caching mechanism. Because of the lightweight +nature of the Windows feature design, effective configuration of +Opportunistic Locking requires a good understanding of its limitations, +and then applying that understanding when configuring data access for +each particular customized network and client usage state. + + Opportunistic locking essentially means that the client is allowed to download and cache a file on their hard drive while making changes; if a second client wants to access the @@ -116,16 +577,38 @@ Another factor to consider is the perceived performance of file access. If oploc measurable speed benefit on your network, it might not be worth the hassle of dealing with them. + +Example Configuration + + +In the following we examine two destinct aspects of samba locking controls. + + + +Disabling Oplocks + You can disable oplocks on a per-share basis with the following: + + +[acctdata] oplocks = False level2 oplocks = False + + + +The default oplock type is Level1. Level2 Oplocks are enabled on a per-share basis +in the &smb.conf; file. + + Alternately, you could disable oplocks on a per-file basis within the share: + + veto oplock files = /*.mdb/*.MDB/*.dbf/*.DBF/ @@ -136,6 +619,96 @@ If you are experiencing problems with oplocks as apparent from Samba's log entri you may want to play it safe and disable oplocks and level2 oplocks. + + + +Diabling Kernel OpLocks + + +Kernel OpLocks is an &smb.conf; parameter that notifies Samba (if +the UNIX kernel has the capability to send a Windows client an oplock +break) when a UNIX process is attempting to open the file that is +cached. This parameter addresses sharing files between UNIX and +Windows with Oplocks enabled on the Samba server: the UNIX process +can open the file that is Oplocked (cached) by the Windows client and +the smbd process will not send an oplock break, which exposes the file +to the risk of data corruption. If the UNIX kernel has the ability to +send an oplock break, then the kernel oplocks parameter enables Samba +to send the oplock break. Kernel oplocks are enabled on a per-server +basis in the &smb.conf; file. + + + +Example: +[global] + kernel oplocks = yes + +The default is "no". + + + + +Veto OpLocks is an &smb.conf; parameter that identifies specific files for +which Oplocks are disabled. When a Windows client opens a file that +has been configured for veto oplocks, the client will not be granted +the oplock, and all operations will be executed on the original file on +disk instead of a client-cached file copy. By explicitly identifying +files that are shared with UNIX processes, and disabling oplocks for +those files, the server-wide Oplock configuration can be enabled to +allow Windows clients to utilize the performance benefit of file +caching without the risk of data corruption. Veto Oplocks can be +enabled on a per-share basis, or globally for the entire server, in the +&smb.conf; file: + + + +Example Veto OpLock Settings +[global] + veto oplock files = /filename.htm/*.txt/ + +[share_name] + veto oplock files = /*.exe/filename.ext/ + + + + +Oplock break wait time is an &smb.conf; parameter that adjusts the time +interval for Samba to reply to an oplock break request. Samba +recommends "DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ AND +UNDERSTOOD THE SAMBA OPLOCK CODE." Oplock Break Wait Time can only be +configured globally in the smb.conf file: + + + + +[global] + oplock break wait time = 0 (default) + + + + +Oplock break contention limit is an &smb.conf; parameter that limits the +response of the Samba server to grant an oplock if the configured +number of contending clients reaches the limit specified by the +parameter. Samba recommends "DO NOT CHANGE THIS PARAMETER UNLESS YOU +HAVE READ AND UNDERSTOOD THE SAMBA OPLOCK CODE." Oplock Break +Contention Limit can be enable on a per-share basis, or globally for +the entire server, in the &smb.conf; file: + + + + +[global] + oplock break contention limit = 2 (default) + + [share_name] + oplock break contention limit = 2 (default) + + + + + + @@ -196,7 +769,8 @@ You can also deny the granting of opportunistic locks by changing the following - HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\MRXSmb\Parameters\ + HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\MRXSmb\Parameters\ OplocksDisabled REG_DWORD 0 or 1 Default: 0 (not disabled) @@ -211,7 +785,8 @@ request opportunistic locks on a remote file. To disable oplocks, the value of - HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters + HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\LanmanServer\Parameters EnableOplocks REG_DWORD 0 or 1 Default: 1 (Enabled by Default) @@ -275,7 +850,8 @@ An illustration of how level II oplocks work: Workstation Service Entries - \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters + \HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\LanmanWorkstation\Parameters UseOpportunisticLocking REG_DWORD 0 or 1 Default: 1 (true) @@ -291,7 +867,8 @@ enhancement. This parameter should be disabled only to isolate problems. Server Service Entries - \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters + \HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\LanmanServer\Parameters EnableOplocks REG_DWORD 0 or 1 Default: 1 (true) @@ -357,6 +934,53 @@ our Knowledge Base. + +Common Errors + + +In some sites locking problems surface as soon as a server is installed, in other sites +locking problems may not surface for a long time. Almost without exeception, when a locking +problem does surface it will cause embarassment and potential data corruption. + + + +Over the past few years there have been a number of complaints on the samba mailing lists +that have claimed that samba caused data corruption. Three causes have been identified +so far: + + + + + Incorrect configuration of opportunistic locking (incompatible with the application + being used. This is a VERY common problem even where MS Windows NT4 or MS Windows 200x + based servers were in use. It is imperative that the software application vendors' + instructions for configuration of file locking should be followed. If in doubt, + disable oplocks on both the server and the client. Disabling of all forms of file + caching on the MS Windows client may be necessary also. + + + + Defective network cards, cables, or HUBs / Switched. This is generally a more + prevalent factor with low cost networking hardware, though occasionally there + have been problems with incompatibilities in more up market hardware also. + + + + There have been some random reports of samba log files being written over data + files. This has been reported by very few sites (about 5 in the past 3 years) + and all attempts to reproduce the problem have failed. The Samba-Team has been + unable to catch this happening and thus has NOT been able to isolate any particular + cause. Considering the millions of systems that use samba, for the sites that have + been affected by this as well as for the Samba-Team this is a frustrating and + a vexing challenge. If you see this type of thing happening please create a bug + report on https://bugzilla.samba.org without delay. Make sure that you give as much + information as you possibly can to help isolate the cause and to allow reproduction + of the problem (an essential step in problem isolation and correction). + + + + + Additional Reading @@ -379,7 +1003,7 @@ Windows Base Services > Files and I/O > SDK Documentation > File Storag Microsoft Knowledge Base Article Q224992 "Maintaining Transactional Integrity with OPLOCKS", -Microsoft Corporation, April 1999, http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992. +Microsoft Corporation, April 1999, http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992. -- cgit From efd50ead07bcbd69b8fe2ac766654c2559d907f8 Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Wed, 21 May 2003 17:14:40 +0000 Subject: Fix typo. (This used to be commit 89e9ce8e67ef097f8851da2b12b2cfe27fcc44f6) --- docs/docbook/global.ent | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/docbook/global.ent b/docs/docbook/global.ent index 777848d050..0ff0c9a5cf 100644 --- a/docs/docbook/global.ent +++ b/docs/docbook/global.ent @@ -98,7 +98,7 @@ EricRoseme HP Oplocks Usage Recommendations Whitepaper -
eric.roseme@hp.com +
eric.roseme@hp.com
'> -- cgit From 5c0586f488f65f5c55f86ab9debdab1ec8eb5c57 Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Sat, 24 May 2003 06:58:08 +0000 Subject: Oh aye, another wee edit. (This used to be commit 03542544d450e2b2a5ba4dd5f938836a025205e9) --- docs/docbook/projdoc/NetworkBrowsing.xml | 228 ++++++++++++++++++++++++++++--- 1 file changed, 207 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/NetworkBrowsing.xml b/docs/docbook/projdoc/NetworkBrowsing.xml index 6327bde30a..8648bfa256 100644 --- a/docs/docbook/projdoc/NetworkBrowsing.xml +++ b/docs/docbook/projdoc/NetworkBrowsing.xml @@ -22,6 +22,58 @@ means for resolution of MS Windows machine names is via DNS and Active Directory The following information assumes that your site is running NetBIOS over TCP/IP. + +Features and Benefits + + +Someone once referred to the past in terms of: They were the worst of times, +they were the best of times. The more we look back, them more we long for what was and +hope it never returns!. + + + +For many MS Windows network administrators that statement sums up their feelings about +NetBIOS networking precisely. For those who mastered NetBIOS networking it's fickle +nature was just par for the course. For those who never quite managed to tame it's +lusty features NetBIOS is like Paterson's Curse. + + + +For those not familiar with botanical problems in Australia: Paterson's curse, +Echium plantagineum, was introduced to Australia from Europe during the mid-nineteenth +century. Since then it has spread rapidly. The high seed production, with densities of +thousands of seeds per square metre, a seed longevity of more than seven years, and an +ability to germinate at any time of year, given the right conditions, are some of the +features which make it such a persistent weed. + + + +In this chapter we explore vital aspects of SMB (Server Message Block) networking with +a particular focus on SMB as implmented through running NetBIOS (Network Basic +Input / Output System) over TCP/IP. Since Samba does NOT implement SMB or NetBIOS over +any other protocols we need to know how to configure our network environment and simply +remember to use nothing but TCP/IP on all our MS Windows network clients. + + + +Samba provides the ability to implement a WINS (Windows Internetworking Name Server) +and implements extensions to Microsoft's implementation of WINS. These extensions +help Samba to affect stable WINS operations beyond the normal scope of MS WINS. + + + +Please note that WINS is exclusively a service that applies only to those systems +that run NetBIOS over TCP/IP. MS Windows 200x / XP have the capacity to turn off +support for NetBIOS, in which case WINS is of no relevance. Samba-3 supports this also. + + + +For those networks on which NetBIOS has been disabled (ie: WINS is NOT required) +the use of DNS is necessary for host name resolution. + + + + What is Browsing? @@ -76,28 +128,36 @@ called nmbd. The configuration parameters involved in nmbd' -WINS Server and WINS Support are mutually exclusive options. Those marked with an '*' are -the only options that commonly MAY need to be modified. Even if not one of these parameters -is set nmbd will still do it's job. +For Samba the WINS Server and WINS Support are mutually exclusive options. Those marked with +an '*' are the only options that commonly MAY need to be modified. Even if not one of these +parameters is set nmbd will still do it's job. + Discussion -Firstly, all MS Windows networking is based on SMB (Server Message -Block) based messaging. SMB messaging may be implemented using NetBIOS or -without NetBIOS. Samba implements NetBIOS by encapsulating it over TCP/IP. -MS Windows products can do likewise. NetBIOS based networking uses broadcast -messaging to affect browse list management. When running NetBIOS over -TCP/IP this uses UDP based messaging. UDP messages can be broadcast or unicast. +Firstly, all MS Windows networking uses SMB (Server Message Block) based messaging. +SMB messaging may be implemented with or without NetBIOS. MS Windows 200x supports +NetBIOS over TCP/IP for backwards compatibility. Microsoft are intent on phasing out NetBIOS +support. + + + +NetBIOS over TCP/IP + + +Samba implements NetBIOS, as does MS Windows NT / 200x / XP, by encapsulating it over TCP/IP. +MS Windows products can do likewise. NetBIOS based networking uses broadcast messaging to +affect browse list management. When running NetBIOS over TCP/IP this uses UDP based messaging. +UDP messages can be broadcast or unicast. Normally, only unicast UDP messaging can be forwarded by routers. The -remote announce -parameter to smb.conf helps to project browse announcements +remote announce parameter to smb.conf helps to project browse announcements to remote network segments via unicast UDP. Similarly, the remote browse sync parameter of smb.conf implements browse list collation using unicast UDP. @@ -121,20 +181,21 @@ the use of the remote announce and the As of Samba 3 WINS replication is being worked on. The bulk of the code has -been committed, but it still needs maturation. +been committed, but it still needs maturation. This is NOT a supported feature +of the Samba-3.0.0 release. Hopefully, this will become a supported feature +of one of the samba-3 release series. Right now samba WINS does not support MS-WINS replication. This means that -when setting up Samba as a WINS server there must only be one nmbd configured -as a WINS server on the network. Some sites have used multiple Samba WINS +when setting up Samba as a WINS server there must only be one nmbd +configured as a WINS server on the network. Some sites have used multiple Samba WINS servers for redundancy (one server per subnet) and then used remote browse sync and remote announce -to affect browse list collation across all -segments. Note that this means clients will only resolve local names, -and must be configured to use DNS to resolve names on other subnets in -order to resolve the IP addresses of the servers they can see on other -subnets. This setup is not recommended, but is mentioned as a practical +to affect browse list collation across all segments. Note that this means clients +will only resolve local names, and must be configured to use DNS to resolve names +on other subnets in order to resolve the IP addresses of the servers they can see +on other subnets. This setup is not recommended, but is mentioned as a practical consideration (ie: an 'if all else fails' scenario). @@ -145,15 +206,140 @@ that it will take time to establish a browse list and it can take up to 45 minutes to stabilise, particularly across network segments. + + + +TCP/IP - without NetBIOS + + +All TCP/IP using systems use various forms of host name resolution. The primary +methods for TCP/IP hostname resolutions involves either a static file (/etc/hosts +) or DNS (the Domain Name System). DNS is the technology that makes +the Internet usable. DNS based host name resolution is supported by nearly all TCP/IP +enabled systems. Only a few embedded TCP/IP systems do not support DNS. + + + +When an MS Windows 200x / XP system attempts to resolve a host name to an IP address +it follows a defined path: + + + + + Checks the hosts file. It is located in + C:\WinNT\System32\Drivers\etc. + + + + Does a DNS lookup + + + + Checks the NetBIOS name cache + + + + Queries the WINS server + + + + Does a broadcast name lookup over UDP + + + + Looks up entries in LMHOSTS. It is located in + C:\WinNT\System32\Drivers\etc. + + + + +Windows 200x / XP can register it's host name with a Dynamic DNS server. You can +force register with a Dynamic DNS server in Windows 200x / XP using: +ipconfig /registerdns + + + +With Active Directory (ADS), a correctly functioning DNS server is absolutely +essential. In the absence of a working DNS server that has been correctly configured +MS Windows clients and servers will be totally unable to locate each other, +consequently network services will be severely impaired. + + + +The use of Dynamic DNS is highly recommended with Active Directory, in which case +the use of BIND9 is preferred for it's ability to adequately support the SRV (service) +records that are needed for Active Directory. + + + + + +DNS and Active Directory + + +Occasionally we hear from Unix network administrators who want to use a Unix based Dynamic +DNS server in place of the Microsoft DNS server. While this might be desirable to some, the +MS Windows 200x DNS server is auto-configured to work with Active Directory. It is possible +to use BIND version 8 or 9, but it will almost certainly be necessary to create service records +so that MS Active Directory clients can resolve host names to locate essential network services. +The following are some of the default service records that Active Directory requires: + + + + _ldap._tcp.pdc.ms-dcs.Domain + + + This provides the address of the Windows NT PDC for the Domain. + + + + _ldap._tcp.pdc.ms-dcs.DomainTree + + + Resolves the addresses of Global Catalog servers in the domain. + + + + _ldap._tcp.site.sites.writable.ms-dcs.Domain + + Provides list of domain controllers based on sites. + + + + _ldap._tcp.writable.ms-dcs.Domain + + + Enumerates list of domain controllers that have the writable + copies of the Active Directory data store. + + + + _ldap._tcp.GUID.domains.ms-dcs.DomainTree + + Entry used by MS Windows clients to locate machines using the + Global Unique Identifier. + + + + _ldap._tcp.Site.gc.ms-dcs.DomainTree + + Used by MS Windows clients to locate site configuration dependant + Global Catalog server. + + + + + + How Browsing Functions -As stated above, MS Windows machines register their NetBIOS names +MS Windows machines register their NetBIOS names (ie: the machine name for each service type in operation) on start -up. Also, as stated above, the exact method by which this name registration +up. The exact method by which this name registration takes place is determined by whether or not the MS Windows client/server has been given a WINS server address, whether or not LMHOSTS lookup is enabled, or if DNS for NetBIOS name resolution is enabled, etc. -- cgit From 593d264c7200fa55a977de77ed2cfae1c2910ba1 Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Sun, 25 May 2003 07:55:33 +0000 Subject: Update includes Jelmers' changes. (This used to be commit a2501945cf29c5579da61e708705a56a3f0a993e) --- docs/docbook/projdoc/passdb.xml | 2017 +++++++++++++++++++++++---------------- 1 file changed, 1200 insertions(+), 817 deletions(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/passdb.xml b/docs/docbook/projdoc/passdb.xml index b2ae40f0b7..c64f568571 100644 --- a/docs/docbook/projdoc/passdb.xml +++ b/docs/docbook/projdoc/passdb.xml @@ -12,435 +12,765 @@ - February 2003 + May 24, 2003 +Account Information Databases -User information database + +Samba-3 implements a new capability to work concurrently with mulitple account backends. +The possible new combinations of password backends allows Samba-3 a degree of flexibility +and scalability that previously could be achieved only with MS Windows Active Directory. +This chapter describes the new functionality and how to get the most out of it. + + + +In the course of development of Samba-3 a number of requests were received to provide the +ability to migrate MS Windows NT4 SAM accounts to Samba-3 without the need to provide +matching Unix/Linux accounts. We called this the Non Unix Accounts (NUA) +capability. The intent was that an administrator could decide to use the tdbsam +backend and by simply specifying "passdb backedn = tdbsam_nua, guest" +this would allow Samba-3 to implement a solution that did not use Unix accounts per se. Late +in the development cycle the team doing this work hit upon some obstacles that prevents this +solution from being used. Given the delays with Samba-3 release a decision was made to NOT +deliver this functionality until a better method of recognising NT Group SIDs from NT User +SIDs could be found. This feature may thus return during the life cycle for the Samba-3 series. + + + +Samba-3.0.0 does NOT support Non-Unix Account (NUA) operation. + - Introduction +Features and Benefits - Old windows clients send plain text passwords over the wire. - Samba can check these passwords by crypting them and comparing them - to the hash stored in the unix user database. - - - - Newer windows clients send encrypted passwords (so-called - Lanman and NT hashes) over - the wire, instead of plain text passwords. The newest clients - will only send encrypted passwords and refuse to send plain text - passwords, unless their registry is tweaked. - + +Samba-3 provides for complete backwards compatibility with Samba-2.2.x functionality +as follows: + - These passwords can't be converted to unix style encrypted - passwords. Because of that you can't use the standard unix - user database, and you have to store the Lanman and NT hashes - somewhere else. - - Next to a differently encrypted passwords, - windows also stores certain data for each user - that is not stored in a unix user database, e.g. - workstations the user may logon from, the location where his/her - profile is stored, etc. - Samba retrieves and stores this information using a "passdb backend". - Commonly - available backends are LDAP, plain text file, MySQL and nisplus. - For more information, see the documentation about the - passdb backend = parameter. - - + +Backwards Compatibility Backends + Plain Text: + + + This option uses nothing but the Unix/Linux /etc/passwd + style back end. On systems that have PAM (Pluggable Authentication Modules) + support all PAM modules are supported. The behaviour is just as it was with + Samba-2.2.x, and the protocol limitations imposed by MS Windows clients + apply likewise. + + + - - Important Notes About Security - - The unix and SMB password encryption techniques seem similar - on the surface. This similarity is, however, only skin deep. The unix - scheme typically sends clear text passwords over the network when - logging in. This is bad. The SMB encryption scheme never sends the - cleartext password over the network but it does store the 16 byte - hashed values on disk. This is also bad. Why? Because the 16 byte hashed - values are a "password equivalent". You cannot derive the user's - password from them, but they could potentially be used in a modified - client to gain access to a server. This would require considerable - technical knowledge on behalf of the attacker but is perfectly possible. - You should thus treat the data stored in whatever - passdb backend you use (smbpasswd file, ldap, mysql) as though it contained the - cleartext passwords of all your users. Its contents must be kept - secret, and the file should be protected accordingly. - - Ideally we would like a password scheme which neither requires - plain text passwords on the net or on disk. Unfortunately this - is not available as Samba is stuck with being compatible with - other SMB systems (WinNT, WfWg, Win95 etc). - - - Note that Windows NT 4.0 Service pack 3 changed the - default for permissible authentication so that plaintext - passwords are never sent over the wire. - The solution to this is either to switch to encrypted passwords - with Samba or edit the Windows NT registry to re-enable plaintext - passwords. See the document WinNT.txt for details on how to do - this. - - Other Microsoft operating systems which also exhibit - this behavior includes - - These versions of MS Windows do not support full domain - security protocols, although they may log onto a domain environment. - Of these Only MS Windows XP Home does NOT support domain logons. + smbpasswd: + + + This option allows continues use of the smbpasswd + file that maintains a plain ASCII (text) layout that includes the MS Windows + LanMan and NT encrypted passwords as well as a field that stores some + account information. This form of password backend does NOT store any of + the MS Windows NT/200x SAM (Security Account Manager) information needed to + provide the extended controls that are needed for more comprehensive + interoperation with MS Windows NT4 / 200x servers. + + + - - MS DOS Network client 3.0 with - the basic network redirector installed - - Windows 95 with the network redirector - update installed - - Windows 98 [se] + ldapsam_compat (Samba-2.2 LDAP Compatibilty): + + + There is a password backend option that allows continued operation with + a existing OpenLDAP backend that uses the Samba-2.2.x LDAP schema extension. + This option is provided primarily as a migration tool, although there is + no reason to force migration at this time. + + + + - Windows Me + +Samba-3 introduces the following new password backend capabilities: + - Windows XP Home - + +New Backends + tdbsam: + + + The tdbsam password backend stores the old + smbpasswd information PLUS the extended MS Windows NT / 200x + SAM information into a binary format TDB (trivial database) file. + The inclusion of the extended information makes it possible for Samba-3 + to implement the same account and system access controls that are possible + with MS Windows NT4 and MS Windows 200x based systems. + + + + The inclusion of the tdbssam capability is a direct + response to user requests to allow simple site operation without the overhead + of the complexities of running OpenLDAP. It is recommended to use this only + for sites that have fewer than 250 users. For larger sites or implementations + the use of OpenLDAP or of Active Directory integration is strongly recommended. + + + - The following versions of MS Windows fully support domain - security protocols. + ldapsam: + + + Samba-3 has a new and extended LDAP implementation that requires configuration + of OpenLDAP with a new format samba schema. The new format schema file is + included in the ~samba/examples/LDAP directory. + + + + The new LDAP implmentation significantly expands the control abilities that + were possible with prior versions of Samba. It is not possible to specify + "per user" profile settings, home directories, account access controls, and + much more. Corporate sites will see that the Samba-Team has listened to their + requests both for capability and to allow greater scalability. + + + - - Windows NT 3.5x - Windows NT 4.0 - Windows 2000 Professional - Windows 200x Server/Advanced Server - Windows XP Professional - - - - All current release of - Microsoft SMB/CIFS clients support authentication via the - SMB Challenge/Response mechanism described here. Enabling - clear text authentication does not disable the ability - of the client to participate in encrypted authentication. - - MS Windows clients will cache the encrypted password alone. - Even when plain text passwords are re-enabled, through the appropriate - registry change, the plain text password is NEVER cached. This means that - in the event that a network connections should become disconnected (broken) - only the cached (encrypted) password will be sent to the resource server - to affect a auto-reconnect. If the resource server does not support encrypted - passwords the auto-reconnect will fail. USE OF ENCRYPTED PASSWORDS - IS STRONGLY ADVISED. + mysqlsam (MySQL based backend): + + + It is expected that the MySQL based SAM will be very popular in some corners. + This database backend will be on considerable interest to sites that want to + leverage existing MySQL technology. + + + - - Advantages of SMB Encryption - - - Plain text passwords are not passed across - the network. Someone using a network sniffer cannot just - record passwords going to the SMB server. - - WinNT doesn't like talking to a server - that does not support encrypted passwords. It will refuse - to browse the server if the server is also in user level - security mode. It will insist on prompting the user for the - password on each connection, which is very annoying. The - only things you can do to stop this is to use SMB encryption. - - - Encrypted password support allows automatic share - (resource) reconnects. - - + xmlsam (XML based datafile): + + + Allows the account and password data to be stored in an XML format + data file. This backend is NOT recommended for normal operation, it is + provided for developmental and for experimental use only. We recognise + that this will not stop some people from using it anyhow, it should work + but is NOT officially supported at this time (and likely will not be + at any time). + + + + The xmlsam option can be useful for account migration between database + backends. Use of this tool will allow the data to be edited before migration + into another backend format. + + + + nisplussam: + + + The NIS+ based passdb backend. Takes name NIS domain as an + optional argument. Only works with Sun NIS+ servers. + + + - - Advantages of non-encrypted passwords + plugin: + + + This option allows any external non-Samba backend to interface directly + to the samba code. This facility will allow third part vendors to provide + a proprietary backend to Samba-3. + + + + - - Plain text passwords are not kept - on disk, and are NOT cached in memory. - - Uses same password file as other unix - services such as login and ftp - - Use of other services (such as telnet and ftp) which - send plain text passwords over the net, so sending them for SMB - isn't such a big deal. - - - - The smbpasswd Command - - The smbpasswd utility is a utility similar to the - passwd or yppasswd programs. - It maintains the two 32 byte password fields in the passdb backend. - - smbpasswd works in a client-server mode - where it contacts the local smbd to change the user's password on its - behalf. This has enormous benefits - as follows. - - smbpasswd has the capability - to change passwords on Windows NT servers (this only works when - the request is sent to the NT Primary Domain Controller if you - are changing an NT Domain user's password). - - To run smbpasswd as a normal user just type : - - $ smbpasswd - Old SMB password: <type old value here - - or hit return if there was no old password> - New SMB Password: <type new value> - - Repeat New SMB Password: <re-type new value - - - If the old value does not match the current value stored for - that user, or the two new values do not match each other, then the - password will not be changed. - - If invoked by an ordinary user it will only allow the user - to change his or her own Samba password. + Technical Information + + + Old windows clients send plain text passwords over the wire. Samba can check these + passwords by crypting them and comparing them to the hash stored in the unix user database. + - If run by the root user smbpasswd may take an optional - argument, specifying the user name whose SMB password you wish to - change. Note that when run as root smbpasswd does not prompt for - or check the old password value, thus allowing root to set passwords - for users who have forgotten their passwords. + + Newer windows clients send encrypted passwords (so-called Lanman and NT hashes) over + the wire, instead of plain text passwords. The newest clients will send only encrypted + passwords and refuse to send plain text passwords, unless their registry is tweaked. + + + + These passwords can't be converted to unix style encrypted passwords. Because of that + you can't use the standard unix user database, and you have to store the Lanman and NT + hashes somewhere else. + - smbpasswd is designed to work in the same way - and be familiar to UNIX users who use the passwd or - yppasswd commands. + + In addition to differently encrypted passwords, windows also stores certain data for each + user that is not stored in a unix user database. e.g: workstations the user may logon from, + the location where the users' profile is stored, and so on. Samba retrieves and stores this + information using a "passdb backend". Commonly available backends are LDAP, plain text + file, MySQL and nisplus. For more information, see the man page for &smb.conf; regarding the + passdb backend = parameter. + - For more details on using smbpasswd refer - to the man page which will always be the definitive reference. - + + Important Notes About Security + + + The unix and SMB password encryption techniques seem similar on the surface. This + similarity is, however, only skin deep. The unix scheme typically sends clear text + passwords over the network when logging in. This is bad. The SMB encryption scheme + never sends the cleartext password over the network but it does store the 16 byte + hashed values on disk. This is also bad. Why? Because the 16 byte hashed values + are a "password equivalent". You cannot derive the user's password from them, but + they could potentially be used in a modified client to gain access to a server. + This would require considerable technical knowledge on behalf of the attacker but + is perfectly possible. You should thus treat the data stored in whatever passdb + backend you use (smbpasswd file, ldap, mysql) as though it contained the cleartext + passwords of all your users. Its contents must be kept secret, and the file should + be protected accordingly. + + + + Ideally we would like a password scheme that involves neither plain text passwords + on the net nor on disk. Unfortunately this is not available as Samba is stuck with + having to be compatible with other SMB systems (WinNT, WfWg, Win95 etc). + + + + Windows NT 4.0 Service pack 3 changed the default setting so that plaintext passwords + are disabled from being sent over the wire. This mandates either the use of encrypted + password support or edit the Windows NT registry to re-enable plaintext passwords. + + + + The following versions of MS Windows do not support full domain security protocols, + although they may log onto a domain environment: + + + + + MS DOS Network client 3.0 with the basic network redirector installed + + + + Windows 95 with the network redirector update installed + + + + Windows 98 [se] + + + + Windows Me + + + + + + MS Windows XP Home does not have facilities to become a domain member and it can + not participate in domain logons. + + + + + The following versions of MS Windows fully support domain security protocols. + + + + Windows NT 3.5x + Windows NT 4.0 + Windows 2000 Professional + Windows 200x Server/Advanced Server + Windows XP Professional + + + + All current release of Microsoft SMB/CIFS clients support authentication via the + SMB Challenge/Response mechanism described here. Enabling clear text authentication + does not disable the ability of the client to participate in encrypted authentication. + Instead, it allows the client to negotiate either plain text _or_ encrypted password + handling. + + + + MS Windows clients will cache the encrypted password alone. Where plain text passwords + are re-enabled, through the appropriate registry change, the plain text password is NEVER + cached. This means that in the event that a network connections should become disconnected + (broken) only the cached (encrypted) password will be sent to the resource server to + affect a auto-reconnect. If the resource server does not support encrypted passwords the + auto-reconnect will fail. USE OF ENCRYPTED PASSWORDS IS STRONGLY ADVISED. + + + + Advantages of Encrypted Passwords + + + Plain text passwords are not passed across + the network. Someone using a network sniffer cannot just + record passwords going to the SMB server. + + Plain text passwords are not stored anywhere in + memory or on disk. + + WinNT doesn't like talking to a server + that does not support encrypted passwords. It will refuse + to browse the server if the server is also in user level + security mode. It will insist on prompting the user for the + password on each connection, which is very annoying. The + only things you can do to stop this is to use SMB encryption. + + + Encrypted password support allows automatic share + (resource) reconnects. + + Encrypted passwords are essential for PDC/BDC + operation. + + + + + + Advantages of non-encrypted passwords - -Plain text +Account Management Tools + -Older versions of samba retrieved user information from the unix user database -and eventually some other fields from the file /etc/samba/smbpasswd -or /etc/smbpasswd. When password encryption is disabled, no -data is stored at all. +Samba-3 provides two (2) tools for management of User and machine accounts. These tools are +called smbpasswd and pdbedit. A third tool is under +development but is NOT expected to ship in time for Samba-3.0.0. The new tool will be a TCL/TK +GUI tool that looks much like the MS Windows NT4 Domain User Manager - hopefully this will +be announced in time for samba-3.0.1 release timing. - + + The <emphasis>smbpasswd</emphasis> Command + + + The smbpasswd utility is a utility similar to the passwd + or yppasswd programs. It maintains the two 32 byte password + fields in the passdb backend. + + + + smbpasswd works in a client-server mode where it contacts the + local smbd to change the user's password on its behalf.This has enormous benefits + as follows: + + + + smbpasswd has the capability to change passwords on Windows NT + servers (this only works when the request is sent to the NT Primary Domain Controller + if changing an NT Domain user's password). + + + + smbpasswd can be used to: + + + + + add user or machine accounts + + + + delete user or machine accounts + + + + enable user or machine accounts + + + + disable user or machine accounts + + + + set to NULL user passwords + + + + manage interdomain trust accounts + + + + + To run smbpasswd as a normal user just type: + + + + + $ smbpasswd + Old SMB password: <secret> + + For secret type old value here - or hit return if + there was no old password + + New SMB Password: <new secret> + Repeat New SMB Password: <new secret> + + + + + If the old value does not match the current value stored for that user, or the two + new values do not match each other, then the password will not be changed. + + + + When invoked by an ordinary user it will only allow change of their own + SMB password. + + + + When run by root smbpasswd may take an optional argument, specifying + the user name whose SMB password you wish to change. When run as root, smbpasswd + does not prompt for or check the old password value, thus allowing root to set passwords + for users who have forgotten their passwords. + + + + smbpasswd is designed to work in the way familiar to UNIX + users who use the passwd or yppasswd commands. + While designed for administrative use, this tool provides essential user level + password change capabilities. + + + + For more details on using smbpasswd refer to the man page (the + definitive reference). + + - -TDB -Samba can also store the user data in a "TDB" (Trivial Database). Using this backend -doesn't require any additional configuration. This backend is recommended for new installations that -don not require LDAP. - + + The <emphasis>pdbedit</emphasis> Command + + + pdbedit is a tool that can be used only by root. It is used to + manage the passdb backend. pdbedit can be used to: + + + + + add, remove or modify user accounts + + + + listing user accounts + + + + migrate user accounts + + + + + The pdbedit tool is the only one that can manage the account + security and policy settings. It is capable of all operations that smbpasswd can + do as well as a super set of them. + + + + One particularly important purpose of the pdbedit is to allow + the migration of account information from one passdb backend to another. See the + XML password backend section of this chapter. + + + + The following is an example of the user account information that is stored in + a tdbsam password backend. This listing was produced by running: + + + + pdbedit -Lv met + + Unix username: met + NT username: + Account Flags: [UX ] + User SID: S-1-5-21-1449123459-1407424037-3116680435-2004 + Primary Group SID: S-1-5-21-1449123459-1407424037-3116680435-1201 + Full Name: Melissa E Terpstra + Home Directory: \\frodo\met\Win9Profile + HomeDir Drive: H: + Logon Script: scripts\logon.bat + Profile Path: \\frodo\Profiles\met + Domain: MIDEARTH + Account desc: + Workstations: melbelle + Munged dial: + Logon time: 0 + Logoff time: Mon, 18 Jan 2038 20:14:07 GMT + Kickoff time: Mon, 18 Jan 2038 20:14:07 GMT + Password last set: Sat, 14 Dec 2002 14:37:03 GMT + Password can change: Sat, 14 Dec 2002 14:37:03 GMT + Password must change: Mon, 18 Jan 2038 20:14:07 GMT + + + + -LDAP - - -Introduction - - -This document describes how to use an LDAP directory for storing Samba user -account information traditionally stored in the smbpasswd(5) file. It is -assumed that the reader already has a basic understanding of LDAP concepts -and has a working directory server already installed. For more information -on LDAP architectures and Directories, please refer to the following sites. - - - - OpenLDAP - http://www.openldap.org/ - iPlanet Directory Server - http://iplanet.netscape.com/directory - +Password Backends - O'Reilly Publishing has published - LDAP System Administration - written by Gerald Carter. +Samba-3 offers the greatest flexibility in backend account database design of any SMB/CIFS server +technology available today. The flexibility is immediately obvious as one begins to explore this +capability. -Two additional Samba resources which may prove to be helpful are +It is possible to specify not only multiple different password backends, but even multiple +backends of the same type. For example, to use two different tdbsam databases: - - The Samba-PDC-LDAP-HOWTO - maintained by Ignacio Coupeau. - - The NT migration scripts from IDEALX that are - geared to manage users and group in such a Samba-LDAP Domain Controller configuration. - - - - - - -Encrypted Password Database - -Traditionally, when configuring "encrypt -passwords = yes" in Samba's smb.conf file, user account -information such as username, LM/NT password hashes, password change times, and account -flags have been stored in the smbpasswd(5) file. There are several -disadvantages to this approach for sites with very large numbers of users (counted -in the thousands). + +In smb.conf [globals] + passdb backend = tdbsam:/etc/samba/passdb.tdb, \ + tdbsam:/etc/samba/old-passdb.tdb, guest + - - -The first is that all lookups must be performed sequentially. Given that -there are approximately two lookups per domain logon (one for a normal -session connection such as when mapping a network drive or printer), this -is a performance bottleneck for large sites. What is needed is an indexed approach -such as is used in databases. - - - -The second problem is that administrators who desired to replicate a -smbpasswd file to more than one Samba server were left to use external -tools such as rsync(1) and ssh(1) -and wrote custom, in-house scripts. - - - -And finally, the amount of information which is stored in an -smbpasswd entry leaves no room for additional attributes such as -a home directory, password expiration time, or even a Relative -Identified (RID). - - - -As a result of these defeciencies, a more robust means of storing user attributes -used by smbd was developed. The API which defines access to user accounts -is commonly referred to as the samdb interface (previously this was called the passdb -API, and is still so named in the CVS trees). - + + Plain Text - -There are a few points to stress about that the ldapsam -does not provide. The LDAP support referred to in the this documentation does not -include: - + + Older versions of samba retrieved user information from the unix user database + and eventually some other fields from the file /etc/samba/smbpasswd + or /etc/smbpasswd. When password encryption is disabled, no + SMB specific data is stored at all. Instead all operations are conduected via the way + that the samba host OS will access it's /etc/passwd database. + eg: On Linux systems that is done via PAM. + - - A means of retrieving user account information from - an Windows 2000 Active Directory server. - A means of replacing /etc/passwd. - + - -The second item can be accomplished by using LDAP NSS and PAM modules. LGPL -versions of these libraries can be obtained from PADL Software -(http://www.padl.com/). More -information about the configuration of these packages may be found at "LDAP, -System Administration; Gerald Carter, O'Reilly; Chapter 6: Replacing NIS". - + + smbpasswd - Encrypted Password Database + + + Traditionally, when configuring "encrypt + passwords = yes" in Samba's smb.conf file, user account + information such as username, LM/NT password hashes, password change times, and account + flags have been stored in the smbpasswd(5) file. There are several + disadvantages to this approach for sites with very large numbers of users (counted + in the thousands). + + + + + The first is that all lookups must be performed sequentially. Given that + there are approximately two lookups per domain logon (one for a normal + session connection such as when mapping a network drive or printer), this + is a performance bottleneck for large sites. What is needed is an indexed approach + such as is used in databases. + + + + The second problem is that administrators who desire to replicate a smbpasswd file + to more than one Samba server were left to use external tools such as + rsync(1) and ssh(1) and wrote custom, + in-house scripts. + + + + And finally, the amount of information which is stored in an smbpasswd entry leaves + no room for additional attributes such as a home directory, password expiration time, + or even a Relative Identified (RID). + + + + + As a result of these defeciencies, a more robust means of storing user attributes + used by smbd was developed. The API which defines access to user accounts + is commonly referred to as the samdb interface (previously this was called the passdb + API, and is still so named in the Samba CVS trees). + + + + Samba-3 provides an enhanced set of passdb backends that overcome the deficiencies + of the smbpasswd plain text database. These are tdbsam, ldapsam, and xmlsam. + Of these ldapsam will be of most interest to large corporate or enterprise sites. + - + - -Supported LDAP Servers + + tdbsam - -The LDAP samdb code in 2.2.3 (and later) has been developed and tested -using the OpenLDAP 2.0 and 2.1 server and client libraries. -The same code should be able to work with Netscape's Directory Server -and client SDK. However, due to lack of testing so far, there are bound -to be compile errors and bugs. These should not be hard to fix. Please submit -fixes via . - + Samba can store user and machine account data in a "TDB" (Trivial Database). + Using this backend doesn't require any additional configuration. This backend is + recommended for new installations that do not require LDAP. + - + + As a general guide the Samba-Team do NOT recommend using the tdbsam backend for sites + that have 250 or more users. Additionally, tdbsam is not capable of scaling for use + in sites that require PDB/BDC implmentations that requires replication of the account + database. Clearly, for reason of scalability the use of ldapsam should be encouraged. + - -Schema and Relationship to the RFC 2307 posixAccount + + + ldapsam + + + There are a few points to stress that the ldapsam does not provide. The LDAP + support referred to in the this documentation does not include: + + + + A means of retrieving user account information from + an Windows 200x Active Directory server. + A means of replacing /etc/passwd. + + + + The second item can be accomplished by using LDAP NSS and PAM modules. LGPL + versions of these libraries can be obtained from PADL Software + (http://www.padl.com/). More + information about the configuration of these packages may be found at "LDAP, + System Administration; Gerald Carter, O'Reilly; Chapter 6: Replacing NIS". + Refer to + http://safari.oreilly.com/?XmlId=1-56592-491-6 for those who might wish to know + more about configuration and adminstration of an OpenLDAP server. + + + + This document describes how to use an LDAP directory for storing Samba user + account information traditionally stored in the smbpasswd(5) file. It is + assumed that the reader already has a basic understanding of LDAP concepts + and has a working directory server already installed. For more information + on LDAP architectures and Directories, please refer to the following sites. + + + + OpenLDAP - http://www.openldap.org/ + iPlanet Directory Server - + http://iplanet.netscape.com/directory + + + + Two additional Samba resources which may prove to be helpful are + + + + The Samba-PDC-LDAP-HOWTO + maintained by Ignacio Coupeau. + + The NT migration scripts from IDEALX that are + geared to manage users and group in such a Samba-LDAP Domain Controller configuration. + + + + + Supported LDAP Servers + + + The LDAP ldapsam code has been developed and tested using the OpenLDAP 2.0 and 2.1 server and + client libraries. The same code should work with Netscape's Directory Server and client SDK. + However, there are bound to be compile errors and bugs. These should not be hard to fix. + Please submit fixes via . + + + + + + Schema and Relationship to the RFC 2307 posixAccount + + + + Samba 3.0 includes the necessary schema file for OpenLDAP 2.0 in + examples/LDAP/samba.schema. The sambaAccount objectclass is given here: + -Samba 3.0 includes the necessary schema file for OpenLDAP 2.0 in -examples/LDAP/samba.schema. The sambaAccount objectclass is given here: - - - + objectclass ( 1.3.6.1.4.1.7165.2.2.3 NAME 'sambaAccount' SUP top AUXILIARY - DESC 'Samba Auxilary Account' - MUST ( uid $ rid ) - MAY ( cn $ lmPassword $ ntPassword $ pwdLastSet $ logonTime $ - logoffTime $ kickoffTime $ pwdCanChange $ pwdMustChange $ acctFlags $ - displayName $ smbHome $ homeDrive $ scriptPath $ profilePath $ - description $ userWorkstations $ primaryGroupID $ domain )) - - - -The samba.schema file has been formatted for -OpenLDAP 2.0/2.1. The OID's are -owned by the Samba Team and as such is legal to be openly published. -If you translate the schema to be used with Netscape DS, please -submit the modified schema file as a patch to jerry@samba.org - - - -Just as the smbpasswd file is meant to store information which supplements a -user's /etc/passwd entry, so is the sambaAccount object -meant to supplement the UNIX user account information. A sambaAccount is a -STRUCTURAL objectclass so it can be stored individually -in the directory. However, there are several fields (e.g. uid) which overlap -with the posixAccount objectclass outlined in RFC2307. This is by design. - - - - - -In order to store all user account information (UNIX and Samba) in the directory, -it is necessary to use the sambaAccount and posixAccount objectclasses in -combination. However, smbd will still obtain the user's UNIX account -information via the standard C library calls (e.g. getpwnam(), et. al.). -This means that the Samba server must also have the LDAP NSS library installed -and functioning correctly. This division of information makes it possible to -store all Samba account information in LDAP, but still maintain UNIX account -information in NIS while the network is transitioning to a full LDAP infrastructure. + DESC 'Samba Auxilary Account' + MUST ( uid $ rid ) + MAY ( cn $ lmPassword $ ntPassword $ pwdLastSet $ logonTime $ + logoffTime $ kickoffTime $ pwdCanChange $ pwdMustChange $ acctFlags $ + displayName $ smbHome $ homeDrive $ scriptPath $ profilePath $ + description $ userWorkstations $ primaryGroupID $ domain )) + - - - -Configuring Samba with LDAP - - - -OpenLDAP configuration - -To include support for the sambaAccount object in an OpenLDAP directory -server, first copy the samba.schema file to slapd's configuration directory. -The samba.schema file can be found in the directory examples/LDAP -in the samba source distribution. - + + The samba.schema file has been formatted for OpenLDAP 2.0/2.1. + The OID's are owned by the Samba Team and as such is legal to be openly published. + If you translate the schema to be used with Netscape DS, please + submit the modified schema file as a patch to + jerry@samba.org + + + + Just as the smbpasswd file is meant to store information which supplements a + user's /etc/passwd entry, so is the sambaAccount object + meant to supplement the UNIX user account information. A sambaAccount is a + STRUCTURAL objectclass so it can be stored individually + in the directory. However, there are several fields (e.g. uid) which overlap + with the posixAccount objectclass outlined in RFC2307. This is by design. + + + + + + In order to store all user account information (UNIX and Samba) in the directory, + it is necessary to use the sambaAccount and posixAccount objectclasses in + combination. However, smbd will still obtain the user's UNIX account + information via the standard C library calls (e.g. getpwnam(), et. al.). + This means that the Samba server must also have the LDAP NSS library installed + and functioning correctly. This division of information makes it possible to + store all Samba account information in LDAP, but still maintain UNIX account + information in NIS while the network is transitioning to a full LDAP infrastructure. + + + + + OpenLDAP configuration + + + To include support for the sambaAccount object in an OpenLDAP directory + server, first copy the samba.schema file to slapd's configuration directory. + The samba.schema file can be found in the directory examples/LDAP + in the samba source distribution. + + root# cp samba.schema /etc/openldap/schema/ + - -Next, include the samba.schema file in slapd.conf. -The sambaAccount object contains two attributes which depend upon other schema -files. The 'uid' attribute is defined in cosine.schema and -the 'displayName' attribute is defined in the inetorgperson.schema -file. Both of these must be included before the samba.schema file. - + + Next, include the samba.schema file in slapd.conf. + The sambaAccount object contains two attributes which depend upon other schema + files. The 'uid' attribute is defined in cosine.schema and + the 'displayName' attribute is defined in the inetorgperson.schema + file. Both of these must be included before the samba.schema file. + - + + ## /etc/openldap/slapd.conf ## schema files (core.schema is required by default) @@ -451,573 +781,626 @@ include /etc/openldap/schema/cosine.schema include /etc/openldap/schema/inetorgperson.schema include /etc/openldap/schema/samba.schema include /etc/openldap/schema/nis.schema - .... - + + + + + It is recommended that you maintain some indices on some of the most usefull attributes, + like in the following example, to speed up searches made on sambaAccount objectclasses + (and possibly posixAccount and posixGroup as well). + -It is recommended that you maintain some indices on some of the most usefull attributes, -like in the following example, to speed up searches made on sambaAccount objectclasses -(and possibly posixAccount and posixGroup as well). - - + # Indices to maintain -## required by OpenLDAP 2.0 -index objectclass eq +## required by OpenLDAP +index objectclass eq -## support pdb_getsampwnam() -index uid pres,eq -## support pdb_getsambapwrid() -index rid eq +index cn pres,sub,eq +index sn pres,sub,eq +## required to support pdb_getsampwnam +index uid pres,sub,eq +## required to support pdb_getsambapwrid() +index displayName pres,sub,eq ## uncomment these if you are storing posixAccount and ## posixGroup entries in the directory as well -##index uidNumber eq -##index gidNumber eq -##index cn eq -##index memberUid eq - -# (both fetched via ldapsearch): -index primaryGroupID eq -index displayName pres,eq - - - -Remember to restart slapd after making these changes: - -root# /etc/init.d/slapd restart - - - +##index uidNumber eq +##index gidNumber eq +##index memberUid eq + +index rid eq +index sambaSID eq +index sambaPrimaryGroupSID eq +index sambaDomainName eq +index default sub + + - -Configuring Samba + + Create the new index by executing: + -The following parameters are available in smb.conf only if your version of samba was built -with LDAP support. Samba automatically builds with LDAP support if the LDAP libraries are -found. + +./sbin/slapindex -f slapd.conf + - - passdb backend = ldapsam:url - ldap ssl - ldap admin dn - ldap suffix - ldap filter - ldap machine suffix - ldap user suffix - ldap delete dn - ldap passwd sync - ldap trust ids - + + Remember to restart slapd after making these changes: + -These are described in the smb.conf(5) man -page and so will not be repeated here. However, a sample smb.conf file for -use with an LDAP directory could appear as + +root# /etc/init.d/slapd restart + - -## /usr/local/samba/lib/smb.conf -[global] - security = user - encrypt passwords = yes - - netbios name = TASHTEGO - workgroup = NARNIA - - # ldap related parameters + + + + Configuring Samba + + + The following parameters are available in smb.conf only with --with-ldapsam + was included when compiling Samba. The following parameters are available in smb.conf only if your + version of samba was built with LDAP support. Samba automatically builds with LDAP support if the + LDAP libraries are found. + + + + passdb backend ldapsam:url + ldap ssl + ldap admin dn + ldap suffix + ldap filter + ldap machine suffix + ldap user suffix + ldap delete dn + ldap passwd sync + ldap trust ids + + + + + These are described in the smb.conf(5) man + page and so will not be repeated here. However, a sample smb.conf file for + use with an LDAP directory could appear as + - # define the DN to use when binding to the directory servers - # The password for this DN is not stored in smb.conf. Rather it - # must be set by using 'smbpasswd -w secretpw' to store the - # passphrase in the secrets.tdb file. If the "ldap admin dn" values - # change, this password will need to be reset. - ldap admin dn = "cn=Samba Manager,ou=people,dc=samba,dc=org" - - # Define the SSL option when connecting to the directory - # ('off', 'start tls', or 'on' (default)) - ldap ssl = start tls - - # syntax: passdb backend = ldapsam:ldap://server-name[:port] - passdb backend = ldapsam:ldap://ahab.samba.org - - # smbpasswd -x delete the entire dn-entry - ldap delete dn = no - - # the machine and user suffix added to the base suffix - # wrote WITHOUT quotes. NULL siffixes by default - ldap user suffix = ou=People - ldap machine suffix = ou=Systems - - # specify the base DN to use when searching the directory - ldap suffix = "ou=people,dc=samba,dc=org" - - # Trust unix account information in LDAP (see the smb.conf manpage for details) - ldap trust ids = Yes + + + ## /usr/local/samba/lib/smb.conf + [global] + security = user + encrypt passwords = yes - # generally the default ldap search filter is ok - # ldap filter = "(&(uid=%u)(objectclass=sambaAccount))" - + netbios name = TASHTEGO + workgroup = NARNIA + # ldap related parameters - - + # define the DN to use when binding to the directory servers + # The password for this DN is not stored in smb.conf. Rather it + # must be set by using 'smbpasswd -w secretpw' to store the + # passphrase in the secrets.tdb file. If the "ldap admin dn" values + # change, this password will need to be reset. + ldap admin dn = "cn=Samba Manager,ou=people,dc=samba,dc=org" + # Define the SSL option when connecting to the directory + # ('off', 'start tls', or 'on' (default)) + ldap ssl = start tls - -Accounts and Groups management + # syntax: passdb backend = ldapsam:ldap://server-name[:port] + passdb backend ldapsam:ldap://funball.samba.org - -As users accounts are managed thru the sambaAccount objectclass, you should -modify your existing administration tools to deal with sambaAccount attributes. - + # smbpasswd -x delete the entire dn-entry + ldap delete dn = no - -Machines accounts are managed with the sambaAccount objectclass, just -like users accounts. However, it's up to you to store thoses accounts -in a different tree of you LDAP namespace: you should use -"ou=Groups,dc=plainjoe,dc=org" to store groups and -"ou=People,dc=plainjoe,dc=org" to store users. Just configure your -NSS and PAM accordingly (usually, in the /etc/ldap.conf configuration -file). - + # the machine and user suffix added to the base suffix + # wrote WITHOUT quotes. NULL siffixes by default + ldap user suffix = ou=People + ldap machine suffix = ou=Systems - -In Samba release 3.0, the group management system is based on posix -groups. This means that Samba makes usage of the posixGroup objectclass. -For now, there is no NT-like group system management (global and local -groups). - + # Trust unix account information in LDAP + # (see the smb.conf manpage for details) + ldap trust ids = Yes - + # specify the base DN to use when searching the directory + ldap suffix = "ou=people,dc=samba,dc=org" - -Security and sambaAccount + # generally the default ldap search filter is ok + # ldap filter = "(&(uid=%u)(objectclass=sambaAccount))" + + + + + + Accounts and Groups management + + + As users accounts are managed thru the sambaAccount objectclass, you should + modify your existing administration tools to deal with sambaAccount attributes. + + + + Machines accounts are managed with the sambaAccount objectclass, just + like users accounts. However, it's up to you to store thoses accounts + in a different tree of you LDAP namespace: you should use + "ou=Groups,dc=plainjoe,dc=org" to store groups and + "ou=People,dc=plainjoe,dc=org" to store users. Just configure your + NSS and PAM accordingly (usually, in the /etc/ldap.conf configuration + file). + + + + In Samba release 3.0, the group management system is based on posix + groups. This means that Samba makes usage of the posixGroup objectclass. + For now, there is no NT-like group system management (global and local + groups). + + + + + + Security and sambaAccount + + + + There are two important points to remember when discussing the security + of sambaAccount entries in the directory. + + + + Never retrieve the lmPassword or + ntPassword attribute values over an unencrypted LDAP session. + Never allow non-admin users to + view the lmPassword or ntPassword attribute values. + + + + These password hashes are clear text equivalents and can be used to impersonate + the user without deriving the original clear text strings. For more information + on the details of LM/NT password hashes, refer to the + Account Information Database section of this chapter. + + + + To remedy the first security issue, the "ldap ssl" smb.conf parameter defaults + to require an encrypted session (ldap ssl = on) using + the default port of 636 + when contacting the directory server. When using an OpenLDAP server, it + is possible to use the use the StartTLS LDAP extended operation in the place of + LDAPS. In either case, you are strongly discouraged to disable this security + (ldap ssl = off). + + + + Note that the LDAPS protocol is deprecated in favor of the LDAPv3 StartTLS + extended operation. However, the OpenLDAP library still provides support for + the older method of securing communication between clients and servers. + + + + The second security precaution is to prevent non-administrative users from + harvesting password hashes from the directory. This can be done using the + following ACL in slapd.conf: + - -There are two important points to remember when discussing the security -of sambaAccount entries in the directory. - + + + ## allow the "ldap admin dn" access, but deny everyone else + access to attrs=lmPassword,ntPassword + by dn="cn=Samba Admin,ou=people,dc=plainjoe,dc=org" write + by * none + + - - Never retrieve the lmPassword or - ntPassword attribute values over an unencrypted LDAP session. - Never allow non-admin users to - view the lmPassword or ntPassword attribute values. - + - -These password hashes are clear text equivalents and can be used to impersonate -the user without deriving the original clear text strings. For more information -on the details of LM/NT password hashes, refer to the first sections of this chapter. - + + LDAP special attributes for sambaAccounts - -To remedy the first security issue, the "ldap ssl" smb.conf parameter defaults -to require an encrypted session (ldap ssl = on) using -the default port of 636 -when contacting the directory server. When using an OpenLDAP server, it -is possible to use the use the StartTLS LDAP extended operation in the place of -LDAPS. In either case, you are strongly discouraged to disable this security -(ldap ssl = off). - + + The sambaAccount objectclass is composed of the following attributes: + - -Note that the LDAPS protocol is deprecated in favor of the LDAPv3 StartTLS -extended operation. However, the OpenLDAP library still provides support for -the older method of securing communication between clients and servers. - + + lmPassword: the LANMAN password 16-byte hash stored as a character + representation of a hexidecimal string. - -The second security precaution is to prevent non-administrative users from -harvesting password hashes from the directory. This can be done using the -following ACL in slapd.conf: - + ntPassword: the NT password hash 16-byte stored as a character + representation of a hexidecimal string. - -## allow the "ldap admin dn" access, but deny everyone else -access to attrs=lmPassword,ntPassword - by dn="cn=Samba Admin,ou=people,dc=plainjoe,dc=org" write - by * none - + pwdLastSet: The integer time in seconds since 1970 when the + lmPassword and ntPassword attributes were last set. + + acctFlags: string of 11 characters surrounded by square brackets [] + representing account flags such as U (user), W(workstation), X(no password expiration), + I(Domain trust account), H(Home dir required), S(Server trust account), + and D(disabled). - + logonTime: Integer value currently unused + logoffTime: Integer value currently unused + kickoffTime: Integer value currently unused - -LDAP specials attributes for sambaAccounts + pwdCanChange: Integer value currently unused - -The sambaAccount objectclass is composed of the following attributes: - + pwdMustChange: Integer value currently unused - + homeDrive: specifies the drive letter to which to map the + UNC path specified by homeDirectory. The drive letter must be specified in the form "X:" + where X is the letter of the drive to map. Refer to the "logon drive" parameter in the + smb.conf(5) man page for more information. - lmPassword: the LANMAN password 16-byte hash stored as a character - representation of a hexidecimal string. + scriptPath: The scriptPath property specifies the path of + the user's logon script, .CMD, .EXE, or .BAT file. The string can be null. The path + is relative to the netlogon share. Refer to the "logon script" parameter in the + smb.conf(5) man page for more information. - ntPassword: the NT password hash 16-byte stored as a character - representation of a hexidecimal string. + profilePath: specifies a path to the user's profile. + This value can be a null string, a local absolute path, or a UNC path. Refer to the + "logon path" parameter in the smb.conf(5) man page for more information. - pwdLastSet: The integer time in seconds since 1970 when the - lmPassword and ntPassword attributes were last set. - + smbHome: The homeDirectory property specifies the path of + the home directory for the user. The string can be null. If homeDrive is set and specifies + a drive letter, homeDirectory should be a UNC path. The path must be a network + UNC path of the form \\server\share\directory. This value can be a null string. + Refer to the "logon home" parameter in the smb.conf(5) man page for more information. + - acctFlags: string of 11 characters surrounded by square brackets [] - representing account flags such as U (user), W(workstation), X(no password expiration), and - D(disabled). + userWorkstation: character string value currently unused. + - logonTime: Integer value currently unused + rid: the integer representation of the user's relative identifier + (RID). - logoffTime: Integer value currently unused + primaryGroupID: the relative identifier (RID) of the primary group + of the user. - kickoffTime: Integer value currently unused + domain: domain the user is part of. + - pwdCanChange: Integer value currently unused + + The majority of these parameters are only used when Samba is acting as a PDC of + a domain (refer to the Samba-PDC-HOWTO for details on + how to configure Samba as a Primary Domain Controller). The following four attributes + are only stored with the sambaAccount entry if the values are non-default values: + - pwdMustChange: Integer value currently unused + + smbHome + scriptPath + logonPath + homeDrive + - homeDrive: specifies the drive letter to which to map the - UNC path specified by homeDirectory. The drive letter must be specified in the form "X:" - where X is the letter of the drive to map. Refer to the "logon drive" parameter in the - smb.conf(5) man page for more information. + + These attributes are only stored with the sambaAccount entry if + the values are non-default values. For example, assume TASHTEGO has now been + configured as a PDC and that logon home = \\%L\%u was defined in + its smb.conf file. When a user named "becky" logons to the domain, + the logon home string is expanded to \\TASHTEGO\becky. + If the smbHome attribute exists in the entry "uid=becky,ou=people,dc=samba,dc=org", + this value is used. However, if this attribute does not exist, then the value + of the logon home parameter is used in its place. Samba + will only write the attribute value to the directory entry if the value is + something other than the default (e.g. \\MOBY\becky). + - scriptPath: The scriptPath property specifies the path of - the user's logon script, .CMD, .EXE, or .BAT file. The string can be null. The path - is relative to the netlogon share. Refer to the "logon script" parameter in the - smb.conf(5) man page for more information. + - profilePath: specifies a path to the user's profile. - This value can be a null string, a local absolute path, or a UNC path. Refer to the - "logon path" parameter in the smb.conf(5) man page for more information. + + Example LDIF Entries for a sambaAccount - smbHome: The homeDirectory property specifies the path of - the home directory for the user. The string can be null. If homeDrive is set and specifies - a drive letter, homeDirectory should be a UNC path. The path must be a network - UNC path of the form \\server\share\directory. This value can be a null string. - Refer to the "logon home" parameter in the smb.conf(5) man page for more information. - + + The following is a working LDIF with the inclusion of the posixAccount objectclass: + - userWorkstation: character string value currently unused. - + + + dn: uid=guest2, ou=people,dc=plainjoe,dc=org + ntPassword: 878D8014606CDA29677A44EFA1353FC7 + pwdMustChange: 2147483647 + primaryGroupID: 1201 + lmPassword: 552902031BEDE9EFAAD3B435B51404EE + pwdLastSet: 1010179124 + logonTime: 0 + objectClass: sambaAccount + uid: guest2 + kickoffTime: 2147483647 + acctFlags: [UX ] + logoffTime: 2147483647 + rid: 19006 + pwdCanChange: 0 + + - rid: the integer representation of the user's relative identifier - (RID). + + The following is an LDIF entry for using both the sambaAccount and + posixAccount objectclasses: + - primaryGroupID: the relative identifier (RID) of the primary group - of the user. + + + dn: uid=gcarter, ou=people,dc=plainjoe,dc=org + logonTime: 0 + displayName: Gerald Carter + lmPassword: 552902031BEDE9EFAAD3B435B51404EE + primaryGroupID: 1201 + objectClass: posixAccount + objectClass: sambaAccount + acctFlags: [UX ] + userPassword: {crypt}BpM2ej8Rkzogo + uid: gcarter + uidNumber: 9000 + cn: Gerald Carter + loginShell: /bin/bash + logoffTime: 2147483647 + gidNumber: 100 + kickoffTime: 2147483647 + pwdLastSet: 1010179230 + rid: 19000 + homeDirectory: /home/tashtego/gcarter + pwdCanChange: 0 + pwdMustChange: 2147483647 + ntPassword: 878D8014606CDA29677A44EFA1353FC7 + + - domain: domain the user is part of. + - + + Password synchronisation - -The majority of these parameters are only used when Samba is acting as a PDC of -a domain (refer to for details on -how to configure Samba as a Primary Domain Controller). The following four attributes -are only stored with the sambaAccount entry if the values are non-default values: - + + Since 3.0 Samba can update the non-samba (LDAP) password stored with an account. When + using pam_ldap, this allows changing both unix and windows passwords at once. + - - smbHome - scriptPath - logonPath - homeDrive - + The ldap passwd sync options can have the following values: - -These attributes are only stored with the sambaAccount entry if -the values are non-default values. For example, assume TASHTEGO has now been -configured as a PDC and that logon home = \\%L\%u was defined in -its smb.conf file. When a user named "becky" logons to the domain, -the logon home string is expanded to \\TASHTEGO\becky. -If the smbHome attribute exists in the entry "uid=becky,ou=people,dc=samba,dc=org", -this value is used. However, if this attribute does not exist, then the value -of the logon home parameter is used in its place. Samba -will only write the attribute value to the directory entry if the value is -something other than the default (e.g. \\MOBY\becky). - + + + yes + When the user changes his password, update + ntPassword, lmPassword + and the password fields. + + + no + Only update ntPassword and lmPassword. + - + + only + Only update the LDAP password and let the LDAP server worry + about the other fields. This option is only available when + the LDAP library supports LDAP_EXOP_X_MODIFY_PASSWD. + + + More information can be found in the smb.conf manpage. + + - -Example LDIF Entries for a sambaAccount + + ldap trust ids + + LDAP Performance can be approved by using the ldap trust ids parameter. + See the smb.conf manpage for details. + - -The following is a working LDIF with the inclusion of the posixAccount objectclass: - + - -dn: uid=guest2, ou=people,dc=plainjoe,dc=org -ntPassword: 878D8014606CDA29677A44EFA1353FC7 -pwdMustChange: 2147483647 -primaryGroupID: 1201 -lmPassword: 552902031BEDE9EFAAD3B435B51404EE -pwdLastSet: 1010179124 -logonTime: 0 -objectClass: sambaAccount -uid: guest2 -kickoffTime: 2147483647 -acctFlags: [UX ] -logoffTime: 2147483647 -rid: 19006 -pwdCanChange: 0 - + - -The following is an LDIF entry for using both the sambaAccount and -posixAccount objectclasses: - + + MySQL - -dn: uid=gcarter, ou=people,dc=plainjoe,dc=org -logonTime: 0 -displayName: Gerald Carter -lmPassword: 552902031BEDE9EFAAD3B435B51404EE -primaryGroupID: 1201 -objectClass: posixAccount -objectClass: sambaAccount -acctFlags: [UX ] -userPassword: {crypt}BpM2ej8Rkzogo -uid: gcarter -uidNumber: 9000 -cn: Gerald Carter -loginShell: /bin/bash -logoffTime: 2147483647 -gidNumber: 100 -kickoffTime: 2147483647 -pwdLastSet: 1010179230 -rid: 19000 -homeDirectory: /home/tashtego/gcarter -pwdCanChange: 0 -pwdMustChange: 2147483647 -ntPassword: 878D8014606CDA29677A44EFA1353FC7 - - - - - -Password synchronisation + + Stuff goes here! + - -Since 3.0 Samba can update the non-samba (LDAP) password stored with an account. When -using pam_ldap, this allows changing both unix and windows passwords at once. - + + Creating the database -The ldap passwd sync options can have the following values: + + You either can set up your own table and specify the field names to pdb_mysql (see below + for the column names) or use the default table. The file examples/pdb/mysql/mysql.dump + contains the correct queries to create the required tables. Use the command : - - - yes - When the user changes his password, update - ntPassword, lmPassword - and the password fields. - + mysql -uusername -hhostname -ppassword databasename > /path/to/samba/examples/pdb/mysql/mysql.dump + + - - no - Only update ntPassword and lmPassword. - + + Configuring - - only - Only update the LDAP password and let the LDAP server worry - about the other fields. This option is only available when - the LDAP library supports LDAP_EXOP_X_MODIFY_PASSWD. - - + This plugin lacks some good documentation, but here is some short info: -More information can be found in the smb.conf manpage. - + Add a the following to the passdb backend variable in your smb.conf: + + passdb backend = [other-plugins] mysql:identifier [other-plugins] + + - + The identifier can be any string you like, as long as it doesn't collide with + the identifiers of other plugins or other instances of pdb_mysql. If you + specify multiple pdb_mysql.so entries in 'passdb backend', you also need to + use different identifiers! + - -ldap trust ids + + Additional options can be given thru the smb.conf file in the [global] section. + - -LDAP Performance can be approved by using the ldap trust ids parameter. -See the smb.conf manpage for details. - + + + identifier:mysql host - host name, defaults to 'localhost' + identifier:mysql password + identifier:mysql user - defaults to 'samba' + identifier:mysql database - defaults to 'samba' + identifier:mysql port - defaults to 3306 + identifier:table - Name of the table containing users + + - + + + Since the password for the mysql user is stored in the + smb.conf file, you should make the the smb.conf file + readable only to the user that runs samba. This is considered a security + bug and will be fixed soon. + + - + Names of the columns in this table(I've added column types those columns should have first): - -MySQL + + + identifier:logon time column - int(9) + identifier:logoff time column - int(9) + identifier:kickoff time column - int(9) + identifier:pass last set time column - int(9) + identifier:pass can change time column - int(9) + identifier:pass must change time column - int(9) + identifier:username column - varchar(255) - unix username + identifier:domain column - varchar(255) - NT domain user is part of + identifier:nt username column - varchar(255) - NT username + identifier:fullname column - varchar(255) - Full name of user + identifier:home dir column - varchar(255) - Unix homedir path + identifier:dir drive column - varchar(2) - Directory drive path (eg: 'H:') + identifier:logon script column - varchar(255) + - Batch file to run on client side when logging on + identifier:profile path column - varchar(255) - Path of profile + identifier:acct desc column - varchar(255) - Some ASCII NT user data + identifier:workstations column - varchar(255) + - Workstations user can logon to (or NULL for all) + identifier:unknown string column - varchar(255) - unknown string + identifier:munged dial column - varchar(255) - ? + identifier:user sid column - varchar(255) - NT user SID + identifier:group sid column - varchar(255) - NT group ID + identifier:lanman pass column - varchar(255) - encrypted lanman password + identifier:nt pass column - varchar(255) - encrypted nt passwd + identifier:plain pass column - varchar(255) - plaintext password + identifier:acct control column - int(9) - nt user data + identifier:unknown 3 column - int(9) - unknown + identifier:logon divs column - int(9) - ? + identifier:hours len column - int(9) - ? + identifier:unknown 5 column - int(9) - unknown + identifier:unknown 6 column - int(9) - unknown + + - -Creating the database + + Eventually, you can put a colon (:) after the name of each column, which + should specify the column to update when updating the table. You can also + specify nothing behind the colon - then the data from the field will not be + updated. + - -You either can set up your own table and specify the field names to pdb_mysql (see below -for the column names) or use the default table. The file examples/pdb/mysql/mysql.dump -contains the correct queries to create the required tables. Use the command : + -mysql -uusername -hhostname -ppassword databasename > /path/to/samba/examples/pdb/mysql/mysql.dump + + Using plaintext passwords or encrypted password - - + + I strongly discourage the use of plaintext passwords, however, you can use them: + - -Configuring + + If you would like to use plaintext passwords, set + 'identifier:lanman pass column' and 'identifier:nt pass column' to + 'NULL' (without the quotes) and 'identifier:plain pass column' to the + name of the column containing the plaintext passwords. + -This plugin lacks some good documentation, but here is some short info: + + If you use encrypted passwords, set the 'identifier:plain pass + column' to 'NULL' (without the quotes). This is the default. + -Add a the following to the passdb backend variable in your smb.conf: - -passdb backend = [other-plugins] mysql:identifier [other-plugins] - - + -The identifier can be any string you like, as long as it doesn't collide with -the identifiers of other plugins or other instances of pdb_mysql. If you -specify multiple pdb_mysql.so entries in 'passdb backend', you also need to -use different identifiers! - + + Getting non-column data from the table - -Additional options can be given thru the smb.conf file in the [global] section. - + + It is possible to have not all data in the database and making some 'constant'. + - -identifier:mysql host - host name, defaults to 'localhost' -identifier:mysql password -identifier:mysql user - defaults to 'samba' -identifier:mysql database - defaults to 'samba' -identifier:mysql port - defaults to 3306 -identifier:table - Name of the table containing users - + + For example, you can set 'identifier:fullname column' to : + CONCAT(First_name,' ',Sur_name) + - - -Since the password for the mysql user is stored in the -smb.conf file, you should make the the smb.conf file -readable only to the user that runs samba. This is considered a security -bug and will be fixed soon. - - - -Names of the columns in this table(I've added column types those columns should have first): - - -identifier:logon time column - int(9) -identifier:logoff time column - int(9) -identifier:kickoff time column - int(9) -identifier:pass last set time column - int(9) -identifier:pass can change time column - int(9) -identifier:pass must change time column - int(9) -identifier:username column - varchar(255) - unix username -identifier:domain column - varchar(255) - NT domain user is part of -identifier:nt username column - varchar(255) - NT username -identifier:fullname column - varchar(255) - Full name of user -identifier:home dir column - varchar(255) - Unix homedir path -identifier:dir drive column - varchar(2) - Directory drive path (eg: 'H:') -identifier:logon script column - varchar(255) - - Batch file to run on client side when logging on -identifier:profile path column - varchar(255) - Path of profile -identifier:acct desc column - varchar(255) - Some ASCII NT user data -identifier:workstations column - varchar(255) - - Workstations user can logon to (or NULL for all) -identifier:unknown string column - varchar(255) - unknown string -identifier:munged dial column - varchar(255) - ? -identifier:user sid column - varchar(255) - NT user SID -identifier:group sid column - varchar(255) - NT group ID -identifier:lanman pass column - varchar(255) - encrypted lanman password -identifier:nt pass column - varchar(255) - encrypted nt passwd -identifier:plain pass column - varchar(255) - plaintext password -identifier:acct control column - int(9) - nt user data -identifier:unknown 3 column - int(9) - unknown -identifier:logon divs column - int(9) - ? -identifier:hours len column - int(9) - ? -identifier:unknown 5 column - int(9) - unknown -identifier:unknown 6 column - int(9) - unknown - + + Or, set 'identifier:workstations column' to : + NULL - -Eventually, you can put a colon (:) after the name of each column, which -should specify the column to update when updating the table. You can also -specify nothing behind the colon - then the data from the field will not be -updated. - + See the MySQL documentation for more language constructs. - + + - -Using plaintext passwords or encrypted password + + XML - -I strongly discourage the use of plaintext passwords, however, you can use them: - + This module requires libxml2 to be installed. - -If you would like to use plaintext passwords, set -'identifier:lanman pass column' and 'identifier:nt pass column' to -'NULL' (without the quotes) and 'identifier:plain pass column' to the -name of the column containing the plaintext passwords. - + The usage of pdb_xml is pretty straightforward. To export data, use: + - -If you use encrypted passwords, set the 'identifier:plain pass -column' to 'NULL' (without the quotes). This is the default. - + + pdbedit -e xml:filename + - + + (where filename is the name of the file to put the data in) + - -Getting non-column data from the table + + To import data, use: + pdbedit -i xml:filename -e current-pdb + - -It is possible to have not all data in the database and making some 'constant'. - + + Where filename is the name to read the data from and current-pdb to put it in. + - -For example, you can set 'identifier:fullname column' to : -CONCAT(First_name,' ',Sur_name) - + + For example: To migrate (copy) the smbpasswd database into a tdbsam database: + - -Or, set 'identifier:workstations column' to : -NULL + + + In your smb.conf file [globals]: + passdb backend = tdbsam, smbpasswd, guest -See the MySQL documentation for more language constructs. - + then execute (as root): + pdbedit -i smbpasswd -e tdbsam + + + -XML - -This module requires libxml2 to be installed. - -The usage of pdb_xml is pretty straightforward. To export data, use: - +Common Errors - pdbedit -e xml:filename +Put stuff here - -(where filename is the name of the file to put the data in) - - - -To import data, use: -pdbedit -i xml:filename -e current-pdb - - -Where filename is the name to read the data from and current-pdb to put it in. - - -- cgit From bf6a38c8945e59582dda029d55a5299192f052b9 Mon Sep 17 00:00:00 2001 From: John Terpstra Date: Sun, 25 May 2003 08:21:45 +0000 Subject: Fix typos, update to sync HEAD and 3.0.0. (This used to be commit 58750141696feddfeef9ea817b44e4cdfe3afd51) --- docs/docbook/projdoc/ServerType.xml | 9 --------- docs/docbook/projdoc/Speed.xml | 10 ++++++---- docs/docbook/projdoc/StandAloneServer.xml | 17 +++++++++-------- docs/docbook/projdoc/passdb.xml | 4 ++-- docs/docbook/projdoc/samba-doc.xml | 6 +++--- 5 files changed, 20 insertions(+), 26 deletions(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/ServerType.xml b/docs/docbook/projdoc/ServerType.xml index 9081956bb0..ecfeb41735 100644 --- a/docs/docbook/projdoc/ServerType.xml +++ b/docs/docbook/projdoc/ServerType.xml @@ -436,15 +436,6 @@ be determined from a domain name. In essence a samba server that is in workgroup mode. - -Server level security is incompatible with the newer security features -in recent MS Windows networking protocols. In particular it is incompatible with NTLMv2. -Server Mode security also breaks Sign and Seal interoperability because only a domain member -can sign packets in the manner in which it is currently implemented in Samba-3. -If you chose to use Server Mode security this means it is necessary to disable Sign and Seal -on all workstations. - - Example Configuration diff --git a/docs/docbook/projdoc/Speed.xml b/docs/docbook/projdoc/Speed.xml index 327aeff8c9..e2ede62ac7 100644 --- a/docs/docbook/projdoc/Speed.xml +++ b/docs/docbook/projdoc/Speed.xml @@ -192,8 +192,7 @@ case you may wish to change this option. Slow logins are almost always due to the password checking time. Using -the lowest practical password level will improve things. Note that -this problem only occurs on slow servers(e.g. 486 and lower). +the lowest practical password level will improve things. @@ -201,10 +200,14 @@ this problem only occurs on slow servers(e.g. 486 and lower). LDAP -LDAP can be vastly improved by using the ldap trust ids parameter. + +LDAP can be vastly improved by using the +ldap trust ids parameter. + + Client tuning @@ -216,5 +219,4 @@ performance. Check the sections on the various clients in - diff --git a/docs/docbook/projdoc/StandAloneServer.xml b/docs/docbook/projdoc/StandAloneServer.xml index fc003330ea..d8f5992191 100644 --- a/docs/docbook/projdoc/StandAloneServer.xml +++ b/docs/docbook/projdoc/StandAloneServer.xml @@ -5,7 +5,7 @@ Stand-Alone Servers -Stand-Alone servers are independant of an Domain Controllers on the network. +Stand-Alone servers are independant of Domain Controllers on the network. They are NOT domain members and function more like workgroup servers. In many cases a stand-alone server is configured with a minimum of security control with the intent that all data served will be readilly accessible to all users. @@ -42,11 +42,11 @@ a great solution. Background -The term stand alone server means that the server +The term stand-alone server means that the server will provide local authentication and access control for all resources that are available from it. In general this means that there will be a local user database. In more technical terms, it means that resources -on the machine will either be made available in either SHARE mode or in +on the machine will be made available in either SHARE mode or in USER mode. @@ -71,10 +71,10 @@ the samba server is NOT a member of a domain security context. Through the use of PAM (Pluggable Authentication Modules) and nsswitch (the name service switcher) the source of authentication may reside on another server. We would be inclined to call this the authentication server. -This means that the samba server may use the local Unix/Linux system -password database (/etc/passwd or /etc/shadow), may use a local smbpasswd -file, or may use an LDAP back end, or even via PAM and Winbind another CIFS/SMB -server for authentication. +This means that the samba server may use the local Unix/Linux system password database +(/etc/passwd or /etc/shadow), may use a local smbpasswd file, or may use +an LDAP back end, or even via PAM and Winbind another CIFS/SMB server +for authentication. @@ -222,7 +222,8 @@ the anonymous (guest) user two things will be required: Common Errors -Put stuff here. +The greatest mistake so often made is to make a network configuration too complex. +It pays to use the simplest solution that will meet the needs of the moment. diff --git a/docs/docbook/projdoc/passdb.xml b/docs/docbook/projdoc/passdb.xml index c64f568571..5dc0f9e6cb 100644 --- a/docs/docbook/projdoc/passdb.xml +++ b/docs/docbook/projdoc/passdb.xml @@ -687,7 +687,7 @@ In smb.conf [globals] The LDAP ldapsam code has been developed and tested using the OpenLDAP 2.0 and 2.1 server and client libraries. The same code should work with Netscape's Directory Server and client SDK. However, there are bound to be compile errors and bugs. These should not be hard to fix. - Please submit fixes via . + Please submit fixes via . @@ -834,7 +834,7 @@ index default sub -root# /etc/init.d/slapd restart +root# /etc/init.d/slapd restart diff --git a/docs/docbook/projdoc/samba-doc.xml b/docs/docbook/projdoc/samba-doc.xml index c682230330..a4394d263f 100644 --- a/docs/docbook/projdoc/samba-doc.xml +++ b/docs/docbook/projdoc/samba-doc.xml @@ -1,5 +1,6 @@ - %globalentities; ]> @@ -90,8 +91,7 @@ section carefully. Valuable Nuts and Bolts Information -Samba has several features that you might want or might not want to use. -The chapters in this part each cover specific Samba features. +Samba has several features that you might want or might not want to use. The chapters in this part each cover specific Samba features. &NetworkBrowsing; -- cgit From 9a5a90b33454c9d4e451d260f58fe2a2c9c94501 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sun, 25 May 2003 10:01:20 +0000 Subject: Some minor fixes in language and content (This used to be commit 83e3d4b4e70490c59c69ab83b8f787fa362e6caa) --- docs/docbook/projdoc/passdb.xml | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/docbook/projdoc/passdb.xml b/docs/docbook/projdoc/passdb.xml index 5dc0f9e6cb..78aee30448 100644 --- a/docs/docbook/projdoc/passdb.xml +++ b/docs/docbook/projdoc/passdb.xml @@ -718,7 +718,7 @@ objectclass ( 1.3.6.1.4.1.7165.2.2.3 NAME 'sambaAccount' SUP top AUXILIARY The OID's are owned by the Samba Team and as such is legal to be openly published. If you translate the schema to be used with Netscape DS, please submit the modified schema file as a patch to - jerry@samba.org + jerry@samba.org. @@ -865,7 +865,7 @@ index default sub - These are described in the smb.conf(5) man + These are described in the &smb.conf; man page and so will not be repeated here. However, a sample smb.conf file for use with an LDAP directory could appear as @@ -1051,8 +1051,8 @@ index default sub smbHome: The homeDirectory property specifies the path of the home directory for the user. The string can be null. If homeDrive is set and specifies a drive letter, homeDirectory should be a UNC path. The path must be a network - UNC path of the form \\server\share\directory. This value can be a null string. - Refer to the "logon home" parameter in the smb.conf(5) man page for more information. + UNC path of the form \\server\share\directory. This value can be a null string. + Refer to the logon home parameter in the &smb.conf; man page for more information. userWorkstation: character string value currently unused. @@ -1069,7 +1069,7 @@ index default sub The majority of these parameters are only used when Samba is acting as a PDC of - a domain (refer to the Samba-PDC-HOWTO for details on + a domain (refer to the Samba as a primary domain controller chapter for details on how to configure Samba as a Primary Domain Controller). The following four attributes are only stored with the sambaAccount entry if the values are non-default values: @@ -1091,7 +1091,7 @@ index default sub this value is used. However, if this attribute does not exist, then the value of the logon home parameter is used in its place. Samba will only write the attribute value to the directory entry if the value is - something other than the default (e.g. \\MOBY\becky). + something other than the default (e.g. \\MOBY\becky). @@ -1160,7 +1160,7 @@ index default sub Password synchronisation - Since 3.0 Samba can update the non-samba (LDAP) password stored with an account. When + Since version 3.0 samba can update the non-samba (LDAP) password stored with an account. When using pam_ldap, this allows changing both unix and windows passwords at once. @@ -1196,7 +1196,7 @@ index default sub ldap trust ids - LDAP Performance can be approved by using the ldap trust ids parameter. + LDAP Performance can be improved by using the ldap trust ids parameter. See the smb.conf manpage for details. @@ -1241,7 +1241,7 @@ index default sub - Additional options can be given thru the smb.conf file in the [global] section. + Additional options can be given thru the &smb.conf; file in the [global] section. @@ -1258,7 +1258,7 @@ index default sub Since the password for the mysql user is stored in the - smb.conf file, you should make the the smb.conf file + &smb.conf; file, you should make the the &smb.conf; file readable only to the user that runs samba. This is considered a security bug and will be fixed soon. @@ -1384,10 +1384,6 @@ index default sub - In your smb.conf file [globals]: - passdb backend = tdbsam, smbpasswd, guest - - then execute (as root): pdbedit -i smbpasswd -e tdbsam @@ -1400,6 +1396,8 @@ index default sub Put stuff here +- People forget to put their users in their backend and then complain samba + won't authorize them -- cgit From 7006d6b29a0d5e5a4b257420a6a53ace33727bcf Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Mon, 26 May 2003 20:36:57 +0000 Subject: Add document on contributing code to samba (This used to be commit 15ab9f350cea6a2a9bfe49491816ae60e5fd9d7c) --- docs/docbook/devdoc/contributing.xml | 106 +++++++++++++++++++++++++++++++++++ docs/docbook/devdoc/dev-doc.xml | 2 + 2 files changed, 108 insertions(+) create mode 100644 docs/docbook/devdoc/contributing.xml (limited to 'docs') diff --git a/docs/docbook/devdoc/contributing.xml b/docs/docbook/devdoc/contributing.xml new file mode 100644 index 0000000000..d0fb1d41a3 --- /dev/null +++ b/docs/docbook/devdoc/contributing.xml @@ -0,0 +1,106 @@ + + + &author.jelmer; + + +Contributing code + +Here are a few tips and notes that might be useful if you are + interested in modifying samba source code and getting it into + samba's main branch. + + + + Retrieving the source + + + In order to contribute code to samba, make sure you have the + latest source. Retrieving the samba source code from CVS is + documented in the appendix of the Samba HOWTO Collection. + + + + + + Discuss large modifications with team members + + Please discuss large modifications you are going to make + with members of the samba team. Some parts of the samba code + have one or more 'owners' - samba developers who wrote most + of the code and maintain it. + + + This way you can avoid spending your time and effort on + something that is not going to make it into the main samba branch + because someone else was working on the same thing or because your + implementation is not the correct one. + + + + + Patch format + + Patches to the samba tree should be in unified diff format, + e.g. files generated by diff -u. + + + If you are modifying a copy of samba you retrieved from CVS, + you can easily generate a diff file of these changes by running + cvs diff -u. + + + + + Points of attention when modifying samba source code + + + Don't simply copy code from other places and modify it until it + works. Code needs to be clean and logical. Duplicate + code is to be avoided. + Test your patch. It might take a while before one of us looks + at your patch so it will take longer before your patch when your patch + needs to go thru the review cycle again. + Don't put seperate patches in one large diff file. This makes + it harder to read, understand and test the patch. You might + also risk not getting a good patch committed because you mixed it + with one that had issues. + Make sure your patch complies to the samba coding style as + suggested in the coding-suggestions chapter. + + + + + Sending in bugfixes + + Bugfixes to bugs in samba should be submitted to samba's + bugzilla system, + along with a description of the bug. + + + + + + Sending in feature patches + + Send feature patches along with a description of what the + patch is supposed to do to the + Samba-technical mailinglist and possibly to a samba team member who is (one of the) 'owners' + of the code you made modifications to. We are all busy people + so everybody tends to 'let one of the others handle it'. If nobody + responded to your patch for a week, try to send it again until you + get a response from one of us. + + + + + Feedback on your patch + + One of the team members will look at your patch and either + commit your patch or give comments why he won't apply it. In the + latter case you can fix your patch and re-send it until + your patch is approved. + + + + + diff --git a/docs/docbook/devdoc/dev-doc.xml b/docs/docbook/devdoc/dev-doc.xml index 26374f7f39..0ed4275972 100644 --- a/docs/docbook/devdoc/dev-doc.xml +++ b/docs/docbook/devdoc/dev-doc.xml @@ -16,6 +16,7 @@ + ]> @@ -76,5 +77,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt -- cgit