diff options
Diffstat (limited to 'docs/docbook/projdoc')
42 files changed, 7918 insertions, 3360 deletions
diff --git a/docs/docbook/projdoc/AccessControls.xml b/docs/docbook/projdoc/AccessControls.xml index 38c3475d34..44d0d41449 100644 --- a/docs/docbook/projdoc/AccessControls.xml +++ b/docs/docbook/projdoc/AccessControls.xml @@ -66,7 +66,7 @@ shrink. <para> Samba honours and implements Unix file system access controls. Users who access a Samba server will do so as a particular MS Windows user. - This information is passed to the Samba server as part of the logon orr + This information is passed to the Samba server as part of the logon or connection setup process. Samba uses this user identity to validate whether or not the user should be given access to file system resources (files and directories). This chapter provides an overview for those @@ -146,10 +146,11 @@ at how Samba helps to bridge the differences. to depths of control ability should review the &smb.conf; man page. </para> - <itemizedlist> - <title>File System Feature Comparison</title> - <listitem> - <para><emphasis>Name Space</emphasis></para> + <variablelist> + <title>File System Feature Comparison</title> + <varlistentry> + <term>Name Space</term> + <listitem> <para> MS Windows NT4 / 200x/ XP files names may be up to 254 characters long, Unix file names may be 1023 characters long. In MS Windows file extensions indicate particular file types, @@ -158,10 +159,12 @@ at how Samba helps to bridge the differences. <para> What MS Windows calls a Folder, Unix calls a directory, </para> - </listitem> + </listitem> + </varlistentry> - <listitem> - <para><emphasis>Case Sensitivity</emphasis></para> + <varlistentry> + <term>Case Sensitivity</term> + <listitem> <para> MS Windows file names are generally Upper Case if made up of 8.3 (ie: 8 character file name and 3 character extension. If longer than 8.3 file names are Case Preserving, and Case @@ -176,28 +179,32 @@ at how Samba helps to bridge the differences. </para> <para> Consider the following, all are unique Unix names but one single MS Windows file name: - <programlisting> + <computeroutput> MYFILE.TXT MyFile.txt myfile.txt - </programlisting> + </computeroutput> So clearly, In an MS Windows file name space these three files CAN NOT co-exist! But in Unix they can. So what should Samba do if all three are present? Answer, the one that is lexically first will be accessible to MS Windows users, the others are invisible and unaccessible - any other solution would be suicidal. </para> - </listitem> + </listitem> + </varlistentry> - <listitem> - <para><emphasis>Directory Separators</emphasis></para> + <varlistentry> + <term>Directory Separators</term> + <listitem> <para> MS Windows and DOS uses the back-slash '\' as a directory delimiter, Unix uses the forward-slash '/' as it's directory delimiter. This is transparently handled by Samba. </para> - </listitem> + </listitem> + </varlistentry> - <listitem> - <para><emphasis>Drive Identification</emphasis></para> + <varlistentry> + <term>Drive Identification</term> + <listitem> <para> MS Windows products support a notion of drive letters, like <command>C:</command> to represent disk partitions. Unix has NO concept if separate identifiers for file partitions since each @@ -205,20 +212,24 @@ at how Samba helps to bridge the differences. The Unix directory tree begins at '/', just like the root of a DOS drive is specified like <command>C:\</command>. </para> - </listitem> + </listitem> + </varlistentry> - <listitem> - <para><emphasis>File Naming Conventions</emphasis></para> + <varlistentry> + <term>File Naming Conventions</term> + <listitem> <para> MS Windows generally never experiences file names that begin with a '.', while in Unix these are commonly found in a user's home directory. Files that begin with a '.' are typically either start up files for various Unix applications, or they may be files that contain start-up configuration data. </para> - </listitem> - - <listitem> - <para><emphasis>Links and Short-Cuts</emphasis></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Links and Short-Cuts</term> + <listitem> <para> MS Windows make use of "links and Short-Cuts" that are actually special types of files that will redirect an attempt to execute the file to the real location of the file. Unix knows of file and directory @@ -230,8 +241,9 @@ at how Samba helps to bridge the differences. referred to as 'soft links'. A hard link is something that MS Windows is NOT familiar with. It allows one physical file to be known simulataneously by more than one file name. </para> - </listitem> - </itemizedlist> + </listitem> + </varlistentry> + </variablelist> <para> There are many other subtle differences that may cause the MS Windows administrator some temporary discomfort @@ -246,13 +258,20 @@ at how Samba helps to bridge the differences. <para> There are three basic operations for managing directories, <command>create, delete, rename</command>. - <programlisting> - Action MS Windows Command Unix Command - ------ ------------------ ------------ - create md folder mkdir folder - delete rd folder rmdir folder - rename rename oldname newname mv oldname newname - </programlisting> + <table frame="all"> + <title>Managing directories with unix and windows</title> + <tgroup align="center" cols="3"> + <thead> + <row><entry>Action</entry><entry>MS Windows Command</entry><entry>Unix Command</entry></row> + </thead> + + <tbody> + <row><entry>create</entry><entry>md folder</entry><entry>mkdir folder</entry></row> + <row><entry>delete</entry><entry>rd folder</entry><entry>rmdir folder</entry></row> + <row><entry>rename</entry><entry>rename oldname newname</entry><entry>mv oldname newname</entry></row> + </tbody> + </tgroup> + </table> </para> </sect2> @@ -271,8 +290,8 @@ at how Samba helps to bridge the differences. Unix/Linux file and directory access permissions invloves setting three (3) primary sets of data and one (1) control set. A Unix file listing looks as follows:- - <programlisting> - jht@frodo:~/stuff> ls -la + <screen> + <prompt>jht@frodo:~/stuff> </prompt><userinput>ls -la</userinput> total 632 drwxr-xr-x 13 jht users 816 2003-05-12 22:56 . drwxr-xr-x 37 jht users 3800 2003-05-12 22:29 .. @@ -293,8 +312,8 @@ at how Samba helps to bridge the differences. -r-xr-xr-x 1 jht users 206339 2003-05-12 22:32 mydata05.lst -rw-rw-rw- 1 jht users 41105 2003-05-12 22:32 mydata06.lst -rwxrwxrwx 1 jht users 19312 2003-05-12 22:32 mydata07.lst - jht@frodo:~/stuff> - </programlisting> + <prompt>jht@frodo:~/stuff></prompt> + </screen> </para> <para> @@ -305,6 +324,7 @@ at how Samba helps to bridge the differences. The permissions field is made up of: <programlisting> + <comment> JRV: Put this into a diagram of some sort</comment> [ type ] [ users ] [ group ] [ others ] [File, Directory Permissions] [ d | l ] [ r w x ] [ r w x ] [ r w x ] | | | | | | | | | | | @@ -324,12 +344,16 @@ at how Samba helps to bridge the differences. <para> Any bit flag may be unset. An unset bit flag is the equivalent of 'Can NOT' and is represented as a '-' character. - <programlisting> - <title>Example File</title> + + <example> + <title>Example File</title> + <programlisting> -rwxr-x--- Means: The owner (user) can read, write, execute the group can read and execute everyone else can NOT do anything with it - </programlisting> + </programlisting> + </example> + </para> <para> @@ -356,7 +380,7 @@ at how Samba helps to bridge the differences. </para> <para> - When a directory is set <command>drw-r-----</command> this means that the owner can read and create (write) files in it, but because + When a directory is set <constant>drw-r-----</constant> this means that the owner can read and create (write) files in it, but because the (x) execute flags are not set files can not be listed (seen) in the directory by anyone. The group can read files in the directory but can NOT create new files. NOTE: If files in the directory are set to be readable and writable for the group, then group members will be able to write to (or delete) them. @@ -379,17 +403,17 @@ Before using any of the following options please refer to the man page for &smb. <para> User and group based controls can prove very useful. In some situations it is distinctly desirable to affect all - file system operations as if a single user is doing this, the use of the <emphasis>force user</emphasis> and - <emphasis>force group</emphasis> behaviour will achieve this. In other situations it may be necessary to affect a + file system operations as if a single user is doing this, the use of the <parameter>force user</parameter> and + <parameter>force group</parameter> behaviour will achieve this. In other situations it may be necessary to affect a paranoia level of control to ensure that only particular authorised persons will be able to access a share or - it's contents, here the use of the <emphasis>valid users</emphasis> or the <emphasis>invalid users</emphasis> may + it's contents, here the use of the <parameter>valid users</parameter> or the <parameter>invalid users</parameter> may be most useful. </para> <para> As always, it is highly advisable to use the least difficult to maintain and the least ambiguous method for controlling access. Remember, that when you leave the scene someone else will need to provide assistance and - if that person finds to great a mess, or if they do not understand what you have done then there is risk of + if that person finds too great a mess, or if they do not understand what you have done then there is risk of Samba being removed and an alternative solution being adopted. </para> @@ -656,7 +680,7 @@ Before using any of the following options please refer to the man page for &smb. By default samba sets no restrictions on the share itself. Restrictions on the share itself can be set on MS Windows NT4/200x/XP shares. This can be a very effective way to limit who can connect to a share. In the absence of specific restrictions the default setting is to allow - the global user <emphasis>Everyone</emphasis> Full Control (ie: Full control, Change and Read). + the global user <constant>Everyone</constant> Full Control (ie: Full control, Change and Read). </para> <para> @@ -692,13 +716,13 @@ Before using any of the following options please refer to the man page for &smb. <procedure> <title>Instructions</title> <step><para> - Launch the NT4 Server Manager, click on the Samba server you want to administer, then from the menu - select Computer, then click on the Shared Directories entry. + Launch the <application>NT4 Server Manager</application>, click on the Samba server you want to administer, then from the menu + select <guimenu>Computer</guimenu>, then click on the <guimenuitem>Shared Directories</guimenuitem> entry. </para></step> <step><para> - Now click on the share that you wish to manage, then click on the Properties tab, next click on - the Permissions tab. Now you can Add or change access control settings as you wish. + Now click on the share that you wish to manage, then click on the <guilabel>Properties</guilabel> tab, next click on + the <guilabel>Permissions</guilabel> tab. Now you can add or change access control settings as you wish. </para></step> </procedure> @@ -708,14 +732,14 @@ Before using any of the following options please refer to the man page for &smb. <title>Windows 200x/XP</title> <para> - On MS Windows NT4/200x/XP system access control lists on the share itself are set using native + On <application>MS Windows NT4/200x/XP</application> system access control lists on the share itself are set using native tools, usually from filemanager. For example, in Windows 200x: right click on the shared folder, - then select 'Sharing', then click on 'Permissions'. The default Windows NT4/200x permission allows - <emphasis>Everyone</emphasis> Full Control on the Share. + then select <guimenuitem>Sharing</guimenuitem>, then click on <guilabel>Permissions</guilabel>. The default + Windows NT4/200x permission allows <emphasis>Everyone</emphasis> Full Control on the Share. </para> <para> - MS Windows 200x and later all comes with a tool called the 'Computer Management' snap-in for the + MS Windows 200x and later all comes with a tool called the <application>Computer Management</application> snap-in for the Microsoft Management Console (MMC). This tool is located by clicking on <filename>Control Panel -> Administrative Tools -> Computer Management</filename>. </para> @@ -723,21 +747,22 @@ Before using any of the following options please refer to the man page for &smb. <procedure> <title>Instructions</title> <step><para> - After launching the MMC with the Computer Management snap-in, click on the menu item 'Action', - select 'Connect to another computer'. If you are not logged onto a domain you will be prompted + After launching the MMC with the Computer Management snap-in, click on the menu item <guimenuitem>Action</guimenuitem>, + select <guilabel>Connect to another computer</guilabel>. If you are not logged onto a domain you will be prompted to enter a domain login user identifier and a password. This will authenticate you to the domain. If you where already logged in with administrative privilidge this step is not offered. </para></step> <step><para> - If the Samba server is not shown in the Select Computer box, then type in the name of the target - Samba server in the field 'Name:'. Now click on the [+] next to 'System Tools', then on the [+] - next to 'Shared Folders' in the left panel. + If the Samba server is not shown in the <guilabel>Select Computer</guilabel> box, then type in the name of the target + Samba server in the field <guilabel>Name:</guilabel>. Now click on the <guibutton>[+]</guibutton> next to + <guilabel>System Tools</guilabel>, then on the <guibutton>[+]</guibutton> next to <guilabel>Shared Folders</guilabel> in the + left panel. </para></step> <step><para> Now in the right panel, double-click on the share you wish to set access control permissions on. - Then click on the tab 'Share Permissions'. It is now possible to add access control entities + Then click on the tab <guilabel>Share Permissions</guilabel>. It is now possible to add access control entities to the shared folder. Do NOT forget to set what type of access (full control, change, read) you wish to assign for each entry. </para></step> @@ -745,10 +770,10 @@ Before using any of the following options please refer to the man page for &smb. <warning> <para> - Be careful. If you take away all permissions from the Everyone user without removing this user + Be careful. If you take away all permissions from the <constant>Everyone</constant> user without removing this user then effectively no user will be able to access the share. This is a result of what is known as - ACL precidence. ie: Everyone with NO ACCESS means that MaryK who is part of the group Everyone - will have no access even if this user is given explicit full control access. + ACL precedence. ie: Everyone with <strong>no access</strong> means that MaryK who is part of the group + <constant>Everyone</constant> will have no access even if this user is given explicit full control access. </para> </warning> @@ -789,19 +814,19 @@ Before using any of the following options please refer to the man page for &smb. <para>From an NT4/2000/XP client, single-click with the right mouse button on any file or directory in a Samba mounted drive letter or UNC path. When the menu pops-up, click - on the <emphasis>Properties</emphasis> entry at the bottom of + on the <guilabel>Properties</guilabel> entry at the bottom of the menu. This brings up the file properties dialog - box. Click on the tab <emphasis>Security</emphasis> and you - will see three buttons, <emphasis>Permissions</emphasis>, - <emphasis>Auditing</emphasis>, and <emphasis>Ownership</emphasis>. - The <emphasis>Auditing</emphasis> button will cause either + box. Click on the tab <guilabel>Security</guilabel> and you + will see three buttons, <guibutton>Permissions</guibutton>, + <guibutton>Auditing</guibutton>, and <guibutton>Ownership</guibutton>. + The <guibutton>Auditing</guibutton> button will cause either an error message <errorname>A requested privilege is not held by the client</errorname> to appear if the user is not the NT Administrator, or a dialog which is intended to allow an Administrator to add auditing requirements to a file if the user is logged on as the NT Administrator. This dialog is non-functional with a Samba share at this time, as the only - useful button, the <command>Add</command> button will not currently + useful button, the <guibutton>Add</guibutton> button will not currently allow a list of users to be seen.</para> </sect2> @@ -809,7 +834,7 @@ Before using any of the following options please refer to the man page for &smb. <sect2> <title>Viewing file ownership</title> - <para>Clicking on the <command>"Ownership"</command> button + <para>Clicking on the <guibutton>Ownership</guibutton> button brings up a dialog box telling you who owns the given file. The owner name will be of the form :</para> @@ -819,14 +844,14 @@ Before using any of the following options please refer to the man page for &smb. the Samba server, <replaceable>user</replaceable> is the user name of the UNIX user who owns the file, and <replaceable>(Long name)</replaceable> is the descriptive string identifying the user (normally found in the - GECOS field of the UNIX password database). Click on the <command>Close - </command> button to remove this dialog.</para> + GECOS field of the UNIX password database). Click on the + <guibutton>Close </guibutton> button to remove this dialog.</para> <para>If the parameter <parameter>nt acl support</parameter> is set to <constant>false</constant> then the file owner will - be shown as the NT user <command>"Everyone"</command>.</para> + be shown as the NT user <constant>"Everyone"</constant>.</para> - <para>The <command>Take Ownership</command> button will not allow + <para>The <guibutton>Take Ownership</guibutton> button will not allow you to change the ownership of this file to yourself (clicking on it will display a dialog box complaining that the user you are currently logged onto the NT client cannot be found). The reason @@ -840,8 +865,8 @@ Before using any of the following options please refer to the man page for &smb. and allow a user with Administrator privilege connected to a Samba server as root to change the ownership of files on both a local NTFS filesystem or remote mounted NTFS - or Samba drive. This is available as part of the <emphasis>Seclib - </emphasis> NT security library written by Jeremy Allison of + or Samba drive. This is available as part of the <application>Seclib + </application> NT security library written by Jeremy Allison of the Samba Team, available from the main Samba ftp site.</para> </sect2> @@ -849,12 +874,14 @@ Before using any of the following options please refer to the man page for &smb. <sect2> <title>Viewing File or Directory Permissions</title> - <para>The third button is the <command>"Permissions"</command> + <para>The third button is the <guibutton>Permissions</guibutton> button. Clicking on this brings up a dialog box that shows both the permissions and the UNIX owner of the file or directory. The owner is displayed in the form :</para> - <para><command>"SERVER\user (Long name)"</command></para> + <para><command>"<replaceable>SERVER</replaceable>\ + <replaceable>user</replaceable> + <replaceable>(Long name)</replaceable>"</command></para> <para>Where <replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server, <replaceable>user</replaceable> is the user name of @@ -864,7 +891,7 @@ Before using any of the following options please refer to the man page for &smb. <para>If the parameter <parameter>nt acl support</parameter> is set to <constant>false</constant> then the file owner will - be shown as the NT user <command>"Everyone"</command> and the + be shown as the NT user <constant>"Everyone"</constant> and the permissions will be shown as NT "Full Control".</para> @@ -880,18 +907,18 @@ Before using any of the following options please refer to the man page for &smb. triples are mapped by Samba into a three element NT ACL with the 'r', 'w', and 'x' bits mapped into the corresponding NT permissions. The UNIX world permissions are mapped into - the global NT group <command>Everyone</command>, followed + the global NT group <constant>Everyone</constant>, followed by the list of permissions allowed for UNIX world. The UNIX owner and group permissions are displayed as an NT - <command>user</command> icon and an NT <command>local - group</command> icon respectively followed by the list + <guiicon>user</guiicon> icon and an NT <guiicon>local + group</guiicon> icon respectively followed by the list of permissions allowed for the UNIX user and group.</para> <para>As many UNIX permission sets don't map into common - NT names such as <command>"read"</command>, <command> - "change"</command> or <command>"full control"</command> then - usually the permissions will be prefixed by the words <command> - "Special Access"</command> in the NT display list.</para> + NT names such as <constant>read</constant>, <constant> + "change"</constant> or <constant>full control</constant> then + usually the permissions will be prefixed by the words <constant> + "Special Access"</constant> in the NT display list.</para> <para>But what happens if the file has no permissions allowed for a particular UNIX user group or world component ? In order @@ -910,14 +937,14 @@ Before using any of the following options please refer to the man page for &smb. <para>Directories on an NT NTFS file system have two different sets of permissions. The first set of permissions is the ACL set on the directory itself, this is usually displayed - in the first set of parentheses in the normal <command>"RW"</command> + in the first set of parentheses in the normal <constant>"RW"</constant> NT style. This first set of permissions is created by Samba in exactly the same way as normal file permissions are, described above, and is displayed in the same way.</para> <para>The second set of directory permissions has no real meaning - in the UNIX permissions world and represents the <command> - "inherited"</command> permissions that any file created within + in the UNIX permissions world and represents the <constant> + inherited</constant> permissions that any file created within this directory would inherit.</para> <para>Samba synthesises these inherited permissions for NT by @@ -931,27 +958,27 @@ Before using any of the following options please refer to the man page for &smb. <para>Modifying file and directory permissions is as simple as changing the displayed permissions in the dialog box, and - clicking the <command>OK</command> button. However, there are + clicking the <guibutton>OK</guibutton> button. However, there are limitations that a user needs to be aware of, and also interactions with the standard Samba permission masks and mapping of DOS attributes that need to also be taken into account.</para> <para>If the parameter <parameter>nt acl support</parameter> is set to <constant>false</constant> then any attempt to set - security permissions will fail with an <command>"Access Denied" - </command> message.</para> + security permissions will fail with an <errorname>"Access Denied" + </errorname> message.</para> - <para>The first thing to note is that the <command>"Add"</command> + <para>The first thing to note is that the <guibutton>"Add"</guibutton> button will not return a list of users in Samba (it will give - an error message of <command>"The remote procedure call failed - and did not execute"</command>). This means that you can only + an error message of <errorname>The remote procedure call failed + and did not execute</errorname>). This means that you can only manipulate the current user/group/world permissions listed in the dialog box. This actually works quite well as these are the only permissions that UNIX actually has.</para> <para>If a permission triple (either user, group, or world) is removed from the list of permissions in the NT dialog box, - then when the <command>"OK"</command> button is pressed it will + then when the <guibutton>OK</guibutton> button is pressed it will be applied as "no permissions" on the UNIX side. If you then view the permissions again the "no permissions" entry will appear as the NT <command>"O"</command> flag, as described above. This @@ -966,15 +993,15 @@ Before using any of the following options please refer to the man page for &smb. <para>When setting permissions on a directory the second set of permissions (in the second set of parentheses) is by default applied to all files within that directory. If this - is not what you want you must uncheck the <command>"Replace - permissions on existing files"</command> checkbox in the NT - dialog before clicking <command>"OK"</command>.</para> + is not what you want you must uncheck the <guilabel>Replace + permissions on existing files</guilabel> checkbox in the NT + dialog before clicking <guibutton>OK</guibutton>.</para> <para>If you wish to remove all permissions from a user/group/world component then you may either highlight the - component and click the <command>"Remove"</command> button, - or set the component to only have the special <command>"Take - Ownership"</command> permission (displayed as <command>"O" + component and click the <guibutton>Remove</guibutton> button, + or set the component to only have the special <constant>Take + Ownership</constant> permission (displayed as <command>"O" </command>) highlighted.</para> </sect2> @@ -984,14 +1011,18 @@ Before using any of the following options please refer to the man page for &smb. <para>There are four parameters to control interaction with the standard Samba create mask parameters. - These are :</para> + These are : - <para><parameter>security mask</parameter></para> - <para><parameter>force security mode</parameter></para> - <para><parameter>directory security mask</parameter></para> - <para><parameter>force directory security mode</parameter></para> + <simplelist> + <member><parameter>security mask</parameter></member> + <member><parameter>force security mode</parameter></member> + <member><parameter>directory security mask</parameter></member> + <member><parameter>force directory security mode</parameter></member> + </simplelist> - <para>Once a user clicks <command>"OK"</command> to apply the + </para> + + <para>Once a user clicks <guibutton>OK</guibutton> to apply the permissions Samba maps the given permissions into a user/group/world r/w/x triple set, and then will check the changed permissions for a file against the bits set in the <ulink url="smb.conf.5.html#SECURITYMASK"> @@ -1050,12 +1081,15 @@ Before using any of the following options please refer to the man page for &smb. <para>If you want to set up a share that allows users full control in modifying the permission bits on their files and directories and doesn't force any particular bits to be set 'on', then set the following - parameters in the &smb.conf; file in that share specific section :</para> + parameters in the &smb.conf; file in that share specific section : + </para> - <para><parameter>security mask = 0777</parameter></para> - <para><parameter>force security mode = 0</parameter></para> - <para><parameter>directory security mask = 0777</parameter></para> - <para><parameter>force directory security mode = 0</parameter></para> + <simplelist> + <member><parameter>security mask = 0777</parameter></member> + <member><parameter>force security mode = 0</parameter></member> + <member><parameter>directory security mask = 0777</parameter></member> + <member><parameter>force directory security mode = 0</parameter></member> + </simplelist> </sect2> <sect2> @@ -1075,13 +1109,13 @@ Before using any of the following options please refer to the man page for &smb. <para>What this can mean is that if the owner changes the permissions to allow themselves read access using the security dialog, clicks - <command>"OK"</command> to get back to the standard attributes tab - dialog, and then clicks <command>"OK"</command> on that dialog, then + <guibutton>OK</guibutton> to get back to the standard attributes tab + dialog, and then clicks <guibutton>OK</guibutton> on that dialog, then NT will set the file permissions back to read-only (as that is what the attributes still say in the dialog). This means that after setting - permissions and clicking <command>"OK"</command> to get back to the - attributes dialog you should always hit <command>"Cancel"</command> - rather than <command>"OK"</command> to ensure that your changes + permissions and clicking <guibutton>OK</guibutton> to get back to the + attributes dialog you should always hit <guibutton>Cancel</guibutton> + rather than <guibutton>OK</guibutton> to ensure that your changes are not overridden.</para> </sect2> </sect1> @@ -1099,10 +1133,12 @@ are examples taken from the mailing list in recent times. <title>Users can not write to a public share</title> <para> + <quote> 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 - <command>chgrp -R users *</command> and <command>chown -R nobody *</command> to allow others users to change the file. + <userinput>chgrp -R users *</userinput> and <userinput>chown -R nobody *</userinput> to allow others users to change the file. + </quote> </para> <para> @@ -1112,77 +1148,99 @@ are examples taken from the mailing list in recent times. <procedure> <title>Example Solution:</title> <step> - <para> - Go to the top of the directory that is shared - </para> + <para> + Go to the top of the directory that is shared + </para> </step> <step> - <para> - Set the ownership to what ever public owner and group you want - <programlisting> - 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 {}\; - </programlisting> - </para> + <para> + Set the ownership to what ever public owner and group you want + <programlisting> + 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 {}\; + </programlisting> + </para> - <para> - 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. - </para> + <note><para> + 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. + </para></note> + </step> + <step> + <para> - <para> - <programlisting> - Directory is: /foodbar - chown jack.engr /foodbar + Directory is: <replaceable>/foodbar</replaceable> + <screen> + <prompt>$ </prompt><userinput>chown jack.engr /foodbar</userinput> + </screen> + </para> - Note: This is the same as doing: - chown jack /foodbar - chgrp engr /foodbar + <note><para> + <para>This is the same as doing:</para> + <screen> + <prompt>$ </prompt><userinput>chown jack /foodbar</userinput> + <prompt>$ </prompt><userinput>chgrp engr /foodbar</userinput> + </screen> + </para></note> + </step> + <step> + <para>Now do: - Now do: - chmod 6775 /foodbar - ls -al /foodbar/.. + <screen> + <prompt>$ </prompt><userinput>chmod 6775 /foodbar</userinput> + <prompt>$ </prompt><userinput>ls -al /foodbar/..</userinput> + </screen> - You should see: - drwsrwsr-x 2 jack engr 48 2003-02-04 09:55 foodbar + </para> + + <para>You should see: + <screen> + drwsrwsr-x 2 jack engr 48 2003-02-04 09:55 foodbar + </screen> + </para> + </step> + <step> - Now do: - su - jill - cd /foodbar - touch Afile - ls -al - </programlisting> + <para>Now do: + <screen> + <prompt>$ </prompt><userinput>su - jill</userinput> + <prompt>$ </prompt><userinput>cd /foodbar</userinput> + <prompt>$ </prompt><userinput>touch Afile</userinput> + <prompt>$ </prompt><userinput>ls -al</userinput> + </screen> </para> <para> - You should see that the file 'Afile' created by Jill will have ownership + You should see that the file <filename>Afile</filename> created by Jill will have ownership and permissions of Jack, as follows: - <programlisting> + <screen> -rw-r--r-- 1 jack engr 0 2003-02-04 09:57 Afile - </programlisting> + </screen> </para> </step> <step> <para> - Now in your smb.conf for the share add: + Now in your &smb.conf; for the share add: <programlisting> force create mode = 0775 force direcrtory mode = 6775 </programlisting> </para> - <para> - Note: The above are only needed IF your users are NOT members of the group + <note><para> + The above are only needed <strong>if</strong> your users are <strong>not</strong> members of the group you have used. ie: Within the OS do not have write permission on the directory. </para> - + </note> + <para> - An alternative is to set in the smb.conf entry for the share: + An alternative is to set in the &smb.conf; entry for the share: <programlisting> force user = jack force group = engr @@ -1193,6 +1251,16 @@ are examples taken from the mailing list in recent times. </sect2> + <sect2> + <title>I have set <parameter>force user</parameter> and samba still makes <emphasis>root</emphasis> the owner of all the files + I touch!</title> + <para> + When you have a user in 'admin users', samba will always do file operations for + this user as <emphasis>root</emphasis>, even if <parameter>force user</parameter> has been set. + </para> + </sect2> + + </sect1> </chapter> diff --git a/docs/docbook/projdoc/AdvancedNetworkAdmin.xml b/docs/docbook/projdoc/AdvancedNetworkAdmin.xml index e6e7347290..15b8836962 100644 --- a/docs/docbook/projdoc/AdvancedNetworkAdmin.xml +++ b/docs/docbook/projdoc/AdvancedNetworkAdmin.xml @@ -7,12 +7,31 @@ <title>Advanced Network Manangement</title> <para> -This section attempts to document peripheral issues that are of great importance to network +This section documents peripheral issues that are of great importance to network administrators who want to improve network resource access control, to automate the user environment, and to make their lives a little easier. </para> <sect1> +<title>Features and Benefits</title> + +<para> +Often the difference between a working network environment and a well appreciated one can +best be measured by the <emphasis>little things</emphasis> that makes everything work more +harmoniously. A key part of every network environment solution is the ability to remotely +manage MS Windows workstations, to remotely access the Samba server, to provide customised +logon scripts, as well as other house keeping activities that help to sustain more reliable +network operations. +</para> + +<para> +This chapter presents information on each of these area. They are placed here, and not in +other chapters, for ease of reference. +</para> + +</sect1> + +<sect1> <title>Remote Server Administration</title> <para> @@ -20,20 +39,20 @@ environment, and to make their lives a little easier. </para> <para> -Since I don't need to buy an NT4 Server, how do I get the 'User Manager for Domains', + Since I don't need to buy an <application>NT4 Server</application>, how do I get the 'User Manager for Domains', the 'Server Manager'? </para> <para> -Microsoft distributes a version of these tools called nexus for installation on Windows 9x / Me -systems. The tools set includes: +Microsoft distributes a version of these tools called nexus for installation +on <application>Windows 9x / Me</application> systems. The tools set includes: </para> -<itemizedlist> - <listitem><para>Server Manager</para></listitem> - <listitem><para>User Manager for Domains</para></listitem> - <listitem><para>Event Viewer</para></listitem> -</itemizedlist> +<simplelist> + <member>Server Manager</member> + <member>User Manager for Domains</member> + <member>Event Viewer</member> +</simplelist> <para> Click here to download the archived file <ulink @@ -41,12 +60,158 @@ url="ftp://ftp.microsoft.com/Softlib/MSLFILES/NEXUS.EXE">ftp://ftp.microsoft.com </para> <para> -The Windows NT 4.0 version of the 'User Manager for +The <application>Windows NT 4.0</application> version of the 'User Manager for Domains' and 'Server Manager' are available from Microsoft via ftp from <ulink url="ftp://ftp.microsoft.com/Softlib/MSLFILES/SRVTOOLS.EXE">ftp://ftp.microsoft.com/Softlib/MSLFILES/SRVTOOLS.EXE</ulink> </para> </sect1> + +<sect1> +<title>Remote Desktop Management</title> + +<para> +There are a number of possible remote desktop management solutions that range from free +through costly. Do not let that put you off. Sometimes the most costly solutions is the +most cost effective. In any case, you will need to draw your own conclusions as to which +is the best tool in your network environment. +</para> + + <sect2> + <title>Remote Management from NoMachines.Com</title> + + <para> + The following information was posted to the Samba mailing list at Apr 3 23:33:50 GMT 2003. + It is presented in slightly edited form (with author details omitted for privacy reasons). + The entire answer is reproduced below with some comments removed. + </para> + +<para> +<screen> +> I have a wounderfull linux/samba server running as pdc for a network. +> Now I would like to add remote desktop capabilites so that +> users outside could login to the system and get their desktop up from +> home or another country.. +> +> Is there a way to acomplish this? Do I need a windows terminal server? +> Do I need to configure it so that it is a member of the domain or a +> BDC,PDC? Are there any hacks for MS Windows XP to enable remote login +> even if the computer is in a domain? +> +> Any ideas/experience would be appreciated :) +</screen> +</para> + + <para> + Answer provided: Check out the new offer from NoMachine, "NX" software: + <ulink url="http://www.nomachine.com/">http://www.nomachine.com/</ulink>. + </para> + + <para> + It implements a very easy-to-use interface to the remote X protocol as + well as incorporating VNC/RFB and rdesktop/RDP into it, but at a speed + performance much better than anything you may have ever seen... + </para> + + <para> + Remote X is not new at all -- but what they did achieve successfully is + a new way of compression and caching technologies which makes the thing + fast enough to run even over slow modem/ISDN connections. + </para> + + <para> + I could testdrive their (public) RedHat machine in Italy, over a loaded + internet connection, with enabled thumbnail previews in KDE konqueror + which popped up immediately on "mouse-over". From inside that (remote X) + session I started a rdesktop session on another, a Windows XP machine. + To test the performance, I played Pinball. I am proud to announce here + that my score was 631750 points at first try... + </para> + + <para> + NX performs better on my local LAN than any of the other "pure" + connection methods I am using from time to time: TightVNC, rdesktop or + remote X. It is even faster than a direct crosslink connection between + two nodes. + </para> + + <para> + I even got sound playing from the remote X app to my local boxes, and + had a working "copy'n'paste" from an NX window (running a KDE session + in Italy) to my Mozilla mailing agent... These guys are certainly doing + something right! + </para> + + <para> + I recommend to testdrive NX to anybody with a only a remote interest + in remote computing + <ulink url="http://www.nomachine.com/testdrive.php">http://www.nomachine.com/testdrive.php</ulink>. + </para> + + <para> + Just download the free of charge client software (available for RedHat, + SuSE, Debian and Windows) and be up and running within 5 minutes (they + need to send you your account data, though, because you are assigned + a real Unix account on their testdrive.nomachine.com box... + </para> + + <para> + They plan to get to the point were you can have NX application servers + running as a cluster of nodes, and users simply start an NX session locally, + and can select applications to run transparently (apps may even run on + another NX node, but pretend to be on the same as used for initial login, + because it displays in the same window.... well, you also can run it + fullscreen, and after a short time you forget that it is a remote session + at all). + </para> + + <para> + Now the best thing at the end: all the core compression and caching + technologies are released under the GPL and available as source code + to anybody who wants to build on it! These technolgies are working, + albeit started from the command line only (and very inconvenient to + use in order to get a fully running remote X session up and running....) + </para> + + <para> + To answer your questions: + </para> + + <itemizedlist> + <listitem><para> + You don't need to install a terminal server; XP has RDP support built in. + </para></listitem> + + <listitem><para> + NX is much cheaper than Citrix -- and comparable in performance, probably faster + </para></listitem> + + <listitem><para> + You don't need to hack XP -- it just works + </para></listitem> + + <listitem><para> + You log into the XP box from remote transparently (and I think there is no + need to change anything to get a connection, even if authentication is against a domain) + </para></listitem> + + <listitem><para> + The NX core technologies are all Open Source and released under the GPL -- + you can today use a (very inconvenient) commandline to use it at no cost, + but you can buy a comfortable (proprietary) NX GUI frontend for money + </para></listitem> + + <listitem><para> + NoMachine are encouraging and offering help to OSS/Free Software implementations + for such a frontend too, even if it means competition to them (they have written + to this effect even to the LTSP, KDE and GNOME developer mailing lists) + </para></listitem> + </itemizedlist> + + </sect2> + +</sect1> + <sect1> <title>Network Logon Script Magic</title> @@ -69,7 +234,9 @@ There are several opportunities for creating a custom network startup configurat </simplelist> <para> -The Samba source code tree includes two logon script generation/execution tools. See <filename>examples</filename> directory <filename>genlogon</filename> and <filename>ntlogon</filename> subdirectories. +The Samba source code tree includes two logon script generation/execution tools. +See <filename>examples</filename> directory <filename>genlogon</filename> and +<filename>ntlogon</filename> subdirectories. </para> <para> @@ -77,7 +244,7 @@ The following listings are from the genlogon directory. </para> <para> -This is the genlogon.pl file: +This is the <filename>genlogon.pl</filename> file: <programlisting> #!/usr/bin/perl @@ -159,9 +326,9 @@ Those wishing to use more elaborate or capable logon processing system should ch </para> <simplelist> - <member>http://www.craigelachie.org/rhacer/ntlogon</member> - <member>http://www.kixtart.org</member> - <member>http://support.microsoft.com/default.asp?scid=kb;en-us;189105</member> + <member><ulink url="http://www.craigelachie.org/rhacer/ntlogon">http://www.craigelachie.org/rhacer/ntlogon</ulink></member> + <member><ulink url="http://www.kixtart.org">http://www.kixtart.org</ulink></member> + <member><ulink url="http://support.microsoft.com/default.asp?scid=kb;en-us;189105">http://support.microsoft.com/default.asp?scid=kb;en-us;189105</ulink></member> </simplelist> <sect2> @@ -174,10 +341,21 @@ Printers may be added automatically during logon script processing through the u rundll32 printui.dll,PrintUIEntry /? </programlisting> -See the documentation in the Microsoft knowledgebase article no: 189105 referred to above. +See the documentation in the <ulink url="http://support.microsoft.com/default.asp?scid=kb;en-us;189105">Microsoft knowledgebase article no: 189105</ulink>. </para> </sect2> </sect1> -</chapter> +<sect1> +<title>Common Errors</title> + +<para> +The information provided in this chapter has been reproduced from postings on the samba@samba.org +mailing list. No implied endorsement or recommendation is offered. Administrators should conduct +their own evaluation of alternatives and are encouraged to draw their own conclusions. +</para> + +</sect1> + +</chapter> diff --git a/docs/docbook/projdoc/Backup.xml b/docs/docbook/projdoc/Backup.xml new file mode 100644 index 0000000000..b3c37aba53 --- /dev/null +++ b/docs/docbook/projdoc/Backup.xml @@ -0,0 +1,36 @@ +<chapter id="Backup"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>Samba Backup Techniques</title> + +<sect1> +<title>Note</title> + +<para> +This chapter did not make it into this release. +It is planned for the published release of this document. +If you have something to contribute for this section please email it to +<link url="mail://jht@samba.org">jht@samba.org</link>/ +</para> + +</sect1> + +<sect1> +<title>Features and Benefits</title> + +<para> +We need feedback from people who are backing up samba servers. +We would like to know what software tools you are using to backup +your samba server/s. +</para> + +<para> +In particular, if you have any success and / or failure stories you could +share with other users this would be appreciated. +</para> + +</sect1> + +</chapter> diff --git a/docs/docbook/projdoc/Bugs.xml b/docs/docbook/projdoc/Bugs.xml index d782920457..b2ff6d3d96 100644 --- a/docs/docbook/projdoc/Bugs.xml +++ b/docs/docbook/projdoc/Bugs.xml @@ -15,7 +15,8 @@ <sect1> <title>Introduction</title> -<para>Please report bugs using <ulink url="https://bugzilla.samba.org/">bugzilla</ulink>.</para> +<para>Please report bugs using + <ulink url="https://bugzilla.samba.org/">bugzilla</ulink>.</para> <para> Please take the time to read this file before you submit a bug @@ -83,7 +84,7 @@ detail, but may use too much disk space. </para> <para> -To set the debug level use <command>log level =</command> in your +To set the debug level use the <parameter>log level</parameter> in your &smb.conf;. You may also find it useful to set the log level higher for just one machine and keep separate logs for each machine. To do this use: @@ -100,24 +101,25 @@ then create a file <filename>/usr/local/samba/lib/smb.conf.<replaceable>machine</replaceable></filename> where <replaceable>machine</replaceable> is the name of the client you wish to debug. In that file put any &smb.conf; commands you want, for example -<command>log level=</command> may be useful. This also allows you to +<parameter>log level</parameter> may be useful. This also allows you to experiment with different security systems, protocol levels etc on just one machine. </para> <para> -The &smb.conf; entry <command>log level =</command> -is synonymous with the entry <command>debuglevel =</command> that has been -used in older versions of Samba and is being retained for backwards +The &smb.conf; entry <parameter>log level</parameter> +is synonymous with the parameter <parameter>debuglevel</parameter> that has +been used in older versions of Samba and is being retained for backwards compatibility of &smb.conf; files. </para> <para> -As the <command>log level =</command> value is increased you will record +As the <parameter>log level</parameter> value is increased you will record a significantly increasing level of debugging information. For most -debugging operations you may not need a setting higher than 3. Nearly -all bugs can be tracked at a setting of 10, but be prepared for a VERY -large volume of log data. +debugging operations you may not need a setting higher than +<constant>3</constant>. Nearly +all bugs can be tracked at a setting of <constant>10</constant>, but be +prepared for a VERY large volume of log data. </para> </sect1> @@ -126,8 +128,8 @@ large volume of log data. <title>Internal errors</title> <para> -If you get a "INTERNAL ERROR" message in your log files it means that -Samba got an unexpected signal while running. It is probably a +If you get a <errorname>INTERNAL ERROR</errorname> message in your log files +it means that Samba got an unexpected signal while running. It is probably a segmentation fault and almost certainly means a bug in Samba (unless you have faulty hardware or system software). </para> @@ -151,17 +153,20 @@ files. This file is the most useful tool for tracking down the bug. To use it you do this: </para> -<para><command>gdb smbd core</command></para> +<screen> + <prompt>$ </prompt><userinput>gdb smbd core</userinput> +</screen> <para> adding appropriate paths to smbd and core so gdb can find them. If you -don't have gdb then try <userinput>dbx</userinput>. Then within the debugger use the -command <userinput>where</userinput> to give a stack trace of where the problem -occurred. Include this in your mail. +don't have gdb then try <userinput>dbx</userinput>. Then within the debugger +use the command <command>where</command> to give a stack trace of where the +problem occurred. Include this in your report. </para> <para> -If you know any assembly language then do a <userinput>disass</userinput> of the routine +If you know any assembly language then do a +<command>disass</command> of the routine where the problem occurred (if its in a library routine then disassemble the routine that called it) and try to work out exactly where the problem is by looking at the surrounding code. Even if you @@ -177,8 +182,10 @@ useful. Unfortunately some unixes (in particular some recent linux kernels) refuse to dump a core file if the task has changed uid (which smbd does often). To debug with this sort of system you could try to attach -to the running process using <userinput>gdb smbd <replaceable>PID</replaceable></userinput> where you get <replaceable>PID</replaceable> from -<application>smbstatus</application>. Then use <userinput>c</userinput> to continue and try to cause the core dump +to the running process using +<userinput>gdb smbd <replaceable>PID</replaceable></userinput> where you get +<replaceable>PID</replaceable> from <application>smbstatus</application>. +Then use <command>c</command> to continue and try to cause the core dump using the client. The debugger should catch the fault and tell you where it occurred. </para> @@ -198,4 +205,3 @@ exactly what version you used. </sect1> </chapter> - diff --git a/docs/docbook/projdoc/CUPS-printing.xml b/docs/docbook/projdoc/CUPS-printing.xml index 7e302000e6..25d1ac6139 100644 --- a/docs/docbook/projdoc/CUPS-printing.xml +++ b/docs/docbook/projdoc/CUPS-printing.xml @@ -361,7 +361,7 @@ spooler can do: printfiles from all client platforms in a uniform way;</para></listitem> <listitem><para>act as a central accounting and billing server, as all files are passed through the <command>pstops</command> Filter and are therefor logged in - the CUPS <filename>page_log</filename>. - <emphasis>NOTE: </emphasis>this + the CUPS <filename>page_log</filename>. - <emphasis>NOTE: </emphasis>this can not happen with "raw" print jobs, which always remain unfiltered per definition;</para></listitem> <listitem><para>enable clients to consolidate on a single PostScript driver, even for @@ -1133,7 +1133,7 @@ selecting your model (Laserjet 4 Plus) and clicking on "Show execution details". This will bring up this web page: </para> -<para><ulink url="http://www.linuxprinting.org/execution.cgi?driver=ljet4&printer=75104&.submit=Show+execution+details">http://www.linuxprinting.org/execution.cgi?driver=ljet4&printer=75104&.submit=Show+execution+details</ulink></para> +<para><ulink url="http://www.linuxprinting.org/execution.cgi?driver=ljet4;printer=75104;.submit=Show+execution+details">http://www.linuxprinting.org/execution.cgi?driver=ljet4;printer=75104;.submit=Show+execution+details</ulink></para> <para> The ingenious thing is that the database is kept current. If there diff --git a/docs/docbook/projdoc/Compiling.xml b/docs/docbook/projdoc/Compiling.xml index 9638663dde..07251d7ed9 100644 --- a/docs/docbook/projdoc/Compiling.xml +++ b/docs/docbook/projdoc/Compiling.xml @@ -7,14 +7,15 @@ </author> &author.jelmer; - <pubdate> (22 May 2001) </pubdate> + <pubdate> 22 May 2001 </pubdate> <pubdate> 18 March 2003 </pubdate> </chapterinfo> <title>How to compile SAMBA</title> <para> -You can obtain the samba source from the <ulink url="http://samba.org/">samba website</ulink>. To obtain a development version, +You can obtain the samba source from the +<ulink url="http://samba.org/">samba website</ulink>. To obtain a development version, you can download samba from CVS or using rsync. </para> @@ -45,8 +46,8 @@ This chapter is a modified version of the instructions found at <para> The machine samba.org runs a publicly accessible CVS repository for access to the source code of several packages, -including samba, rsync and jitterbug. There are two main ways of -accessing the CVS server on this host. +including samba, rsync, distcc, ccache and jitterbug. There are two main ways +of accessing the CVS server on this host. </para> <sect3> @@ -80,11 +81,12 @@ just a casual browser. <para> To download the latest cvs source code, point your -browser at the URL : <ulink url="http://www.cyclic.com/">http://www.cyclic.com/</ulink>. +browser at the URL : +<ulink url="http://www.cyclic.com/">http://www.cyclic.com/</ulink>. and click on the 'How to get cvs' link. CVS is free software under the GNU GPL (as is Samba). Note that there are several graphical CVS clients which provide a graphical interface to the sometimes mundane CVS commands. -Links to theses clients are also available from http://www.cyclic.com. +Links to theses clients are also available from the Cyclic website. </para> <para> @@ -94,16 +96,17 @@ samba source code. For the other source code repositories on this system just substitute the correct package name </para> -<orderedlist> -<listitem> +<procedure> + <title>Retrieving samba using CVS</title> + + <step> <para> Install a recent copy of cvs. All you really need is a copy of the cvs client binary. </para> -</listitem> - + </step> -<listitem> + <step> <para> Run the command </para> @@ -111,14 +114,16 @@ on this system just substitute the correct package name <para> <userinput>cvs -d :pserver:cvs@samba.org:/cvsroot login</userinput> </para> + </step> + + <step> <para> When it asks you for a password type <userinput>cvs</userinput>. </para> -</listitem> + </step> - -<listitem> + <step> <para> Run the command </para> @@ -134,18 +139,19 @@ on this system just substitute the correct package name </para> <para> - CVS branches other then HEAD can be obtained by using the <parameter>-r</parameter> - and defining a tag name. A list of branch tag names can be found on the - "Development" page of the samba web site. A common request is to obtain the - latest 2.2 release code. This could be done by using the following userinput. + CVS branches other then HEAD can be obtained by using the + <option>-r</option> and defining a tag name. A list of branch tag names + can be found on the "Development" page of the samba web site. A common + request is to obtain the latest 3.0 release code. This could be done by + using the following userinput. </para> <para> - <userinput>cvs -d :pserver:cvs@samba.org:/cvsroot co -r SAMBA_2_2 samba</userinput> + <userinput>cvs -d :pserver:cvs@samba.org:/cvsroot co -r SAMBA_3_0 samba</userinput> </para> -</listitem> + </step> -<listitem> + <step> <para> Whenever you want to merge in the latest code changes use the following command from within the samba directory: @@ -154,8 +160,8 @@ on this system just substitute the correct package name <para> <userinput>cvs update -d -P</userinput> </para> -</listitem> -</orderedlist> + </step> +</procedure> </sect3> </sect2> @@ -166,16 +172,16 @@ on this system just substitute the correct package name <title>Accessing the samba sources via rsync and ftp</title> <para> - pserver.samba.org also exports unpacked copies of most parts of the CVS tree at <ulink url="ftp://pserver.samba.org/pub/unpacked">ftp://pserver.samba.org/pub/unpacked</ulink> and also via anonymous rsync at rsync://pserver.samba.org/ftp/unpacked/. I recommend using rsync rather than ftp. + pserver.samba.org also exports unpacked copies of most parts of the CVS + tree at <ulink url="ftp://pserver.samba.org/pub/unpacked">ftp://pserver.samba.org/pub/unpacked</ulink> and also via anonymous rsync at + <ulink url="rsync://pserver.samba.org/ftp/unpacked/">rsync://pserver.samba.org/ftp/unpacked/</ulink>. I recommend using rsync rather than ftp. See <ulink url="http://rsync.samba.org/">the rsync homepage</ulink> for more info on rsync. </para> <para> - The disadvantage of the unpacked trees - is that they do not support automatic - merging of local changes like CVS does. - rsync access is most convenient for an - initial install. + The disadvantage of the unpacked trees is that they do not support automatic + merging of local changes like CVS does. rsync access is most convenient + for an initial install. </para> </sect1> @@ -183,11 +189,10 @@ on this system just substitute the correct package name <title>Verifying Samba's PGP signature</title> <para> -In these days of insecurity, it's strongly recommended that you verify the PGP signature for any -source file before installing it. According to Jerry Carter of the Samba Team, only about 22% of -all Samba downloads have had a corresponding PGP signature download (a very low percentage, which -should be considered a bad thing). Even if you're not downloading from a mirror site, verifying PGP -signatures should be a standard reflex. +In these days of insecurity, it's strongly recommended that you verify the PGP +signature for any source file before installing it. Even if you're not +downloading from a mirror site, verifying PGP signatures should be a +standard reflex. </para> @@ -195,38 +200,39 @@ signatures should be a standard reflex. With that said, go ahead and download the following files: </para> -<para><programlisting> - $ wget http://us1.samba.org/samba/ftp/samba-2.2.8a.tar.asc - $ wget http://us1.samba.org/samba/ftp/samba-pubkey.asc -</programlisting></para> +<para><screen> +<prompt>$ </prompt><userinput> wget http://us1.samba.org/samba/ftp/samba-2.2.8a.tar.asc</userinput> +<prompt>$ </prompt><userinput> wget http://us1.samba.org/samba/ftp/samba-pubkey.asc</userinput> +</screen></para> <para> The first file is the PGP signature for the Samba source file; the other is the Samba public PGP key itself. Import the public PGP key with: </para> -<programlisting> - $ gpg --import samba-pubkey.asc -</programlisting> +<screen> + <prompt>$ </prompt><userinput>gpg --import samba-pubkey.asc</userinput> +</screen> <para> And verify the Samba source code integrity with: </para> -<programlisting> - $ gzip -d samba-2.2.8a.tar.gz - $ gpg --verify samba-2.2.8a.tar.asc -</programlisting> +<screen> + <prompt>$ </prompt><userinput>gzip -d samba-2.2.8a.tar.gz</userinput> + <prompt>$ </prompt><userinput>gpg --verify samba-2.2.8a.tar.asc</userinput> +</screen> <para> -If you receive a message like, "Good signature from Samba Distribution Verification Key..." -then all is well. The warnings about trust relationships can be ignored. An example of what -you would not want to see would be: +If you receive a message like, "Good signature from Samba Distribution +Verification Key..." +then all is well. The warnings about trust relationships can be ignored. An +example of what you would not want to see would be: </para> -<programlisting> +<computeroutput> gpg: BAD signature from "Samba Distribution Verification Key" -</programlisting> +</computeroutput> </sect1> @@ -238,28 +244,28 @@ you would not want to see would be: configure Samba for your operating system. If you have unusual needs then you may wish to run</para> - <para><prompt>root# </prompt><userinput>./configure --help + <para>&rootprompt;<userinput>./configure --help </userinput></para> <para>first to see what special options you can enable. Then executing</para> - <para><prompt>root# </prompt><userinput>make</userinput></para> + <para>&rootprompt;<userinput>make</userinput></para> <para>will create the binaries. Once it's successfully compiled you can use </para> - <para><prompt>root# </prompt><userinput>make install</userinput></para> + <para>&rootprompt;<userinput>make install</userinput></para> <para>to install the binaries and manual pages. You can separately install the binaries and/or man pages using</para> - <para><prompt>root# </prompt><userinput>make installbin + <para>&rootprompt;<userinput>make installbin </userinput></para> <para>and</para> - <para><prompt>root# </prompt><userinput>make installman + <para>&rootprompt;<userinput>make installman </userinput></para> <para>Note that if you are upgrading for a previous version @@ -267,7 +273,7 @@ you would not want to see would be: the binaries will be renamed with a ".old" extension. You can go back to the previous version with</para> - <para><prompt>root# </prompt><userinput>make revert + <para>&rootprompt;<userinput>make revert </userinput></para> <para>if you find this version a disaster!</para> @@ -288,28 +294,31 @@ you would not want to see would be: </itemizedlist> <para>If your kerberos libraries are in a non-standard location then - remember to add the configure option --with-krb5=DIR.</para> + remember to add the configure option + <option>--with-krb5=<replaceable>DIR</replaceable></option>.</para> - <para>After you run configure make sure that <filename>include/config.h</filename> it generates contains lines like this:</para> + <para>After you run configure make sure that + <filename>include/config.h</filename> it generates contains lines like + this:</para> - <para><programlisting> +<para><programlisting> #define HAVE_KRB5 1 #define HAVE_LDAP 1 </programlisting></para> - <para>If it doesn't then configure did not find your krb5 libraries or - your ldap libraries. Look in config.log to figure out why and fix - it.</para> + <para>If it doesn't then configure did not find your krb5 libraries or + your ldap libraries. Look in <filename>config.log</filename> to figure + out why and fix it.</para> <sect3> <title>Installing the required packages for Debian</title> <para>On Debian you need to install the following packages:</para> <para> - <itemizedlist> - <listitem>libkrb5-dev</listitem> - <listitem>krb5-user</listitem> - </itemizedlist> + <simplelist> + <member>libkrb5-dev</member> + <member>krb5-user</member> + </simplelist> </para> </sect3> @@ -318,11 +327,11 @@ you would not want to see would be: <para>On RedHat this means you should have at least: </para> <para> - <itemizedlist> - <listitem>krb5-workstation (for kinit)</listitem> - <listitem>krb5-libs (for linking with)</listitem> - <listitem>krb5-devel (because you are compiling from source)</listitem> - </itemizedlist> + <simplelist> + <member>krb5-workstation (for kinit)</member> + <member>krb5-libs (for linking with)</member> + <member>krb5-devel (because you are compiling from source)</member> + </simplelist> </para> <para>in addition to the standard development environment.</para> @@ -337,9 +346,9 @@ you would not want to see would be: </sect1> <sect1> - <title>Starting the smbd and nmbd</title> + <title>Starting the &smbd; and &nmbd;</title> - <para>You must choose to start smbd and nmbd either + <para>You must choose to start &smbd; and &nmbd; either as daemons or from <application>inetd</application>Don't try to do both! Either you can put them in <filename> inetd.conf</filename> and have them started on demand @@ -350,26 +359,28 @@ you would not want to see would be: the bit about what user you need to be in order to start Samba. In many cases you must be root.</para> - <para>The main advantage of starting <application>smbd</application> - and <application>nmbd</application> using the recommended daemon method + <para>The main advantage of starting &smbd; + and &nmbd; using the recommended daemon method is that they will respond slightly more quickly to an initial connection request.</para> <sect2> <title>Starting from inetd.conf</title> - <para>NOTE; The following will be different if + <note> + <para>The following will be different if you use NIS, NIS+ or LDAP to distribute services maps.</para> + </note> <para>Look at your <filename>/etc/services</filename>. What is defined at port 139/tcp. If nothing is defined then add a line like this:</para> - <para><userinput>netbios-ssn 139/tcp</userinput></para> + <para><programlisting>netbios-ssn 139/tcp</programlisting></para> <para>similarly for 137/udp you should have an entry like:</para> - <para><userinput>netbios-ns 137/udp</userinput></para> + <para><programlisting>netbios-ns 137/udp</programlisting></para> <para>Next edit your <filename>/etc/inetd.conf</filename> and add two lines something like this:</para> @@ -386,11 +397,13 @@ you would not want to see would be: <note><para>Some unixes already have entries like netbios_ns (note the underscore) in <filename>/etc/services</filename>. You must either edit <filename>/etc/services</filename> or - <filename>/etc/inetd.conf</filename> to make them consistent.</para></note> + <filename>/etc/inetd.conf</filename> to make them consistent. + </para></note> <note><para>On many systems you may need to use the - <command>interfaces</command> option in &smb.conf; to specify the IP address - and netmask of your interfaces. Run <application>ifconfig</application> + <parameter>interfaces</parameter> option in &smb.conf; to specify the IP + address and netmask of your interfaces. Run + <application>ifconfig</application> as root if you don't know what the broadcast is for your net. &nmbd; tries to determine it at run time, but fails on some unixes. @@ -402,9 +415,9 @@ you would not want to see would be: arguments, or you should use a script, and start the script from <command>inetd</command>.</para></warning> - <para>Restart <command>inetd</command>, perhaps just send - it a HUP. If you have installed an earlier version of <application> - nmbd</application> then you may need to kill nmbd as well.</para> + <para>Restart <application>inetd</application>, perhaps just send + it a HUP. If you have installed an earlier version of &nmbd; then + you may need to kill &nmbd; as well.</para> </sect2> <sect2> @@ -428,11 +441,29 @@ you would not want to see would be: </para> <para>To kill it send a kill signal to the processes - <command>nmbd</command> and <command>smbd</command>.</para> + &nmbd; and &smbd;.</para> <note><para>If you use the SVR4 style init system then you may like to look at the <filename>examples/svr4-startup</filename> script to make Samba fit into that system.</para></note> </sect2> </sect1> + +<sect1> +<title>Common Errors</title> + +<para><quote> +I'm using gcc 3 and I've compiled Samba-3 from the CVS and the +binaries are very large files (40 Mb and 20 Mb). I've the same result with +<option>--enable-shared</option> ? +</quote> +</para> + +<para> +The dwarf format used by GCC 3 for storing debugging symbols is very inefficient. +Strip the binaries, don't compile with -g or compile with -gstabs. +</para> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/DNS-DHCP-Configuration.xml b/docs/docbook/projdoc/DNS-DHCP-Configuration.xml new file mode 100644 index 0000000000..21bda63276 --- /dev/null +++ b/docs/docbook/projdoc/DNS-DHCP-Configuration.xml @@ -0,0 +1,17 @@ +<chapter id="DNSDHCP"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>DNS and DHCP Configuration Guide</title> + +<sect1> +<title>Note</title> + +<para> +This chapter did not make it into this release. +It is planned for the published release of this document. +</para> + +</sect1> +</chapter> diff --git a/docs/docbook/projdoc/DOMAIN_MEMBER.xml b/docs/docbook/projdoc/DOMAIN_MEMBER.xml index ecb8a3afb3..16d4198324 100644 --- a/docs/docbook/projdoc/DOMAIN_MEMBER.xml +++ b/docs/docbook/projdoc/DOMAIN_MEMBER.xml @@ -4,40 +4,48 @@ &author.jht; &author.jeremy; &author.jerry; + +<!-- Authors of the ADS-HOWTO --> + &author.tridge; + &author.jelmer; </chapterinfo> <title>Domain Membership</title> <para> -Domain Membership is a subject of vital concern, Samba must be able to participate -as a member server in a Microsoft Domain security context, and Samba must be capable of -providing Domain machine member trust accounts, otherwise it would not be capable of offering -a viable option for many users. +Domain Membership is a subject of vital concern, Samba must be able to +participate as a member server in a Microsoft Domain security context, and +Samba must be capable of providing Domain machine member trust accounts, +otherwise it would not be capable of offering a viable option for many users. </para> <para> -This chapter covers background information pertaining to domain membership, Samba -configuration for it, and MS Windows client procedures for joining a domain. Why is -this necessary? Because both are areas in which there exists within the current MS -Windows networking world and particularly in the Unix/Linux networking and administration -world, a considerable level of mis-information, incorrect understanding, and a lack of -knowledge. Hopefully this chapter will fill the voids. +This chapter covers background information pertaining to domain membership, +Samba configuration for it, and MS Windows client procedures for joining a +domain. Why is this necessary? Because both are areas in which there exists +within the current MS Windows networking world and particularly in the +Unix/Linux networking and administration world, a considerable level of +mis-information, incorrect understanding, and a lack of knowledge. Hopefully +this chapter will fill the voids. </para> <sect1> <title>Features and Benefits</title> <para> -MS Windows workstations and servers that want to participate in domain security need to +MS Windows workstations and servers that want to participate in domain +security need to be made Domain members. Participating in Domain security is often called -<emphasis>Single Sign On</emphasis> or SSO for short. This chapter describes the process -that must be followed to make a workstation (or another server - be it an MS Windows NT4 / 200x +<emphasis>Single Sign On</emphasis> or <acronym>SSO</acronym> for short. This +chapter describes the process that must be followed to make a workstation +(or another server - be it an <application>MS Windows NT4 / 200x</application> server) or a Samba server a member of an MS Windows Domain security context. </para> <para> -Samba-3 can join an MS Windows NT4 style domain as a native member server, an MS Windows -Active Directory Domain as a native member server, or a Samba Domain Control network. +Samba-3 can join an MS Windows NT4 style domain as a native member server, an +MS Windows Active Directory Domain as a native member server, or a Samba Domain +Control network. </para> <para> @@ -50,19 +58,21 @@ Domain membership has many advantages: </para></listitem> <listitem><para> - Domain user access rights and file ownership / access controls can be set from - the single Domain SAM (Security Accounts Management) database (works with Domain member - servers as well as with MS Windows workstations that are domain members) + Domain user access rights and file ownership / access controls can be set + from the single Domain SAM (Security Accounts Management) database + (works with Domain member servers as well as with MS Windows workstations + that are domain members) </para></listitem> <listitem><para> - Only MS Windows NT4 / 200x / XP Professional workstations that are Domain members + Only <application>MS Windows NT4 / 200x / XP Professional</application> + workstations that are Domain members can use network logon facilities </para></listitem> <listitem><para> - Domain Member workstations can be better controlled through the use of Policy files - (NTConfig.POL) and Desktop Profiles. + Domain Member workstations can be better controlled through the use of + Policy files (<filename>NTConfig.POL</filename>) and Desktop Profiles. </para></listitem> <listitem><para> @@ -71,10 +81,11 @@ Domain membership has many advantages: </para></listitem> <listitem><para> - Network administrators gain better application and user access management abilities - because there is no need to maintain user accounts on any network client or server, - other than the central Domain database (either NT4/Samba SAM style Domain, NT4 Domain - that is back ended with an LDAP directory, or via an Active Directory infrastructure) + Network administrators gain better application and user access management + abilities because there is no need to maintain user accounts on any network + client or server, other than the central Domain database + (either NT4/Samba SAM style Domain, NT4 Domain that is back ended with an + LDAP directory, or via an Active Directory infrastructure) </para></listitem> </itemizedlist> @@ -84,7 +95,8 @@ Domain membership has many advantages: <title>MS Windows Workstation/Server Machine Trust Accounts</title> <para> -A machine trust account is an account that is used to authenticate a client machine +A machine trust account is an account that is used to authenticate a client +machine (rather than a user) to the Domain Controller server. In Windows terminology, this is known as a "Computer Account." </para> @@ -113,10 +125,10 @@ as follows: <itemizedlist> <listitem><para> - A Domain Security Account (stored in the <emphasis>passdb backend</emphasis> - that has been configured in the &smb.conf; file. The precise nature of the - account information that is stored depends on the type of backend database - that has been chosen. + A Domain Security Account (stored in the + <parameter>passdb backend</parameter> that has been configured in the + &smb.conf; file. The precise nature of the account information that is + stored depends on the type of backend database that has been chosen. </para> <para> @@ -127,15 +139,17 @@ as follows: </para> <para> - The two newer database types are called <emphasis>ldapsam, tdbsam</emphasis>. - Both store considerably more data than the older <filename>smbpasswd</filename> - file did. The extra information enables new user account controls to be used. + The two newer database types are called <emphasis>ldapsam</emphasis>, + <emphasis>tdbsam</emphasis>. Both store considerably more data than the + older <filename>smbpasswd</filename> file did. The extra information + enables new user account controls to be used. </para></listitem> <listitem><para> - A corresponding Unix account, typically stored in <filename>/etc/passwd</filename>. - Work is in progress to allow a simplified mode of operation that does not require - Unix user accounts, but this may not be a feature of the early releases of Samba-3. + A corresponding Unix account, typically stored in + <filename>/etc/passwd</filename>. Work is in progress to allow a + simplified mode of operation that does not require Unix user accounts, but + this may not be a feature of the early releases of Samba-3. </para></listitem> </itemizedlist> </para> @@ -146,20 +160,22 @@ There are three ways to create machine trust accounts: <itemizedlist> <listitem><para> - Manual creation from the Unix/Linux command line. Here, both the Samba and corresponding - Unix account are created by hand. + Manual creation from the Unix/Linux command line. Here, both the Samba and + corresponding Unix account are created by hand. </para></listitem> <listitem><para> - Using the MS Windows NT4 Server Manager (either from an NT4 Domain member server, or using - the Nexus toolkit available from the Microsoft web site. This tool can be run from any - MS Windows machine so long as the user is logged on as the administrator account. + Using the MS Windows NT4 Server Manager (either from an NT4 Domain member + server, or using the Nexus toolkit available from the Microsoft web site. + This tool can be run from any MS Windows machine so long as the user is + logged on as the administrator account. </para></listitem> <listitem><para> - "On-the-fly" creation. The Samba machine trust account is automatically created by - Samba at the time the client is joined to the domain. (For security, this is the - recommended method.) The corresponding Unix account may be created automatically or manually. + "On-the-fly" creation. The Samba machine trust account is automatically + created by Samba at the time the client is joined to the domain. + (For security, this is the recommended method.) The corresponding Unix + account may be created automatically or manually. </para></listitem> </itemizedlist> @@ -167,26 +183,26 @@ There are three ways to create machine trust accounts: <title>Manual Creation of Machine Trust Accounts</title> <para> -The first step in manually creating a machine trust account is to manually create the -corresponding Unix account in <filename>/etc/passwd</filename>. This can be done using -<command>vipw</command> or other 'add user' command that is normally used to create new -Unix accounts. The following is an example for a Linux based Samba server: +The first step in manually creating a machine trust account is to manually +create the corresponding Unix account in <filename>/etc/passwd</filename>. +This can be done using <command>vipw</command> or another 'add user' command +that is normally used to create new Unix accounts. The following is an example for a Linux based Samba server: </para> <para> -<prompt>root# </prompt><command>/usr/sbin/useradd -g 100 -d /dev/null -c <replaceable>"machine nickname"</replaceable> -s /bin/false <replaceable>machine_name</replaceable>$ </command> +&rootprompt;<userinput>/usr/sbin/useradd -g 100 -d /dev/null -c <replaceable>"machine nickname"</replaceable> -s /bin/false <replaceable>machine_name</replaceable>$ </userinput> </para> <para> -<prompt>root# </prompt><command>passwd -l <replaceable>machine_name</replaceable>$</command> +&rootprompt;<userinput>passwd -l <replaceable>machine_name</replaceable>$</userinput> </para> <para> -On *BSD systems, this can be done using the 'chpass' utility: +On *BSD systems, this can be done using the <command>chpass</command> utility: </para> <para> -<prompt>root# </prompt><command>chpass -a "<replaceable>machine_name</replaceable>$:*:101:100::0:0:Workstation <replaceable>machine_name</replaceable>:/dev/null:/sbin/nologin"</command> +&rootprompt;<userinput>chpass -a "<replaceable>machine_name</replaceable>$:*:101:100::0:0:Workstation <replaceable>machine_name</replaceable>:/dev/null:/sbin/nologin"</userinput> </para> <para> @@ -196,9 +212,9 @@ home directory. For example a machine named 'doppy' would have an <filename>/etc/passwd</filename> entry like this: </para> -<para> +<programlisting> doppy$:x:505:501:<replaceable>machine_nickname</replaceable>:/dev/null:/bin/false -</para> +</programlisting> <para> Above, <replaceable>machine_nickname</replaceable> can be any @@ -218,9 +234,9 @@ as shown here: </para> <para> -<programlisting> -<prompt>root# </prompt><userinput>smbpasswd -a -m <replaceable>machine_name</replaceable></userinput> -</programlisting> +<screen> +&rootprompt;<userinput>smbpasswd -a -m <replaceable>machine_name</replaceable></userinput> +</screen>> </para> <para> @@ -235,11 +251,11 @@ the corresponding Unix account. <para> Manually creating a machine trust account using this method is the equivalent of creating a machine trust account on a Windows NT PDC using - the "Server Manager". From the time at which the account is created - to the time which the client joins the domain and changes the password, - your domain is vulnerable to an intruder joining your domain using - a machine with the same NetBIOS name. A PDC inherently trusts - members of the domain and will serve out a large degree of user + the <application>Server Manager</application>. From the time at which the + account is created to the time which the client joins the domain and + changes the password, your domain is vulnerable to an intruder joining + your domain using a machine with the same NetBIOS name. A PDC inherently + trusts members of the domain and will serve out a large degree of user information to such clients. You have been warned! </para> </warning> @@ -249,16 +265,19 @@ the corresponding Unix account. <title>Using NT4 Server Manager to Add Machine Accounts to the Domain</title> <para> -If the machine from which you are trying to manage the domain is an MS Windows NT4 workstation -then the tool of choice is the package called SRVTOOLS.EXE. When executed in the target directory -this will unpack SrvMge.exe and UsrMgr.exe (both are Domain Management tools for MS Windows NT4 -workstation. +If the machine from which you are trying to manage the domain is an +<application>MS Windows NT4 workstation</application> +then the tool of choice is the package called <command>SRVTOOLS.EXE</command>. +When executed in the target directory this will unpack +<command>SrvMge.exe</command> and <command>UsrMgr.exe</command> (both are +Domain Management tools for MS Windows NT4 workstation. </para> <para> -If your workstation is any other MS Windows product you should download the Nexus.exe package -from the Microsoft web site. When executed from the target directory this will unpack the same -tools but for use on MS Windows 9x/Me/200x/XP. +If your workstation is any other MS Windows product you should download the +<command>Nexus.exe</command> package from the Microsoft web site. When executed +from the target directory this will unpack the same tools but for use on +<application>MS Windows 9x/Me/200x/XP</application>. </para> <para> @@ -268,29 +287,32 @@ Launch the <command>srvmgr.exe</command> (Server Manager for Domains) and follow <procedure> <title>Server Manager Account Machine Account Management</title> <step><para> - From the menu select Computer + From the menu select <guimenu>Computer</guimenu> </para></step> <step><para> - Click on "Select Domain" + Click on <guimenuitem>Select Domain</guimenuitem> </para></step> <step><para> - Click on the name of the domain you wish to administer in the "Select Domain" panel - and then Click OK. + Click on the name of the domain you wish to administer in the + <guilabel>Select Domain</guilabel> panel and then click + <guibutton>OK</guibutton>. </para></step> <step><para> - Again from the menu select Computer + Again from the menu select <guimenu>Computer</guimenu> </para></step> <step><para> - Select "Add to Domain" + Select <guimenuitem>Add to Domain</guimenuitem> </para></step> <step><para> - In the dialog box, click on the radio button to "Add NT Workstation of Server", then - enter the machine name in the field provided, then Click the "Add" button. + In the dialog box, click on the radio button to + <guilabel>Add NT Workstation of Server</guilabel>, then + enter the machine name in the field provided, then click the + <guibutton>Add</guibutton> button. </para></step> </procedure> @@ -334,8 +356,8 @@ The procedure for making an MS Windows workstation of server a member of the dom with the version of Windows: </para> -<itemizedlist> - <listitem><para><emphasis>Windows 200x XP Professional</emphasis></para> +<sect3> + <title>Windows 200x XP Professional</title> <para> When the user elects to make the client a domain member, Windows 200x prompts for @@ -353,9 +375,9 @@ with the version of Windows: <para> The name of the account that is used to create domain member machine accounts can be - anything the network administrator may choose. If it is other than <command>root</command> + anything the network administrator may choose. If it is other than <emphasis>root</emphasis> then this is easily mapped to root using the file pointed to be the &smb.conf; parameter - <emphasis>username map =</emphasis> <command>/etc/samba/smbusers</command>. + <parameter>username map = /etc/samba/smbusers</parameter>. </para> <para> @@ -363,32 +385,37 @@ with the version of Windows: encryption key for setting the password of the machine trust account. The machine trust account will be created on-the-fly, or updated if it already exists. - </para></listitem> + </para> +</sect3> - <listitem><para><emphasis>Windows NT4</emphasis></para> +<sect3> + <title>Windows NT4</title> <para> If the machine trust account was created manually, on the Identification Changes menu enter the domain name, but do not - check the box "Create a Computer Account in the Domain." In this case, - the existing machine trust account is used to join the machine to - the domain. + check the box <guilabel>Create a Computer Account in the Domain</guilabel>. + In this case, the existing machine trust account is used to join the machine + to the domain. </para> <para> If the machine trust account is to be created on-the-fly, on the Identification Changes menu enter the domain - name, and check the box "Create a Computer Account in the Domain." In - this case, joining the domain proceeds as above for Windows 2000 - (i.e., you must supply a Samba administrative account when + name, and check the box <guilabel>Create a Computer Account in the + Domain</guilabel>. In this case, joining the domain proceeds as above + for Windows 2000 (i.e., you must supply a Samba administrative account when prompted). - </para></listitem> + </para> +</sect3> + +<sect3> + <title>Samba</title> - <listitem><para><emphasis>Samba</emphasis></para> <para>Joining a samba client to a domain is documented in the <link linkend="domain-member">Domain Member</link> chapter. - </para></listitem> -</itemizedlist> + </para> +</sect3> </sect2> </sect1> @@ -398,38 +425,44 @@ with the version of Windows: <para> This mode of server operation involves the samba machine being made a member -of a domain security context. This means by definition that all user authentication -will be done from a centrally defined authentication regime. The authentication -regime may come from an NT3/4 style (old domain technology) server, or it may be -provided from an Active Directory server (ADS) running on MS Windows 2000 or later. +of a domain security context. This means by definition that all user +authentication will be done from a centrally defined authentication regime. +The authentication regime may come from an NT3/4 style (old domain technology) +server, or it may be provided from an Active Directory server (ADS) running on +MS Windows 2000 or later. </para> <para> <emphasis> -Of course it should be clear that the authentication back end itself could be from any -distributed directory architecture server that is supported by Samba. This can be -LDAP (from OpenLDAP), or Sun's iPlanet, of NetWare Directory Server, etc. +Of course it should be clear that the authentication back end itself could be +from any distributed directory architecture server that is supported by Samba. +This can be LDAP (from OpenLDAP), or Sun's iPlanet, of NetWare Directory +Server, etc. </emphasis> </para> <para> -Please refer to the section on Howto configure Samba as a Primary Domain Controller -and for more information regarding how to create a domain machine account for a -domain member server as well as for information regarding how to enable the samba -domain member machine to join the domain and to be fully trusted by it. +Please refer to the <link linkend="samba-pdc">Domain Control chapter</link> +for more information regarding how to create a domain +machine account for a domain member server as well as for information +regarding how to enable the samba domain member machine to join the domain and +to be fully trusted by it. </para> <sect2> <title>Joining an NT4 type Domain with Samba-3</title> <para> -<emphasis>Assumptions:</emphasis> -<programlisting> - NetBIOS name: SERV1 - Win2K/NT domain name: DOM - Domain's PDC NetBIOS name: DOMPDC - Domain's BDC NetBIOS names: DOMBDC1 and DOMBDC2 -</programlisting> + <table frame="all"><title>Assumptions</title> +<tgroup align="left" cols="2"> + <tbody> + <row><entry>NetBIOS name:</entry><entry>SERV1</entry></row> + <row><entry>Win2K/NT domain name:</entry><entry>DOM</entry></row> + <row><entry>Domain's PDC NetBIOS name:</entry><entry>DOMPDC</entry></row> + <row><entry>Domain's BDC NetBIOS names:</entry><entry>DOMBDC1 and DOMBDC2</entry></row> +</tbody> +</tgroup> +</table> </para> <para> @@ -439,24 +472,25 @@ now use domain security. <para> Change (or add) your <ulink url="smb.conf.5.html#SECURITY"> -<parameter>security =</parameter></ulink> line in the [global] section +<parameter>security</parameter></ulink> line in the [global] section of your &smb.conf; to read: </para> <para> <programlisting> - <command>security = domain</command> +security = domain </programlisting> </para> <para> Next change the <ulink url="smb.conf.5.html#WORKGROUP"><parameter> -workgroup =</parameter></ulink> line in the [global] section to read: +workgroup</parameter></ulink> line in the <parameter>[global]</parameter> +section to read: </para> <para> <programlisting> - <command>workgroup = DOM</command> +workgroup = DOM </programlisting> </para> @@ -472,13 +506,13 @@ You must also have the parameter <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS"> <para> Finally, add (or modify) a <ulink url="smb.conf.5.html#PASSWORDSERVER"> -<parameter>password server =</parameter></ulink> line in the [global] +<parameter>password server</parameter></ulink> line in the [global] section to read: </para> <para> <programlisting> - <command>password server = DOMPDC DOMBDC1 DOMBDC2</command> +password server = DOMPDC DOMBDC1 DOMBDC2 </programlisting> </para> @@ -498,7 +532,7 @@ set this line to be: <para> <programlisting> - <command>password server = *</command> +password server = * </programlisting> </para> @@ -513,14 +547,14 @@ In order to actually join the domain, you must run this command: </para> <para> -<programlisting> - <prompt>root# </prompt><userinput>net join -S DOMPDC -U<replaceable>Administrator%password</replaceable></userinput> -</programlisting> +<screen> +<prompt>root# </prompt><userinput>net join -S DOMPDC -U<replaceable>Administrator%password</replaceable></userinput> +</screen> </para> <para> -If the <userinput>-S DOMPDC</userinput> argument is not given then -the domain name will be obtained from smb.conf. +If the <option>-S DOMPDC</option> argument is not given then +the domain name will be obtained from &smb.conf;. </para> <para> @@ -604,11 +638,11 @@ domain PDC to an account domain PDC). </para> <para> -In addition, with <command>security = server</command> every Samba +In addition, with <parameter>security = server</parameter> every Samba daemon on a server has to keep a connection open to the authenticating server for as long as that daemon lasts. This can drain the connection resources on a Microsoft NT server and cause it to run -out of available connections. With <command>security = domain</command>, +out of available connections. With <parameter>security = domain</parameter>, however, the Samba daemons connect to the PDC/BDC only for as long as is necessary to authenticate the user, and then drop the connection, thus conserving PDC connection resources. @@ -624,8 +658,8 @@ as the user SID, the list of NT groups the user belongs to, etc. <note> <para> Much of the text of this document -was first published in the Web magazine <ulink url="http://www.linuxworld.com"> -LinuxWorld</ulink> as the article <ulink +was first published in the Web magazine +<ulink url="http://www.linuxworld.com">LinuxWorld</ulink> as the article <ulink url="http://www.linuxworld.com/linuxworld/lw-1998-10/lw-10-samba.html">Doing the NIS/NT Samba</ulink>. </para> @@ -646,7 +680,7 @@ Windows2000 KDC. <title>Setup your <filename>smb.conf</filename></title> <para> -You must use at least the following 3 options in smb.conf: +You must use at least the following 3 options in &smb.conf;: </para> <para><programlisting> @@ -657,17 +691,18 @@ You must use at least the following 3 options in smb.conf: <para> In case samba can't figure out your ads server using your realm name, use the -<command>ads server</command> option in <filename>smb.conf</filename>: +<parameter>ads server</parameter> option in <filename>smb.conf</filename>: <programlisting> ads server = your.kerberos.server </programlisting> </para> <note><para> -You do *not* need a smbpasswd file, and older clients will be authenticated as if -<command>security = domain</command>, although it won't do any harm and allows you -to have local users not in the domain. I expect that the above required options will -change soon when we get better active directory integration. +You do <strong>not</strong> need a smbpasswd file, and older clients will be authenticated as +if <parameter>security = domain</parameter>, although it won't do any harm and +allows you to have local users not in the domain. It is expected that the above +required options will change soon when active directory integration will get +better. </para></note> </sect2> @@ -676,10 +711,6 @@ change soon when we get better active directory integration. <title>Setup your <filename>/etc/krb5.conf</filename></title> <para> -Note: you will need the krb5 workstation, devel, and libs installed -</para> - -<para> The minimal configuration for <filename>krb5.conf</filename> is: </para> @@ -697,14 +728,14 @@ making sure that your password is accepted by the Win2000 KDC. </para> <note><para> -The realm must be uppercase or you will get "Cannot find KDC for requested -realm while getting initial credentials" error +The realm must be uppercase or you will get <errorname>Cannot find KDC for +requested realm while getting initial credentials</errorname> error </para></note> <note><para> Time between the two servers must be synchronized. You will get a -"kinit(v5): Clock skew too great while getting initial credentials" if the time -difference is more than five minutes. +<errorname>kinit(v5): Clock skew too great while getting initial credentials</errorname> +if the time difference is more than five minutes. </para></note> <para> @@ -719,7 +750,7 @@ followed by the realm. The easiest way to ensure you get this right is to add a <filename>/etc/hosts</filename> entry mapping the IP address of your KDC to its netbios name. If you don't get this right then you will get a -"local error" when you try to join the realm. +<errorname>local error</errorname> when you try to join the realm. </para> <para> @@ -748,12 +779,12 @@ As a user that has write permission on the Samba private directory <para> <variablelist> - <varlistentry><term>"ADS support not compiled in"</term> + <varlistentry><term><errorname>ADS support not compiled in</errorname></term> <listitem><para>Samba must be reconfigured (remove config.cache) and recompiled (make clean all install) after the kerberos libs and headers are installed. </para></listitem></varlistentry> - <varlistentry><term>net join prompts for user name</term> + <varlistentry><term><errorname>net join prompts for user name</errorname></term> <listitem><para>You need to login to the domain using <userinput>kinit <replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput>. <replaceable>USERNAME</replaceable> must be a user who has rights to add a machine @@ -803,7 +834,7 @@ install, to create the right encoding types </para> <para> -w2k doesn't seem to create the _kerberos._udp and _ldap._tcp in +W2k doesn't seem to create the _kerberos._udp and _ldap._tcp in their defaults DNS setup. Maybe fixed in service packs? </para> @@ -846,14 +877,14 @@ the old account and then to add the machine with a new name. <para> Adding a Windows 200x or XP Professional machine to the Samba PDC Domain fails with a -message that, "The machine could not be added at this time, there is a network problem. -Please try again later." Why? +message that, <errorname>The machine could not be added at this time, there is a network problem. +Please try again later.</errorname> Why? </para> <para> -You should check that there is an <emphasis>add machine script</emphasis> in your &smb.conf; +You should check that there is an <parameter>add machine script</parameter> in your &smb.conf; file. If there is not, please add one that is appropriate for your OS platform. If a script -has been defined you will need to debug it's operation. Increase the <emphasis>log level</emphasis> +has been defined you will need to debug it's operation. Increase the <parameter>log level</parameter> in the &smb.conf; file to level 10, then try to rejoin the domain. Check the logs to see which operation is failing. </para> diff --git a/docs/docbook/projdoc/Diagnosis.xml b/docs/docbook/projdoc/Diagnosis.xml index 150f071b78..50c5e1352d 100644 --- a/docs/docbook/projdoc/Diagnosis.xml +++ b/docs/docbook/projdoc/Diagnosis.xml @@ -129,7 +129,7 @@ run ping. </para> <para> -If you get a message saying "host not found" or similar then your DNS +If you get a message saying <errorname>host not found</errorname> or similar then your DNS software or <filename>/etc/hosts</filename> file is not correctly setup. It is possible to run samba without DNS entries for the server and client, but I assume @@ -143,10 +143,12 @@ in question, perhaps by allowing access from another subnet (on Linux this is done via the <application>ipfwadm</application> program.) </para> +<note> <para> -Note: Modern Linux distributions install ipchains/iptables by default. +Modern Linux distributions install ipchains/iptables by default. This is a common problem that is often overlooked. </para> +</note> </step> <step performance="required"> @@ -165,7 +167,7 @@ temporarily remove any <command>hosts allow</command>, <command>hosts deny</comm </para> <para> -If you get a "connection refused" response then the smbd server may +If you get a <errorname>connection refused</errorname> response then the smbd server may not be running. If you installed it in inetd.conf then you probably edited that file incorrectly. If you installed it as a daemon then check that it is running, and check that the netbios-ssn port is in a LISTEN @@ -180,7 +182,7 @@ this network super daemon. </para></note> <para> -If you get a "session request failed" then the server refused the +If you get a <errorname>session request failed</errorname> then the server refused the connection. If it says "Your server software is being unfriendly" then its probably because you have invalid command line parameters to &smbd;, or a similar fatal problem with the initial startup of &smbd;. Also @@ -213,7 +215,7 @@ To solve this problem change these lines to: </programlisting></para> <para> -Do NOT use the <command>bind interfaces only</command> parameter where you +Do <strong>not</strong> use the <command>bind interfaces only</command> parameter where you may wish to use the samba password change facility, or where &smbclient; may need to access a local service for name resolution or for local resource @@ -224,7 +226,8 @@ fixed soon). <para> Another common cause of these two errors is having something already running -on port 139, such as Samba (ie: smbd is running from <application>inetd</application> already) or +on port <constant>139</constant>, such as Samba +(ie: &smbd; is running from <application>inetd</application> already) or something like Digital's Pathworks. Check your <filename>inetd.conf</filename> file before trying to start &smbd; as a daemon, it can avoid a lot of frustration! </para> @@ -288,8 +291,8 @@ This time we are trying the same as the previous test but are trying it via a broadcast to the default broadcast address. A number of Netbios/TCPIP hosts on the network should respond, although Samba may not catch all of the responses in the short time it listens. You -should see "got a positive name query response" messages from several -hosts. +should see <errorname>got a positive name query response</errorname> +messages from several hosts. </para> <para> @@ -332,12 +335,12 @@ as follows: <para> Once you enter the password you should get the <prompt>smb></prompt> prompt. If you -don't then look at the error message. If it says "invalid network -name" then the service "tmp" is not correctly setup in your &smb.conf;. +don't then look at the error message. If it says <errorname>invalid network +name</errorname> then the service <emphasis>"tmp"</emphasis> is not correctly setup in your &smb.conf;. </para> <para> -If it says "bad password" then the likely causes are: +If it says <errorname>bad password</errorname> then the likely causes are: </para> <orderedlist> @@ -369,8 +372,7 @@ If it says "bad password" then the likely causes are: <listitem> <para> - you enabled password encryption but didn't create the SMB encrypted - password file + you enabled password encryption but didn't map unix to samba users </para> </listitem> </orderedlist> @@ -394,7 +396,7 @@ list of available shares on the server. </para> <para> -If you get a "network name not found" or similar error then netbios +If you get a <errorname>network name not found</errorname> or similar error then netbios name resolution is not working. This is usually caused by a problem in nmbd. To overcome it you could do one of the following (you only need to choose one of them): @@ -421,7 +423,7 @@ to choose one of them): </orderedlist> <para> -If you get a "invalid network name" or "bad password error" then the +If you get a <errorname>invalid network name</errorname> or <errorname>bad password error</errorname> then the same fixes apply as they did for the <userinput>smbclient -L</userinput> test above. In particular, make sure your <command>hosts allow</command> line is correct (see the man pages) @@ -436,7 +438,7 @@ name and password. </para> <para> -If you get "specified computer is not receiving requests" or similar +If you get <errorname>specified computer is not receiving requests</errorname> or similar it probably means that the host is not contactable via tcp services. Check to see if the host is running tcp wrappers, and if so add an entry in the <filename>hosts.allow</filename> file for your client (or subnet, etc.) @@ -448,16 +450,16 @@ the <filename>hosts.allow</filename> file for your client (or subnet, etc.) <para> Run the command <userinput>net use x: \\BIGSERVER\TMP</userinput>. You should -be prompted for a password then you should get a "command completed -successfully" message. If not then your PC software is incorrectly +be prompted for a password then you should get a <computeroutput>command completed +successfully</computeroutput> message. If not then your PC software is incorrectly installed or your smb.conf is incorrect. make sure your <command>hosts allow</command> and other config lines in &smb.conf; are correct. </para> <para> It's also possible that the server can't work out what user name to -connect you as. To see if this is the problem add the line <command>user = -<replaceable>username</replaceable></command> to the <command>[tmp]</command> section of +connect you as. To see if this is the problem add the line <parameter>user = +<replaceable>username</replaceable></parameter> to the <parameter>[tmp]</parameter> section of &smb.conf; where <replaceable>username</replaceable> is the username corresponding to the password you typed. If you find this fixes things you may need the username mapping option. @@ -465,7 +467,7 @@ fixes things you may need the username mapping option. <para> It might also be the case that your client only sends encrypted passwords -and you have <command>encrypt passwords = no</command> in &smb.conf; +and you have <parameter>encrypt passwords = no</parameter> in &smb.conf; Turn it back on to fix. </para> @@ -484,7 +486,7 @@ master browser for that workgroup. If you don't then the election process has failed. Wait a minute to see if it is just being slow then try again. If it still fails after that then look at the browsing options you have set in &smb.conf;. Make -sure you have <command>preferred master = yes</command> to ensure that +sure you have <parameter>preferred master = yes</parameter> to ensure that an election is held at startup. </para> @@ -500,9 +502,9 @@ of the server and get a list of shares. If you get a "invalid password" error when you do then you are probably running WinNT and it is refusing to browse a server that has no encrypted password capability and is in user level security mode. In this case either set -<command>security = server</command> AND -<command>password server = Windows_NT_Machine</command> in your -&smb.conf; file, or make sure <command>encrypted passwords</command> is +<parameter>security = server</parameter> AND +<parameter>password server = Windows_NT_Machine</parameter> in your +&smb.conf; file, or make sure <parameter>encrypted passwords</parameter> is set to "yes". </para> diff --git a/docs/docbook/projdoc/FastStart.xml b/docs/docbook/projdoc/FastStart.xml new file mode 100644 index 0000000000..a51f878e5c --- /dev/null +++ b/docs/docbook/projdoc/FastStart.xml @@ -0,0 +1,17 @@ +<chapter id="FastStart"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>FastStart for the Impatient</title> + +<sect1> +<title>Note</title> + +<para> +This chapter did not make it into this release. +It is planned for the published release of this document. +</para> + +</sect1> +</chapter> diff --git a/docs/docbook/projdoc/Further-Resources.xml b/docs/docbook/projdoc/Further-Resources.xml index 9f193e3b8d..a6be7f6cd2 100644 --- a/docs/docbook/projdoc/Further-Resources.xml +++ b/docs/docbook/projdoc/Further-Resources.xml @@ -7,6 +7,9 @@ <title>Further Resources</title> +<sect1> + <title>Websites</title> + <itemizedlist> <listitem><para> @@ -74,6 +77,102 @@ </ulink> </para></listitem> + <listitem><para> + <ulink url="http://ru.samba.org/samba/ftp/docs/Samba24Hc13.pdf"> + <emphasis>PDF version of the Troubleshooting Techniques chapter</emphasis> + from the second edition of Sam's Teach Yourself Samba in 24 Hours + (publishing date of Dec. 12, 2001)</ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://ru.samba.org/samba/ftp/slides/"> + <emphasis>Slide presentations</emphasis> by Samba Team members + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.atmarkit.co.jp/flinux/special/samba3/samba3a.html"> + <emphasis>Introduction to Samba 3.0</emphasis> by Motonobu Takahashi + (written in Japanese). </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.linux-mag.com/2001-05/smb_01.html"> + <emphasis>Understanding the Network Neighborhood</emphasis>, by team member + Chris Hertel. This article appeared in the May 2001 issue of + Linux Magazine. + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="ftp://ftp.stratus.com/pub/vos/customers/samba/"> + <emphasis>Samba 2.0.x Troubleshooting guide</emphasis> from Paul Green + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://samba.org/samba/docs/10years.html"> + <emphasis>Ten Years of Samba</emphasis> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://tldp.org/HOWTO/Samba-Authenticated-Gateway-HOWTO.html"> + <emphasis>Samba Authenticated Gateway HOWTO</emphasis> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://samba.org/samba/docs/SambaIntro.html"> + <emphasis>An Introduction to Samba</emphasis> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.samba.org/cifs/"> + <emphasis>What is CIFS?</emphasis> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://support.microsoft.com/support/kb/articles/q92/5/88.asp"> + <emphasis>WFWG: Password Caching and How It Affects LAN Manager + Security</emphasis> at Microsoft Knowledge Base + </ulink> + </para></listitem> + </itemizedlist> +</sect1> + +<sect1> + <title>Related updates from microsoft</title> + +<itemizedlist> + <listitem><para> + <ulink url="http://support.microsoft.com/support/kb/articles/q92/5/88.asp"> + <emphasis>Enhanced Encryption for Windows 95 Password Cache</emphasis> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://support.microsoft.com/support/kb/articles/q136/4/18.asp"> + <emphasis>Windows '95 File Sharing Updates</emphasis> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://support.microsoft.com/support/kb/articles/q136/4/18.asp"> + <emphasis>Windows for Workgroups Sharing Updates</emphasis> + </ulink> + </para></listitem> + +</itemizedlist> +</sect1> + +<sect1> + <title>Books</title> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml b/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml index af6ddff9bf..8104fcd647 100644 --- a/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml +++ b/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml @@ -5,100 +5,308 @@ <firstname>Jean François</firstname><surname>Micouleau</surname> </author> &author.jerry; + &author.jht; </chapterinfo> +<title>Mapping MS Windows and Unix Groups</title> -<title>Configuring Group Mapping</title> + <para> + Starting with Samba-3, new group mapping functionality is available to create associations + between Windows group SIDs and UNIX groups. The <parameter>groupmap</parameter> subcommand + included with the &net; tool can be used to manage these associations. + </para> -<para> -Starting with Samba 3.0 alpha 2, new group mapping functionality -is available to create associations between Windows SIDs and UNIX -groups. The <parameter>groupmap</parameter> subcommand included with -the <command>net</command> tool can be used to manage these associations. -</para> + <warning> + <para> + The first immediate reason to use the group mapping on a Samba PDC, is that + the <parameter>domain admin group</parameter> has been removed and should no longer + be specified in &smb.conf;. This parameter was used to give the listed users membership + in the <constant>Domain Admins</constant> Windows group which gave local admin rights on their workstations + (in default configurations). + </para> + </warning> -<para> -The first immediate reason to use the group mapping on a Samba PDC, is that -the <parameter>domain admin group</parameter> &smb.conf; has been removed. -This parameter was used to give the listed users membership in the "Domain Admins" -Windows group which gave local admin rights on their workstations (in -default configurations). -</para> +<sect1> +<title>Features and Benefits</title> -<para> -When installing NT/W2K on a computer, the installer program creates some users -and groups. Notably the 'Administrators' group, and gives to that group some -privileges like the ability to change the date and time or to kill any process -(or close too) running on the local machine. The 'Administrator' user is a -member of the 'Administrators' group, and thus 'inherit' the 'Administrators' -group privileges. If a 'joe' user is created and become a member of the -'Administrator' group, 'joe' has exactly the same rights as 'Administrator'. -</para> + <para> + Samba allows the administrator to create MS Windows NT4 / 200x group accounts and to + arbitrarily associate them with Unix/Linux group accounts. + </para> -<para> -When a NT/W2K machine is joined to a domain, the "Domain Adminis" group of the -PDC is added to the local 'Administrators' group of the workstation. Every -member of the 'Domain Administrators' group 'inherit' the -rights of the local 'Administrators' group when logging on the workstation. + <para> + Group accounts can be managed using the MS Windows NT4 or MS Windows 200x MMC tools + so long as appropriate interface scripts have been provided to &smb.conf; + </para> + + <para> + Administrators should be aware that where &smb.conf; group interface scripts make + direct calls to the Unix/Linux system tools (eg: the shadow utilities, <command>groupadd</command>, + <command>groupdel</command>, <command>groupmod</command>) then the resulting Unix/Linux group names will be subject + to any limits imposed by these tools. If the tool does NOT allow upper case characters + or space characters, then the creation of an MS Windows NT4 / 200x style group of + <parameter>Engineering Managers</parameter> will attempt to create an identically named + Unix/Linux group, an attempt that will of course fail! + </para> + + <para> + There are several possible work-arounds for the operating system tools limitation. One + method is to use a script that generates a name for the Unix/Linux system group that + fits the operating system limits, and that then just passes the Unix/Linux group id (GID) + back to the calling samba interface. This will provide a dynamic work-around solution. + </para> + + <para> + Another work-around is to manually create a Unix/Linux group, then manually create the + MS Windows NT4 / 200x group on the Samba server and then use the <command>net groupmap</command> + tool to connect the two to each other. + </para> + +</sect1> + +<sect1> +<title>Discussion</title> + + <para> + When installing <application>MS Windows NT4 / 200x</application> on a computer, the installation + program creates default users and groups. Notably the <constant>Administrators</constant> group, + and gives to that group privileges necessary privilidges to perform essential system tasks. + eg: Ability to change the date and time or to kill any process (or close too) running on the + local machine. + </para> + + <para> + The 'Administrator' user is a member of the 'Administrators' group, and thus inherits + 'Administrators' group privileges. If a 'joe' user is created to be a member of the + 'Administrator' group, 'joe' has exactly the same rights as 'Administrator'. + </para> + + <para> + When an MS Windows NT4 / W200x is made a domain member, the "Domain Adminis" group of the + PDC is added to the local 'Administrators' group of the workstation. Every member of the + 'Domain Administrators' group inherits the rights of the local 'Administrators' group when + logging on the workstation. + </para> + + <para> + The following steps describe how to make samba PDC users members of the 'Domain Admins' group? + </para> + + <orderedlist> + <listitem><para> + create a unix group (usually in <filename>/etc/group</filename>), let's call it domadm + </para></listitem> + + <listitem><para>add to this group the users that must be Administrators. For example + if you want joe,john and mary, your entry in <filename>/etc/group</filename> will + look like: + </para> + + <para><programlisting> + domadm:x:502:joe,john,mary + </programlisting> + </para></listitem> + + <listitem><para> + Map this domadm group to the "Domain Admins" group by running the command: + </para> + + <para> + <screen> + &rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm</userinput> + </screen> + </para> + + <para> + The quotes around "Domain Admins" are necessary due to the space in the group name. + Also make sure to leave no whitespace surrounding the equal character (=). + </para></listitem> + </orderedlist> + + <para> + Now joe, john and mary are domain administrators! + </para> + + <para> + It is possible to map any arbitrary UNIX group to any Windows NT4 / 200x group as well as + making any UNIX group a Windows domain group. For example, if you wanted to include a + UNIX group (e.g. acct) in a ACL on a local file or printer on a domain member machine, + you would flag that group as a domain group by running the following on the Samba PDC: + </para> + + <para> + <screen> + &rootprompt;<userinput>net groupmap add rid=1000 ntgroup="Accounting" unixgroup=acct</userinput> + </screen> + </para> + + <para> + Be aware that the RID parmeter is a unsigned 32 bit integer that should + normally start at 1000. However, this rid must not overlap with any RID assigned + to a user. Verifying this is done differently depending on on the passdb backend + you are using. Future versions of the tools may perform the verification automatically, + but for now the burden is on you. + </para> + + <sect2> + <title>Example Configuration</title> + + <para> + You can list the various groups in the mapping database by executing + <command>net groupmap list</command>. Here is an example: + </para> + + <para> + <screen> + &rootprompt; <userinput>net groupmap list</userinput> + System Administrators (S-1-5-21-2547222302-1596225915-2414751004-1002) -> sysadmin + Domain Admins (S-1-5-21-2547222302-1596225915-2414751004-512) -> domadmin + Domain Users (S-1-5-21-2547222302-1596225915-2414751004-513) -> domuser + Domain Guests (S-1-5-21-2547222302-1596225915-2414751004-514) -> domguest + </screen> + </para> + + <para> + For complete details on <command>net groupmap</command>, refer to the net(8) man page. + </para> + + </sect2> + +</sect1> + +<sect1> +<title>Configuration Scripts</title> + + <para> + Everyone needs tools. Some of us like to create our own, others prefer to use canned tools + (ie: prepared by someone else for general use). + </para> + + <sect2> + <title>Sample &smb.conf; add group script</title> + + <para> + A script to great complying group names for use by the samba group interfaces: + </para> + + <para> +<example> + <title>smbgrpadd.sh</title> +<programlisting> + +#!/bin/bash + +# Add the group using normal system groupadd tool. +groupadd smbtmpgrp00 + +thegid=`cat /etc/group | grep smbtmpgrp00 | cut -d ":" -f3` + +# Now change the name to what we want for the MS Windows networking end +cat /etc/group | sed s/smbtmpgrp00/$1/g > /etc/group + +# Now return the GID as would normally happen. +echo $thegid +exit 0 +</programlisting> +</example> </para> + <para> + The &smb.conf; entry for the above script would look like: + <programlisting> + add group script = /path_to_tool/smbgrpadd.sh %g + </programlisting> + </para> + + </sect2> + + <sect2> + <title>Script to configure Group Mapping</title> + + <para> + In our example we have created a Unix/Linux group called <parameter>ntadmin</parameter>. + Our script will create the additional groups <parameter>Engineers, Marketoids, Gnomes</parameter>: + </para> + <para> -The following steps describe how to make samba PDC users members of the -'Domain Admins' group? -</para> +<programlisting> +#!/bin/bash -<orderedlist> -<listitem><para>create a unix group (usually in <filename>/etc/group</filename>), - let's call it domadm</para></listitem> -<listitem><para>add to this group the users that must be Administrators. For example - if you want joe,john and mary, your entry in <filename>/etc/group</filename> will - look like:</para> +net groupmap modify ntgroup="Domain Admins" unixgroup=ntadmin +net groupmap modify ntgroup="Domain Users" unixgroup=users +net groupmap modify ntgroup="Domain Guests" unixgroup=nobody +net groupmap modify ntgroup="Administrators" unixgroup=root +net groupmap modify ntgroup="Users" unixgroup=users +net groupmap modify ntgroup="Guests" unixgroup=nobody +net groupmap modify ntgroup="System Operators" unixgroup=sys +net groupmap modify ntgroup="Account Operators" unixgroup=root +net groupmap modify ntgroup="Backup Operators" unixgroup=bin +net groupmap modify ntgroup="Print Operators" unixgroup=lp +net groupmap modify ntgroup="Replicators" unixgroup=daemon +net groupmap modify ntgroup="Power Users" unixgroup=sys - <para><programlisting> - domadm:x:502:joe,john,mary - </programlisting></para> +#groupadd Engineers +#groupadd Marketoids +#groupadd Gnomes - </listitem> +#net groupmap add ntgroup="Engineers" unixgroup=Engineers type=d +#net groupmap add ntgroup="Marketoids" unixgroup=Marketoids type=d +#net groupmap add ntgroup="Gnomes" unixgroup=Gnomes type=d +</programlisting> +</para> -<listitem><para>Map this domadm group to the "Domain Admins" group - by running the command:</para> + <para> + Of course it is expected that the admininstrator will modify this to suit local needs. + For information regarding the use of the <command>net groupmap</command> tool please + refer to the man page. + </para> - <para><prompt>root# </prompt><userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm</userinput></para> - - <para>The quotes around "Domain Admins" are necessary due to the space in the group name. Also make - sure to leave no whitespace surrounding the equal character (=).</para> - </listitem> + </sect2> -</orderedlist> +</sect1> -<para>Now joe, john and mary are domain administrators!</para> +<sect1> +<title>Common Errors</title> <para> -It is possible to map any arbitrary UNIX group to any Windows NT -group as well as making any UNIX group a Windows domain group. -For example, if you wanted to include a UNIX group (e.g. acct) in a ACL on a -local file or printer on a domain member machine, you would flag -that group as a domain group by running the following on the Samba PDC: +At this time there are many little surprises for the unwary administrator. In a real sense +it is imperative that every step of automated control scripts must be carefully tested +manually before putting them into active service. </para> -<para><prompt>root# </prompt><userinput>net groupmap add rid=1000 ntgroup="Accounting" unixgroup=acct</userinput></para> + <sect2> + <title>Adding Groups Fails</title> + + <para> + This is a common problem when the <command>groupadd</command> is called directly + by the samba interface script for the <parameter>add group script</parameter> in + the &smb.conf; file. + </para> + + <para> + The most common cause of failure is an attempt to add an MS Windows group acocunt + that has either an upper case character and/or a space character in it. + </para> + + <para> + There are three possible work-arounds. Firstly, use only group names that comply + with the limitations of the Unix/Linux <command>groupadd</command> system tool. + The second involves use of the script mentioned earlier in this chapter, and the + third option is to manually create a Unix/Linux group account that can substitute + for the MS Windows group name, then use the procedure listed above to map that group + to the MS Windows group. + </para> + + </sect2> -<para>Be aware that the rid parmeter is a unsigned 32 bit integer that should -normally start at 1000. However, this rid must not overlap with any RID assigned -to a user. Verifying this is done differently depending on on the passdb backend -you are using. Future versions of the tools may perform the verification automatically, -but for now the burden in on you.</para> + <sect2> + <title>Adding MS Windows Groups to MS Windows Groups Fails</title> -<para>You can list the various groups in the mapping database by executing -<command>net groupmap list</command>. Here is an example:</para> + <para> + Samba-3 does NOT support nested groups from the MS Windows control environment. + </para> -<para><programlisting><prompt>root# </prompt>net groupmap list -System Administrators (S-1-5-21-2547222302-1596225915-2414751004-1002) -> sysadmin -Domain Admins (S-1-5-21-2547222302-1596225915-2414751004-512) -> domadmin -Domain Users (S-1-5-21-2547222302-1596225915-2414751004-513) -> domuser -Domain Guests (S-1-5-21-2547222302-1596225915-2414751004-514) -> domguest -</programlisting></para> + </sect2> -<para>For complete details on <command>net groupmap</command>, refer to the -net(8) man page.</para> +</sect1> </chapter> diff --git a/docs/docbook/projdoc/HighAvailability.xml b/docs/docbook/projdoc/HighAvailability.xml new file mode 100644 index 0000000000..3cd7fac807 --- /dev/null +++ b/docs/docbook/projdoc/HighAvailability.xml @@ -0,0 +1,17 @@ +<chapter id="SambaHA"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>High Availability Options</title> + +<sect1> +<title>Note</title> + +<para> +This chapter did not make it into this release. +It is planned for the published release of this document. +</para> + +</sect1> +</chapter> diff --git a/docs/docbook/projdoc/Integrating-with-Windows.xml b/docs/docbook/projdoc/Integrating-with-Windows.xml index 9f0de0a56a..4408595763 100644 --- a/docs/docbook/projdoc/Integrating-with-Windows.xml +++ b/docs/docbook/projdoc/Integrating-with-Windows.xml @@ -24,6 +24,26 @@ NetBIOS over TCP/IP then this section may help you to resolve networking problem </para> </note> +<sect1> +<title>Features and Benefits</title> + +<para> +Many MS Windows network administrators have never been exposed to basic TCP/IP +networking as it is implemented in a Unix/Linux operating system. Likewise, many Unix and +Linux adminsitrators have not been exposed to the intricacies of MS Windows TCP/IP based +networking (and may have no desire to be either). +</para> + +<para> +This chapter gives a short introduction to the basics of how a name can be resolved to +it's IP address for each operating system environment. +</para> + +</sect1> + +<sect1> +<title>Background Information</title> + <para> Since the introduction of MS Windows 2000 it is possible to run MS Windows networking without the use of NetBIOS over TCP/IP. NetBIOS over TCP/IP uses UDP port 137 for NetBIOS @@ -48,6 +68,7 @@ Use of DHCP with ADS is recommended as a further means of maintaining central co over client workstation network configuration. </para> +</sect1> <sect1> <title>Name Resolution in a pure Unix/Linux world</title> @@ -70,10 +91,10 @@ The key configuration files covered in this section are: Contains a static list of IP Addresses and names. eg: </para> -<para><programlisting> +<para><screen> 127.0.0.1 localhost localhost.localdomain 192.168.1.1 bigbox.caldera.com bigbox alias4box -</programlisting></para> +</screen></para> <para> The purpose of <filename>/etc/hosts</filename> is to provide a @@ -87,7 +108,7 @@ Network packets that are sent over the physical network transport layer communicate not via IP addresses but rather using the Media Access Control address, or MAC address. IP Addresses are currently 32 bits in length and are typically presented as four (4) decimal -numbers that are separated by a dot (or period). eg: 168.192.1.1 +numbers that are separated by a dot (or period). eg: 168.192.1.1. </para> <para> @@ -97,7 +118,7 @@ as two digit hexadecimal numbers separated by colons. eg: </para> <para> -Every network interfrace must have an MAC address. Associated with +Every network interface must have an MAC address. Associated with a MAC address there may be one or more IP addresses. There is NO relationship between an IP address and a MAC address, all such assignments are arbitary or discretionary in nature. At the most basic level all @@ -181,10 +202,10 @@ critical configuration file. This file controls the order by which name resolution may procede. The typical structure is: </para> -<para><programlisting> +<para><screen> order hosts,bind multi on -</programlisting></para> +</screen></para> <para> then both addresses should be returned. Please refer to the @@ -205,7 +226,7 @@ file typically has resolver object specifications as follows: </para> -<para><programlisting> +<para><screen> # /etc/nsswitch.conf # # Name Service Switch configuration file. @@ -226,7 +247,7 @@ file typically has resolver object specifications as follows: protocols: nis files rpc: nis files services: nis files -</programlisting></para> +</screen></para> <para> Of course, each of these mechanisms requires that the appropriate @@ -244,8 +265,8 @@ Starting with version 2.2.0 samba has Linux support for extensions to the name service switch infrastructure so that linux clients will be able to obtain resolution of MS Windows NetBIOS names to IP Addresses. To gain this functionality Samba needs to be compiled -with appropriate arguments to the make command (ie: <command>make -nsswitch/libnss_wins.so</command>). The resulting library should +with appropriate arguments to the make command (ie: <userinput>make +nsswitch/libnss_wins.so</userinput>). The resulting library should then be installed in the <filename>/lib</filename> directory and the "wins" parameter needs to be added to the "hosts:" line in the <filename>/etc/nsswitch.conf</filename> file. At this point it @@ -280,7 +301,7 @@ the client/server. The following are typical NetBIOS name/service type registrations: </para> -<para><programlisting> +<para><screen> Unique NetBIOS Names: MACHINENAME<00> = Server Service is running on MACHINENAME MACHINENAME<03> = Generic Machine Name (NetBIOS name) @@ -292,7 +313,7 @@ The following are typical NetBIOS name/service type registrations: WORKGROUP<1c> = Domain Controllers / Netlogon Servers WORKGROUP<1d> = Local Master Browsers WORKGROUP<1e> = Internet Name Resolvers -</programlisting></para> +</screen></para> <para> It should be noted that all NetBIOS machines register their own @@ -372,7 +393,7 @@ frustrating for users - but it is a characteristic of the protocol. <para> The MS Windows utility that allows examination of the NetBIOS name cache is called "nbtstat". The Samba equivalent of this -is called "nmblookup". +is called <command>nmblookup</command>. </para> </sect2> @@ -392,7 +413,7 @@ to IP address mapping. It typically looks like: </para> -<para><programlisting> +<para><screen> # Copyright (c) 1998 Microsoft Corp. # # This is a sample LMHOSTS file used by the Microsoft Wins Client (NetBIOS @@ -469,7 +490,7 @@ It typically looks like: # so keeping the number of comments to a minimum will improve performance. # Therefore it is not advisable to simply add lmhosts file entries onto the # end of this file. -</programlisting></para> +</screen></para> </sect2> @@ -520,19 +541,19 @@ To configure Samba to be a WINS server the following parameter needs to be added to the &smb.conf; file: </para> -<para><programlisting> +<para><screen> wins support = Yes -</programlisting></para> +</screen></para> <para> To configure Samba to use a WINS server the following parameters are needed in the &smb.conf; file: </para> -<para><programlisting> +<para><screen> wins support = No wins server = xxx.xxx.xxx.xxx -</programlisting></para> +</screen></para> <para> where <replaceable>xxx.xxx.xxx.xxx</replaceable> is the IP address @@ -542,4 +563,114 @@ of the WINS server. </sect2> </sect1> +<sect1> +<title>Common Errors</title> + +<para> +TCP/IP network configuration problems find every network administrator sooner or later. +The cause can be anything from keybaord mishaps, forgetfulness, simple mistakes, and +carelessness. Of course, noone is every deliberately careless! +</para> + + <sect2> + <title>My Boomerang Won't Come Back</title> + + <para> + Well, the real complaint said, "I can ping my samba server from Windows, but I can + not ping my Windows machine from the samba server." + </para> + + <para> + The Windows machine was at IP Address 192.168.1.2 with netmask 255.255.255.0, the + Samba server (Linux) was at IP Address 192.168.1.130 with netmast 255.255.255.128. + The machines were on a local network with no external connections. + </para> + + <para> + Due to inconsistent netmasks, the Windows machine was on network 192.168.1.0/24, while + the Samba server was on network 192.168.1.128/25 - logically a different network. + </para> + + </sect2> + + <sect2> + <title>Very Slow Network Connections</title> + + <para> + A common causes of slow network response includes: + </para> + + <itemizedlist> + <listitem><para>Client is configured to use DNS and DNS server is down</para></listitem> + <listitem><para>Client is configured to use remote DNS server, but remote connection is down</para></listitem> + <listitem><para>Client is configured to use a WINS server, but there is no WINS server</para></listitem> + <listitem><para>Client is NOT configured to use a WINS server, but there is a WINS server</para></listitem> + <listitem><para>Firewall is filtering our DNS or WINS traffic</para></listitem> + </itemizedlist> + + </sect2> + + <sect2> + <title>Samba server name change problem</title> + + <para> + The name of the samba server was changed, samba was restarted, samba server can not be + pinged by new name from MS Windows NT4 Workstation, but it does still respond to ping using + the old name. Why? + </para> + + <para> + From this description three (3) things are rather obvious: + </para> + + <itemizedlist> + <listitem><para>WINS is NOT in use, only broadcast based name resolution is used</para></listitem> + <listitem><para>The samba server was renamed and restarted within the last 10-15 minutes</para></listitem> + <listitem><para>The old samba server name is still in the NetBIOS name cache on the MS Windows NT4 Workstation</para></listitem> + </itemizedlist> + + <para> + To find what names are present in the NetBIOS name cache on the MS Windows NT4 machine, + open a cmd shell, then: + </para> + + <para> + <screen> + C:\temp\>nbtstat -n + + NetBIOS Local Name Table + + Name Type Status + ------------------------------------------------ + SLACK <03> UNIQUE Registered + ADMININSTRATOR <03> UNIQUE Registered + SLACK <00> UNIQUE Registered + SARDON <00> GROUP Registered + SLACK <20> UNIQUE Registered + SLACK <1F> UNIQUE Registered + + + C:\Temp\>nbtstat -c + + NetBIOS Remote Cache Name Table + + Name Type Host Address Life [sec] + -------------------------------------------------------------- + FRODO <20> UNIQUE 192.168.1.1 240 + + C:\Temp\> + </screen> + </para> + + <para> + In the above example, FRODO is the Samba server and SLACK is the MS Windows NT4 Workstation. + The first listing shows the contents of the Local Name Table (ie: Identity information on + the MS Windows workstation), the second shows the NetBIOS name in the NetBIOS name cache. + The name cache contains the remote machines known to this workstation. + </para> + + </sect2> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/InterdomainTrusts.xml b/docs/docbook/projdoc/InterdomainTrusts.xml index 2c492d4ac0..9fe108e4ee 100644 --- a/docs/docbook/projdoc/InterdomainTrusts.xml +++ b/docs/docbook/projdoc/InterdomainTrusts.xml @@ -16,6 +16,25 @@ possible for Samba-3 to NT4 trust (and vice versa), as well as Samba3 to Samba3 </para> <sect1> +<title>Features and Benefits</title> + +<para> +Samba-3 can participate in Samba-to-Samba as well as in Samba-to-MS Windows NT4 style +trust relationships. This imparts to Samba similar scalability as is possible with +MS Windows NT4. +</para> + +<para> +Given that Samba-3 has the capability to function with a scalable backend authentication +database such as LDAP, and given it's ability to run in Primary as well as Backup Domain control +modes, the administrator would be well advised to consider alternatives to the use of +Interdomain trusts simplt because by the very nature of how this works it is fragile. +That was after all a key reason for the development and adoption of Microsoft Active Directory. +</para> + +</sect1> + +<sect1> <title>Trust Relationship Background</title> <para> @@ -76,13 +95,15 @@ There are two steps to creating an interdomain trust relationship. <title>NT4 as the Trusting Domain (ie. creating the trusted account)</title> <para> -For MS Windows NT4, all domain trust relationships are configured using the Domain User Manager. -To affect a two way trust relationship it is necessary for each domain administrator to make -available (for use by an external domain) it's security resources. This is done from the Domain -User Manager Policies entry on the menu bar. From the Policy menu, select Trust Relationships, then -next to the lower box that is labelled "Permitted to Trust this Domain" are two buttons, "Add" and -"Remove". The "Add" button will open a panel in which needs to be entered the remote domain that -will be able to assign user rights to your domain. In addition it is necessary to enter a password +For MS Windows NT4, all domain trust relationships are configured using the +<application>Domain User Manager</application>. To affect a two way trust relationship it is +necessary for each domain administrator to make available (for use by an external domain) it's +security resources. This is done from the Domain User Manager Policies entry on the menu bar. +From the <guimenu>Policy</guimenu> menu, select <guimenuitem>Trust Relationships</guimenuitem>, then +next to the lower box that is labelled <guilabel>Permitted to Trust this Domain</guilabel> are two +buttons, <guibutton>Add</guibutton> and <guibutton>Remove</guibutton>. The <guibutton>Add</guibutton> +button will open a panel in which needs to be entered the remote domain that will be able to assign +user rights to your domain. In addition it is necessary to enter a password that is specific to this trust relationship. The password needs to be typed twice (for standard confirmation). </para> @@ -96,8 +117,9 @@ typed twice (for standard confirmation). A trust relationship will work only when the other (trusting) domain makes the appropriate connections with the trusted domain. To consumate the trust relationship the administrator will launch the Domain User Manager, from the menu select Policies, then select Trust Relationships, then click on the -"Add" button that is next to the box that is labelled "Trusted Domains". A panel will open in -which must be entered the name of the remote domain as well as the password assigned to that trust. +<guibutton>Add</guibutton> button that is next to the box that is labelled +<guilabel>Trusted Domains</guilabel>. A panel will open in which must be entered the name of the remote +domain as well as the password assigned to that trust. </para> </sect2> @@ -133,14 +155,14 @@ will be to issue this command from your favourite shell: <para> <screen> -<prompt>deity#</prompt> <userinput>smbpasswd -a -i rumba</userinput> +&rootprompt; <userinput>smbpasswd -a -i rumba</userinput> New SMB password: XXXXXXXX Retype SMB password: XXXXXXXX Added user rumba$ </screen> -where <parameter>-a</parameter> means to add a new account into the -passdb database and <parameter>-i</parameter> means: ''create this +where <option>-a</option> means to add a new account into the +passdb database and <option>-i</option> means: ''create this account with the InterDomain trust flag'' </para> @@ -159,12 +181,15 @@ the trust by establishing it from Windows NT Server. </para> <para> -Open 'User Manager for Domains' and from menu 'Policies' select 'Trust Relationships...'. -Right beside 'Trusted domains' list box press 'Add...' button. You will be prompted for +Open <application>User Manager for Domains</application> and from menu +<guimenu>Policies</guimenu> select <guimenuitem>Trust Relationships...</guimenuitem>. +Right beside <guilabel>Trusted domains</guilabel> list box press the +<guimenu>Add...</guimenu> button. You will be prompted for the trusted domain name and the relationship password. Type in SAMBA, as this is your domain name, and the password used at the time of account creation. -Press OK and, if everything went without incident, you will see 'Trusted domain relationship -successfully established' message. +Press OK and, if everything went without incident, you will see +<computeroutput>Trusted domain relationship successfully +established</computeroutput> message. </para> </sect2> @@ -181,9 +206,11 @@ The very first thing requirement is to add an account for the SAMBA domain on RU </para> <para> -Launch the Domain User Manager, then from the menu select 'Policies', 'Trust Relationships'. -Now, next to 'Trusted Domains' box press the 'Add' button, and type in the name of the trusted -domain (SAMBA) and password securing the relationship. +Launch the <application>Domain User Manager</application>, then from the menu select +<guimenu>Policies</guimenu>, <guimenuitem>Trust Relationships</guimenuitem>. +Now, next to <guilabel>Trusted Domains</guilabel> box press the <guibutton>Add</guibutton> +button, and type in the name of the trusted domain (SAMBA) and password securing +the relationship. </para> <para> @@ -197,7 +224,7 @@ Using your favourite shell while being logged in as root, issue this command: </para> <para> -<prompt>deity# </prompt><userinput>net rpc trustdom establish rumba</userinput> +&rootprompt;<userinput>net rpc trustdom establish rumba</userinput> </para> <para> @@ -207,8 +234,8 @@ Do not worry if you see an error message that mentions a returned code of password you gave is correct and the NT4 Server says the account is ready for interdomain connection and not for ordinary connection. After that, be patient it can take a while (especially -in large networks), you should see the 'Success' message. Congratulations! Your trust -relationship has just been established. +in large networks), you should see the <computeroutput>Success</computeroutput> message. +Congratulations! Your trust relationship has just been established. </para> <note><para> @@ -219,4 +246,48 @@ the <filename>secrets.tdb</filename> file. </sect2> </sect1> +<sect1> +<title>Common Errors</title> + +<para> +Interdomain trust relationships should NOT be attempted on networks that are unstable +or that suffer regular outages. Network stability and integrity are key concerns with +distributed trusted domains. +</para> + + <sect2> + <title>Tell me about Trust Relationships using Samba</title> + + <para> + Like many, I administer multiple LANs connected together using NT trust + relationships. This was implemented about 4 years ago. I now have the + occasion to consider performing this same task again, but this time, I + would like to implement it solely through samba - no Microsoft PDCs + anywhere. + </para> + + <para> + I have read documentation on samba.org regarding NT-style trust + relationships and am now wondering, can I do what I want to? I already + have successfully implemented 2 samba servers, but they are not PDCs. + They merely act as file servers. I seem to remember, and it appears to + be true (according to samba.org) that trust relationships are a + challenge. + </para> + + <para> + Please provide any helpful feedback that you may have. + </para> + + <para> + These are almost complete in Samba 3.0 snapshots. The main catch + is getting winbindd to be able to allocate uid/gid's for trusted + users/groups. See the updated Samba HOWTO collection for more + details. + </para> + + </sect2> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/IntroSMB.xml b/docs/docbook/projdoc/IntroSMB.xml index 38e40ae239..730c400ee1 100644 --- a/docs/docbook/projdoc/IntroSMB.xml +++ b/docs/docbook/projdoc/IntroSMB.xml @@ -6,10 +6,10 @@ <title>Introduction to Samba</title> -<para><emphasis> +<para><quote> "If you understand what you're doing, you're not learning anything." -- Anonymous -</emphasis></para> +</quote></para> <para> Samba is a file and print server for Windows-based clients using TCP/IP as the underlying @@ -132,7 +132,7 @@ thinking? </itemizedlist> <para>If you plan on getting help, make sure to subscribe to the Samba Mailing List (available at -http://www.samba.org). Optionally, you could just search mailing.unix.samba at http://groups.google.com +<ulink url="http://www.samba.org/">http://www.samba.org</ulink>). </para> </sect1> @@ -171,8 +171,9 @@ nothing to do with acting as a file and print server for SMB/CIFS clients. </para> <para> -There are other Open Source CIFS client implementations, such as the jCIFS project -(jcifs.samba.org) which provides an SMB client toolkit written in Java. +There are other Open Source CIFS client implementations, such as the +<ulink url="http://jcifs.samba.org/">jCIFS project</ulink> +which provides an SMB client toolkit written in Java. </para> @@ -226,9 +227,9 @@ up a single file. In general, SMB sessions are established in the following orde </itemizedlist> <para> -A good way to examine this process in depth is to try out SecurityFriday's SWB program -at http://www.securityfriday.com/ToolDownload/SWB/swb_doc.html. It allows you to -walk through the establishment of a SMB/CIFS session step by step. +A good way to examine this process in depth is to try out +<ulink url="http://www.securityfriday.com/ToolDownload/SWB/swb_doc.html">SecurityFriday's SWB program</ulink>. +It allows you to walk through the establishment of a SMB/CIFS session step by step. </para> </sect1> @@ -236,8 +237,8 @@ walk through the establishment of a SMB/CIFS session step by step. <sect1> <title>Epilogue</title> -<para><emphasis> -"What's fundamentally wrong is that nobody ever had any taste when they +<para><quote> +What's fundamentally wrong is that nobody ever had any taste when they did it. Microsoft has been very much into making the user interface look good, but internally it's just a complete mess. And even people who program for Microsoft and who have had years of experience, just don't know how it works internally. @@ -246,16 +247,16 @@ mess that fixing one bug might just break a hundred programs that depend on that bug. And Microsoft isn't interested in anyone fixing bugs -- they're interested in making money. They don't have anybody who takes pride in Windows 95 as an operating system. -</emphasis></para> +</quote></para> -<para><emphasis> +<para><quote> People inside Microsoft know it's a bad operating system and they still continue obviously working on it because they want to get the next version out because they want to have all these new features to sell more copies of the system. -</emphasis></para> +</quote></para> -<para><emphasis> +<para><quote> The problem with that is that over time, when you have this kind of approach, and because nobody understands it, because nobody REALLY fixes bugs (other than when they're really obvious), the end result is really messy. You can't trust @@ -265,11 +266,11 @@ fine and then once in a blue moon for some completely unknown reason, it's dead, and nobody knows why. Not Microsoft, not the experienced user and certainly not the completely clueless user who probably sits there shivering thinking "What did I do wrong?" when they didn't do anything wrong at all. -</emphasis></para> +</quote></para> -<para><emphasis> +<para><quote> That's what's really irritating to me." -</emphasis></para> +</quote></para> <para>-- <ulink url="http://hr.uoregon.edu/davidrl/boot.txt">Linus Torvalds, from an interview with BOOT Magazine, Sept 1998</ulink> @@ -280,15 +281,10 @@ That's what's really irritating to me." <sect1> <title>Miscellaneous</title> -<para> -This chapter was lovingly handcrafted on a Dell Latitude C400 laptop running Slackware Linux 9.0, -in case anyone asks. -</para> - -<!-- This really needs to go... --> +<!--FIXME: This really needs to go... --> <para> -This chapter is Copyright © 2003 David Lechnyr (david at lechnyr dot com). +This chapter is Copyright 2003 David Lechnyr (david at lechnyr dot com). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation. A copy of the license is available at http://www.gnu.org/licenses/fdl.txt. diff --git a/docs/docbook/projdoc/NT4Migration.xml b/docs/docbook/projdoc/NT4Migration.xml index 585cfe6a47..fb136760fa 100644 --- a/docs/docbook/projdoc/NT4Migration.xml +++ b/docs/docbook/projdoc/NT4Migration.xml @@ -44,26 +44,14 @@ should know precisely <emphasis>why</emphasis> the change is important for the o Possible motivations to make a change include: </para> -<itemizedlist> -<listitem> - <para>Improve network manageability</para> -</listitem> -<listitem> - <para>Obtain better user level functionality</para> -</listitem> -<listitem> - <para>Reduce network operating costs</para> -</listitem> -<listitem> - <para>Reduce exposure caused by Microsoft withdrawal of NT4 support</para> -</listitem> -<listitem> - <para>Avoid MS License 6 implications</para> -</listitem> -<listitem> - <para>Reduce organisation's dependency on Microsoft</para> -</listitem> -</itemizedlist> +<simplelist> + <member>Improve network manageability</member> + <member>Obtain better user level functionality</member> + <member>Reduce network operating costs</member> + <member>Reduce exposure caused by Microsoft withdrawal of NT4 support</member> + <member>Avoid MS License 6 implications</member> + <member>Reduce organisation's dependency on Microsoft</member> +</simplelist> <para> It is vital that it be well recognised that Samba-3 is NOT MS Windows NT4. Samba-3 offers @@ -77,61 +65,31 @@ MS Windows 2000 and beyond (with or without Active Directory services). What are the features that Samba-3 can NOT provide? </para> -<itemizedlist> -<listitem> - <para>Active Directory Server</para> -</listitem> -<listitem> - <para>Group Policy Objects (in Active Direcrtory)</para> -</listitem> -<listitem> - <para>Machine Policy objects</para> -</listitem> -<listitem> - <para>Logon Scripts in Active Directorty</para> -</listitem> -<listitem> - <para>Software Application and Access Controls in Active Directory</para> -</listitem> -</itemizedlist> +<simplelist> + <member>Active Directory Server</member> + <member>Group Policy Objects (in Active Direcrtory)</member> + <member>Machine Policy objects</member> + <member>Logon Scripts in Active Directorty</member> + <member>Software Application and Access Controls in Active Directory</member> +</simplelist> <para> The features that Samba-3 DOES provide and that may be of compelling interest to your site includes: </para> -<itemizedlist> -<listitem> - <para>Lower Cost of Ownership</para> -</listitem> -<listitem> - <para>Global availability of support with no strings attached</para> -</listitem> -<listitem> - <para>Dynamic SMB Servers (ie:Can run more than one server per Unix/Linux system)</para> -</listitem> -<listitem> - <para>Creation of on-the-fly logon scripts</para> -</listitem> -<listitem> - <para>Creation of on-the-fly Policy Files</para> -</listitem> -<listitem> - <para>Greater Stability, Reliability, Performance and Availability</para> -</listitem> -<listitem> - <para>Manageability via an ssh connection</para> -</listitem> -<listitem> - <para>Flexible choices of back-end authentication technologies (tdbsam, ldapsam, mysqlsam)</para> -</listitem> -<listitem> - <para>Ability to implement a full single-signon architecture</para> -</listitem> -<listitem> - <para>Ability to distribute authentication systems for absolute minimum wide area network bandwidth demand</para> -</listitem> -</itemizedlist> +<simplelist> + <member>Lower Cost of Ownership</member> + <member>Global availability of support with no strings attached</member> + <member>Dynamic SMB Servers (ie:Can run more than one server per Unix/Linux system)</member> + <member>Creation of on-the-fly logon scripts</member> + <member>Creation of on-the-fly Policy Files</member> + <member>Greater Stability, Reliability, Performance and Availability</member> + <member>Manageability via an ssh connection</member> + <member>Flexible choices of back-end authentication technologies (tdbsam, ldapsam, mysqlsam)</member> + <member>Ability to implement a full single-signon architecture</member> + <member>Ability to distribute authentication systems for absolute minimum wide area network bandwidth demand</member> +</simplelist> <para> Before migrating a network from MS Windows NT4 to Samba-3 it is vital that all necessary factors are @@ -221,11 +179,11 @@ all users gain share and printer connections they need. Logon scripts can be created on-the-fly so that all commands executed are specific to the rights and privilidges granted to the user. The preferred controls should be affected through group membership so that group information can be used to custom create a logong script using -the <filename>root preexec</filename> parameters to the <filename>NETLOGON</filename> share. +the <parameter>root preexec</parameter> parameters to the <filename>NETLOGON</filename> share. </para> <para> -Some sites prefer to use a tool such as <filename>kixstart</filename> to establish a controlled +Some sites prefer to use a tool such as <command>kixstart</command> to establish a controlled user environment. In any case you may wish to do a google search for logon script process controls. In particular, you may wish to explore the use of the Microsoft knowledgebase article KB189105 that deals with how to add printers without user intervention via the logon script process. @@ -241,7 +199,7 @@ Management. </para> <para> -Profiles may also be managed using the Samba-3 tool <filename>profiles</filename>. This tool allows +Profiles may also be managed using the Samba-3 tool <command>profiles</command>. This tool allows the MS Windows NT style security identifiers (SIDs) that are stored inside the profile NTuser.DAT file to be changed to the SID of the Samba-3 domain. </para> @@ -283,39 +241,39 @@ Samba-3 set up as a DC with netlogon share, profile share, etc. <substeps><step><para>Samba must NOT be running</para></step></substeps></step> <step> - <para>rpcclient NT4PDC -U Administrator%passwd</para> + <para><userinput>rpcclient <replaceable>NT4PDC</replaceable> -U Administrator%<replaceable>passwd</replaceable></userinput></para> <substeps><step><para>lsaquery</para></step> <step><para>Note the SID returned</para></step> </substeps> </step> - <step><para>net getsid -S NT4PDC -w DOMNAME -U Administrator%passwd</para> + <step><para><userinput>net getsid -S <replaceable>NT4PDC</replaceable> -w <replaceable>DOMNAME</replaceable> -U Administrator%<replaceable>passwd</replaceable></userinput></para> <substeps><step><para>Note the SID</para></step></substeps> </step> - <step><para>net getlocalsid</para> + <step><para><userinput>net getlocalsid</userinput></para> <substeps> <step><para>Note the SID, now check that all three SIDS reported are the same!</para></step> </substeps> </step> - <step><para>net rpc join -S NT4PDC -w DOMNAME -U Administrator%passwd</para></step> + <step><para><userinput>net rpc join -S <replaceable>NT4PDC</replaceable> -w <replaceable>DOMNAME</replaceable> -U Administrator%<replaceable>passwd</replaceable></userinput></para></step> - <step><para>net rpc vampire -S NT4PDC -U administrator%passwd</para></step> + <step><para><userinput>net rpc vampire -S <replaceable>NT4PDC</replaceable> -U administrator%<replaceable>passwd</replaceable></userinput></para></step> - <step><para>pdbedit -l</para> + <step><para><userinput>pdbedit -L</userinput></para> <substeps><step><para>Note - did the users migrate?</para></step></substeps> </step> - <step><para>initGrps.sh DOMNAME</para></step> + <step><para><userinput>initGrps.sh <replaceable>DOMNAME</replaceable></userinput></para></step> - <step><para>net groupmap list</para> + <step><para><userinput>net groupmap list</userinput></para> <substeps><step><para>Now check that all groups are recognised</para></step></substeps> </step> - <step><para>net rpc campire -S NT4PDC -U administrator%passwd</para></step> + <step><para><userinput>net rpc campire -S <replaceable>NT4PDC</replaceable> -U administrator%<replaceable>passwd</replaceable></userinput></para></step> - <step><para>pdbedit -lv</para> + <step><para><userinput>pdbedit -Lv</userinput></para> <substeps><step> <para>Note - check that all group membership has been migrated</para> </step></substeps> @@ -440,6 +398,7 @@ No matter what choice you make, the following rules will minimise down-stream pr <sect2> <title>Samba Implementation Choices</title> +<!-- FIXME: Either a better layout or more written-out text--> <para><programlisting> Authentication database back end Winbind (external Samba or NT4/200x server) diff --git a/docs/docbook/projdoc/NetworkBrowsing.xml b/docs/docbook/projdoc/NetworkBrowsing.xml index 8648bfa256..971963579b 100644 --- a/docs/docbook/projdoc/NetworkBrowsing.xml +++ b/docs/docbook/projdoc/NetworkBrowsing.xml @@ -103,6 +103,7 @@ called <filename>nmbd</filename>. The configuration parameters involved in nmbd' </para> <para><programlisting> + <!--FIXME--> Browsing options: ----------------- * os level @@ -426,7 +427,8 @@ cross subnet browsing possible for a workgroup. In an WORKGROUP environment the domain master browser must be a Samba server, and there must only be one domain master browser per workgroup name. To set up a Samba server as a domain master browser, -set the following option in the [global] section of the &smb.conf; file : +set the following option in the <parameter>[global]</parameter> section +of the &smb.conf; file : </para> <para> @@ -438,7 +440,7 @@ set the following option in the [global] section of the &smb.conf; file : <para> The domain master browser should also preferrably be the local master browser for its own subnet. In order to achieve this set the following -options in the [global] section of the &smb.conf; file : +options in the <parameter>[global]</parameter> section of the &smb.conf; file : </para> <para> @@ -462,7 +464,7 @@ workgroup. Any MS Windows NT/2K/XP/2003 machine should be able to do this, as will Windows 9x machines (although these tend to get rebooted more often, so it's not such a good idea to use these). To make a Samba server a local master browser -set the following options in the [global] section of the +set the following options in the <parameter>[global]</parameter> section of the &smb.conf; file : </para> @@ -482,9 +484,9 @@ master browser. </para> <para> -The <command>local master</command> parameter allows Samba to act as a -local master browser. The <command>preferred master</command> causes nmbd -to force a browser election on startup and the <command>os level</command> +The <parameter>local master</parameter> parameter allows Samba to act as a +local master browser. The <parameter>preferred master</parameter> causes nmbd +to force a browser election on startup and the <parameter>os level</parameter> parameter sets Samba high enough so that it should win any browser elections. </para> @@ -492,7 +494,7 @@ parameter sets Samba high enough so that it should win any browser elections. If you have an NT machine on the subnet that you wish to be the local master browser then you can disable Samba from becoming a local master browser by setting the following -options in the <command>[global]</command> section of the +options in the <parameter>[global]</parameter> section of the &smb.conf; file : </para> @@ -539,7 +541,7 @@ of the &smb.conf; file : <para> If you wish to have a Samba server fight the election with machines -on the same subnet you may set the <command>os level</command> parameter +on the same subnet you may set the <parameter>os level</parameter> parameter to lower levels. By doing this you can tune the order of machines that will become local master browsers if they are running. For more details on this see the section <link linkend="browse-force-master"> @@ -552,7 +554,7 @@ If you have Windows NT machines that are members of the domain on all subnets, and you are sure they will always be running then you can disable Samba from taking part in browser elections and ever becoming a local master browser by setting following options -in the <command>[global]</command> section of the &smb.conf; +in the <parameter>[global]</parameter> section of the &smb.conf; file : </para> @@ -571,7 +573,7 @@ file : <title>Forcing samba to be the master</title> <para> -Who becomes the <command>master browser</command> is determined by an election +Who becomes the <parameter>master browser</parameter> is determined by an election process using broadcasts. Each election packet contains a number of parameters which determine what precedence (bias) a host should have in the election. By default Samba uses a very low precedence and thus loses @@ -579,14 +581,14 @@ elections to just about anyone else. </para> <para> -If you want Samba to win elections then just set the <command>os level</command> global +If you want Samba to win elections then just set the <parameter>os level</parameter> global option in &smb.conf; to a higher number. It defaults to 0. Using 34 would make it win all elections over every other system (except other samba systems!) </para> <para> -A <command>os level</command> of 2 would make it beat WfWg and Win95, but not MS Windows +A <parameter>os level</parameter> of 2 would make it beat WfWg and Win95, but not MS Windows NT/2K Server. A MS Windows NT/2K Server domain controller uses level 32. </para> @@ -594,18 +596,18 @@ NT/2K Server. A MS Windows NT/2K Server domain controller uses level 32. <para> If you want samba to force an election on startup, then set the -<command>preferred master</command> global option in &smb.conf; to "yes". Samba will +<parameter>preferred master</parameter> global option in &smb.conf; to <constant>yes</constant>. Samba will then have a slight advantage over other potential master browsers that are not preferred master browsers. Use this parameter with care, as if you have two hosts (whether they are windows 95 or NT or -samba) on the same local subnet both set with <command>preferred master</command> to -"yes", then periodically and continually they will force an election +samba) on the same local subnet both set with <parameter>preferred master</parameter> to +<constant>yes</constant>, then periodically and continually they will force an election in order to become the local master browser. </para> <para> -If you want samba to be a <command>domain master browser</command>, then it is -recommended that you also set <command>preferred master</command> to "yes", because + If you want samba to be a <parameter>domain master browser</parameter>, then it is +recommended that you also set <parameter>preferred master</parameter> to <constant>yes</constant>, because samba will not become a domain master browser for the whole of your LAN or WAN if it is not also a local master browser on its own broadcast isolated subnet. @@ -629,12 +631,12 @@ the current domain master browser fail. <para> The domain master is responsible for collating the browse lists of multiple subnets so that browsing can occur between subnets. You can -make samba act as the domain master by setting <command>domain master = yes</command> +make samba act as the domain master by setting <parameter>domain master = yes</parameter> in &smb.conf;. By default it will not be a domain master. </para> <para> -Note that you should NOT set Samba to be the domain master for a +Note that you should <strong>not</strong> set Samba to be the domain master for a workgroup that has the same name as an NT Domain. </para> @@ -647,8 +649,8 @@ browse lists. <para> If you want samba to be the domain master then I suggest you also set -the <command>os level</command> high enough to make sure it wins elections, and set -<command>preferred master</command> to "yes", to get samba to force an election on +the <parameter>os level</parameter> high enough to make sure it wins elections, and set +<parameter>preferred master</parameter> to <constant>yes</constant>, to get samba to force an election on startup. </para> @@ -723,12 +725,12 @@ option in &smb.conf; to configure them. </para> </sect2> <sect2> -<title>Use of the <command>Remote Announce</command> parameter</title> +<title>Use of the Remote Announce parameter</title> <para> -The <command>remote announce</command> parameter of +The <parameter>remote announce</parameter> parameter of <filename>smb.conf</filename> can be used to forcibly ensure that all the NetBIOS names on a network get announced to a remote network. -The syntax of the <command>remote announce</command> parameter is: +The syntax of the <parameter>remote announce</parameter> parameter is: <programlisting> remote announce = a.b.c.d [e.f.g.h] ... </programlisting> @@ -769,10 +771,10 @@ name resolution problems and should be avoided. </sect2> <sect2> -<title>Use of the <command>Remote Browse Sync</command> parameter</title> +<title>Use of the Remote Browse Sync parameter</title> <para> -The <command>remote browse sync</command> parameter of +The <parameter>remote browse sync</parameter> parameter of <filename>smb.conf</filename> is used to announce to another LMB that it must synchronise it's NetBIOS name list with our Samba LMB. It works ONLY if the Samba server that has this option is @@ -780,7 +782,7 @@ simultaneously the LMB on it's network segment. </para> <para> -The syntax of the <command>remote browse sync</command> parameter is: +The syntax of the <parameter>remote browse sync</parameter> parameter is: <programlisting> remote browse sync = <replaceable>a.b.c.d</replaceable> @@ -848,18 +850,18 @@ errors. <para> To configure Samba as a WINS server just add -<command>wins support = yes</command> to the <filename>smb.conf</filename> +<parameter>wins support = yes</parameter> to the <filename>smb.conf</filename> file [globals] section. </para> <para> To configure Samba to register with a WINS server just add -"wins server = a.b.c.d" to your smb.conf file [globals] section. +<parameter>wins server = a.b.c.d</parameter> to your &smb.conf; file <parameter>[globals]</parameter> section. </para> <important><para> -Never use both <command>wins support = yes</command> together -with <command>wins server = a.b.c.d</command> +Never use both <parameter>wins support = yes</parameter> together +with <parameter>wins server = a.b.c.d</parameter> particularly not using it's own IP address. Specifying both will cause &nmbd; to refuse to start! </para></important> @@ -871,7 +873,7 @@ Specifying both will cause &nmbd; to refuse to start! Either a Samba machine or a Windows NT Server machine may be set up as a WINS server. To set a Samba machine to be a WINS server you must add the following option to the &smb.conf; file on the selected machine : -in the [globals] section add the line +in the <parameter>[globals]</parameter> section add the line </para> <para> @@ -888,13 +890,13 @@ least set the parameter to 'no' on all these machines. </para> <para> -Machines with <command>wins support = yes</command> will keep a list of +Machines with <parameter>wins support = yes</parameter> will keep a list of all NetBIOS names registered with them, acting as a DNS for NetBIOS names. </para> <para> You should set up only ONE wins server. Do NOT set the -<command>wins support = yes</command> option on more than one Samba +<parameter>wins support = yes</parameter> option on more than one Samba server. </para> @@ -908,17 +910,17 @@ participate in these replications. It is possible in the future that a Samba->Samba WINS replication protocol may be defined, in which case more than one Samba machine could be set up as a WINS server but currently only one Samba server should have the -<command>wins support = yes</command> parameter set. +<parameter>wins support = yes</parameter> parameter set. </para> <para> After the WINS server has been configured you must ensure that all machines participating on the network are configured with the address of this WINS server. If your WINS server is a Samba machine, fill in -the Samba machine IP address in the "Primary WINS Server" field of -the "Control Panel->Network->Protocols->TCP->WINS Server" dialogs +the Samba machine IP address in the <guilabel>Primary WINS Server</guilabel> field of +the <guilabel>Control Panel->Network->Protocols->TCP->WINS Server</guilabel> dialogs in Windows 95 or Windows NT. To tell a Samba server the IP address -of the WINS server add the following line to the [global] section of +of the WINS server add the following line to the <parameter>[global]</parameter> section of all &smb.conf; files : </para> @@ -936,8 +938,8 @@ machine or its IP address. <para> Note that this line MUST NOT BE SET in the &smb.conf; file of the Samba server acting as the WINS server itself. If you set both the -<command>wins support = yes</command> option and the -<command>wins server = <name></command> option then +<parameter>wins support = yes</parameter> option and the +<parameter>wins server = <name></parameter> option then nmbd will fail to start. </para> @@ -966,7 +968,7 @@ section of the documentation to provide usage and technical details. <title>Static WINS Entries</title> <para> -New to Samba-3 is a tool called <filename>winsedit</filename> that may be used to add +New to Samba-3 is a tool called <command>winsedit</command> that may be used to add static WINS entries to the WINS database. This tool can be used also to modify entries existing in the WINS database. </para> @@ -1051,7 +1053,7 @@ are:</para> <para> Alternative means of name resolution includes:</para> <simplelist> -<member>/etc/hosts: is static, hard to maintain, and lacks name_type info</member> +<member><filename>/etc/hosts</filename>: is static, hard to maintain, and lacks name_type info</member> <member>DNS: is a good choice but lacks essential name_type info.</member> </simplelist> @@ -1082,7 +1084,7 @@ controlled by <filename>/etc/host.conf</filename>, <filename>/etc/nsswitch.conf< <para> SMB networking provides a mechanism by which clients can access a list -of machines in a network, a so-called <command>browse list</command>. This list +of machines in a network, a so-called <parameter>browse list</parameter>. This list contains machines that are ready to offer file and/or print services to other machines within the network. Thus it does not include machines which aren't currently able to do server tasks. The browse @@ -1144,7 +1146,7 @@ recommended that you use one and only one Samba server as your WINS server. <para> To get browsing to work you need to run nmbd as usual, but will need -to use the <command>workgroup</command> option in &smb.conf; +to use the <parameter>workgroup</parameter> option in &smb.conf; to control what workgroup Samba becomes a part of. </para> @@ -1152,7 +1154,7 @@ to control what workgroup Samba becomes a part of. Samba also has a useful option for a Samba server to offer itself for browsing on another subnet. It is recommended that this option is only used for 'unusual' purposes: announcements over the internet, for -example. See <command>remote announce</command> in the +example. See <parameter>remote announce</parameter> in the &smb.conf; man page. </para> </sect2> @@ -1175,7 +1177,7 @@ hit enter and filemanager should display the list of available shares. <para> Some people find browsing fails because they don't have the global -<command>guest account</command> set to a valid account. Remember that the +<parameter>guest account</parameter> set to a valid account. Remember that the IPC$ connection that lists the shares is done as guest, and thus you must have a valid guest account. </para> @@ -1242,6 +1244,7 @@ Consider a network set up as follows : </para> <para> + <!-- FIXME: Convert this to diagram --> <programlisting> (DMB) N1_A N1_B N1_C N1_D N1_E @@ -1312,15 +1315,20 @@ you looked in it on a particular network right now). </para> <para> -<programlisting> -Subnet Browse Master List ------- ------------- ---- -Subnet1 N1_C N1_A, N1_B, N1_C, N1_D, N1_E +<table frame="all"> + <title>Browse subnet example 1</title> + <tgroup align="left" cols="3"> + <thead> + <row><entry>Subnet</entry><entry>Browse Master</entry><entry>List</entry></row> + </thead> -Subnet2 N2_B N2_A, N2_B, N2_C, N2_D - -Subnet3 N3_D N3_A, N3_B, N3_C, N3_D -</programlisting> + <tbody> + <row><entry>Subnet1</entry><entry>N1_C</entry><entry>N1_A, N1_B, N1_C, N1_D, N1_E</entry></row> + <row><entry>Subnet2</entry><entry>N2_B</entry><entry>N2_A, N2_B, N2_C, N2_D</entry></row> + <row><entry>Subnet3</entry><entry>N3_D</entry><entry>N3_A, N3_B, N3_C, N3_D</entry></row> + </tbody> + </tgroup> +</table> </para> <para> @@ -1350,19 +1358,22 @@ are done the browse lists look like : </para> <para> -<programlisting> -Subnet Browse Master List ------- ------------- ---- -Subnet1 N1_C N1_A, N1_B, N1_C, N1_D, N1_E, - N2_A(*), N2_B(*), N2_C(*), N2_D(*) +<table frame="all"> + <title>Browse subnet example 2</title> + <tgroup align="left" cols="3"> + <thead> + <row><entry>Subnet</entry><entry>Browse Master</entry><entry>List</entry></row> + </thead> -Subnet2 N2_B N2_A, N2_B, N2_C, N2_D - N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*) - -Subnet3 N3_D N3_A, N3_B, N3_C, N3_D + <tbody> + <row><entry>Subnet1</entry><entry>N1_C</entry><entry>N1_A, N1_B, N1_C, N1_D, N1_E, N2_A(*), N2_B(*), N2_C(*), N2_D(*)</entry></row> + <row><entry>Subnet2</entry><entry>N2_B</entry><entry>N2_A, N2_B, N2_C, N2_D, N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)</entry></row> + <row><entry>Subnet3</entry><entry>N3_D</entry><entry>N3_A, N3_B, N3_C, N3_D</entry></row> + </tbody> + </tgroup> +</table> Servers with a (*) after them are non-authoritative names. -</programlisting> </para> <para> @@ -1381,22 +1392,22 @@ the browse lists look like. </para> <para> -<programlisting> -Subnet Browse Master List ------- ------------- ---- -Subnet1 N1_C N1_A, N1_B, N1_C, N1_D, N1_E, - N2_A(*), N2_B(*), N2_C(*), N2_D(*), - N3_A(*), N3_B(*), N3_C(*), N3_D(*) +<table frame="all"> + <title>Browse subnet example 3</title> + <tgroup cols="3" align="left"> + <thead> + <row><entry>Subnet</entry><entry>Browse Master</entry><entry>List</entry></row> + </thead> -Subnet2 N2_B N2_A, N2_B, N2_C, N2_D - N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*) - -Subnet3 N3_D N3_A, N3_B, N3_C, N3_D - N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*), - N2_A(*), N2_B(*), N2_C(*), N2_D(*) + <tbody> + <row><entry>Subnet1</entry><entry>N1_C</entry><entry>N1_A, N1_B, N1_C, N1_D, N1_E, N2_A(*), N2_B(*), N2_C(*), N2_D(*), N3_A(*), N3_B(*), N3_C(*), N3_D(*)</entry></row> + <row><entry>Subnet2</entry><entry>N2_B</entry><entry>N2_A, N2_B, N2_C, N2_D, N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)</entry></row> + <row><entry>Subnet3</entry><entry>N3_D</entry><entry>N3_A, N3_B, N3_C, N3_D, N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*), N2_A(*), N2_B(*), N2_C(*), N2_D(*)</entry></row> + </tbody> + </tgroup> +</table> Servers with a (*) after them are non-authoritative names. -</programlisting> </para> <para> @@ -1413,23 +1424,22 @@ are removed or shut off) the browse lists will look like : </para> <para> -<programlisting> -Subnet Browse Master List ------- ------------- ---- -Subnet1 N1_C N1_A, N1_B, N1_C, N1_D, N1_E, - N2_A(*), N2_B(*), N2_C(*), N2_D(*), - N3_A(*), N3_B(*), N3_C(*), N3_D(*) - -Subnet2 N2_B N2_A, N2_B, N2_C, N2_D - N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*) - N3_A(*), N3_B(*), N3_C(*), N3_D(*) - -Subnet3 N3_D N3_A, N3_B, N3_C, N3_D - N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*), - N2_A(*), N2_B(*), N2_C(*), N2_D(*) +<table frame="all"> + <title>Browse subnet example 4</title> + <tgroup cols="3" align="left"> + <thead> + <row><entry>Subnet</entry><entry>Browse Master</entry><entry>List</entry></row> + </thead> + + <tbody> + <row><entry>Subnet1</entry><entry>N1_C</entry><entry>N1_A, N1_B, N1_C, N1_D, N1_E, N2_A(*), N2_B(*), N2_C(*), N2_D(*), N3_A(*), N3_B(*), N3_C(*), N3_D(*)</entry></row> + <row><entry>Subnet2</entry><entry>N2_B</entry><entry>N2_A, N2_B, N2_C, N2_D, N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*), N3_A(*), N3_B(*), N3_C(*), N3_D(*)</entry></row> + <row><entry>Subnet3</entry><entry>N3_D</entry><entry>N3_A, N3_B, N3_C, N3_D, N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*), N2_A(*), N2_B(*), N2_C(*), N2_D(*)</entry></row> + </tbody> + </tgroup> +</table> Servers with a (*) after them are non-authoritative names. -</programlisting> </para> <para> @@ -1496,5 +1506,19 @@ This may take a long time on some networks (months). </para> </sect2> + +<sect1> +<title>My client reports "This server is not configured to list shared resources"</title> + +<para> +Your guest account is probably invalid for some reason. Samba uses the +guest account for browsing in smbd. Check that your guest account is +valid. +</para> + +<para>See also <parameter>guest account</parameter> in the &smb.conf; man page.</para> + +</sect2> + </sect1> </chapter> diff --git a/docs/docbook/projdoc/Other-Clients.xml b/docs/docbook/projdoc/Other-Clients.xml index b9f4cf3a93..0cf9af7a87 100644 --- a/docs/docbook/projdoc/Other-Clients.xml +++ b/docs/docbook/projdoc/Other-Clients.xml @@ -54,14 +54,11 @@ packages, Samba, and Linux (and other UNIX-based systems) see <para>Basically, you need three components:</para> - <itemizedlist> - <listitem><para>The File and Print Client ('IBM Peer') - </para></listitem> - <listitem><para>TCP/IP ('Internet support') - </para></listitem> - <listitem><para>The "NetBIOS over TCP/IP" driver ('TCPBEUI') - </para></listitem> - </itemizedlist> + <simplelist> + <member>The File and Print Client ('IBM Peer')</member> + <member>TCP/IP ('Internet support') </member> + <member>The "NetBIOS over TCP/IP" driver ('TCPBEUI')</member> + </simplelist> <para>Installing the first two together with the base operating system on a blank system is explained in the Warp manual. If Warp @@ -114,40 +111,26 @@ packages, Samba, and Linux (and other UNIX-based systems) see </sect2> <sect2> - <title>Are there any other issues when OS/2 (any version) - is used as a client?</title> - - <para>When you do a NET VIEW or use the "File and Print - Client Resource Browser", no Samba servers show up. This can - be fixed by a patch from <ulink - url="http://carol.wins.uva.nl/~leeuw/samba/fix.html"> - http://carol.wins.uva.nl/~leeuw/samba/fix.html</ulink>. - The patch will be included in a later version of Samba. It also - fixes a couple of other problems, such as preserving long - filenames when objects are dragged from the Workplace Shell - to the Samba server. </para> - </sect2> - - <sect2> <title>How do I get printer driver download working for OS/2 clients?</title> - <para>First, create a share called [PRINTDRV] that is + <para>First, create a share called <parameter>[PRINTDRV]</parameter> that is world-readable. Copy your OS/2 driver files there. Note that the .EA_ files must still be separate, so you will need to use the original install files, and not copy an installed driver from an OS/2 system.</para> <para>Install the NT driver first for that printer. Then, - add to your smb.conf a parameter, os2 driver map = - <replaceable>filename</replaceable>". Then, in the file + add to your &smb.conf; a parameter, <parameter>os2 driver map = + <replaceable>filename</replaceable></parameter>. Then, in the file specified by <replaceable>filename</replaceable>, map the name of the NT driver name to the OS/2 driver name as follows:</para> - <para><command>nt driver name = os2 "driver - name"."device name"</command>, e.g.: - HP LaserJet 5L = LASERJET.HP LaserJet 5L</para> + <para><parameter><replaceable>nt driver name</replaceable> = <replaceable>os2 driver name</replaceable>.<replaceable>device name</replaceable></parameter>, e.g.:</para> + + <para><parameter> + HP LaserJet 5L = LASERJET.HP LaserJet 5L</parameter></para> <para>You can have multiple drivers mapped in this file.</para> @@ -176,10 +159,16 @@ for workgroups. <para> Microsoft has released an incremental upgrade to their TCP/IP 32-Bit VxD drivers. The latest release can be found on their ftp site at -ftp.microsoft.com, located in /peropsys/windows/public/tcpip/wfwt32.exe. +ftp.microsoft.com, located in <filename>/peropsys/windows/public/tcpip/wfwt32.exe</filename>. There is an update.txt file there that describes the problems that were -fixed. New files include WINSOCK.DLL, TELNET.EXE, WSOCK.386, VNBT.386, -WSTCP.386, TRACERT.EXE, NETSTAT.EXE, and NBTSTAT.EXE. +fixed. New files include <filename>WINSOCK.DLL</filename>, +<filename>TELNET.EXE</filename>, +<filename>WSOCK.386</filename>, +<filename>VNBT.386</filename>, +<filename>WSTCP.386</filename>, +<filename>TRACERT.EXE</filename>, +<filename>NETSTAT.EXE</filename>, and +<filename>NBTSTAT.EXE</filename>. </para> </sect2> @@ -210,10 +199,11 @@ Often WfWg will totally ignore a password you give it in a dialog box. <para> There is a program call admincfg.exe on the last disk (disk 8) of the WFW 3.11 disk set. To install it -type EXPAND A:\ADMINCFG.EX_ C:\WINDOWS\ADMINCFG.EXE Then add an icon -for it via the "Progam Manager" "New" Menu. This program allows you -to control how WFW handles passwords. ie disable Password Caching etc -for use with <command>security = user</command> +type <userinput>EXPAND A:\ADMINCFG.EX_ C:\WINDOWS\ADMINCFG.EXE</userinput>. +Then add an icon +for it via the <application>Program Manager</application> <guimenu>New</guimenu> Menu. +This program allows you to control how WFW handles passwords. ie disable Password Caching etc +for use with <parameter>security = user</parameter> </para> </sect2> @@ -221,7 +211,7 @@ for use with <command>security = user</command> <sect2> <title>Case handling of passwords</title> -<para>Windows for Workgroups uppercases the password before sending it to the server. Unix passwords can be case-sensitive though. Check the <ulink url="smb.conf.5.html">smb.conf(5)</ulink> information on <command>password level</command> to specify what characters samba should try to uppercase when checking.</para> +<para>Windows for Workgroups uppercases the password before sending it to the server. Unix passwords can be case-sensitive though. Check the <ulink url="smb.conf.5.html">smb.conf(5)</ulink> information on <parameter>password level</parameter> to specify what characters samba should try to uppercase when checking.</para> </sect2> @@ -240,8 +230,9 @@ It is presumably a WfWg bug.</para> <title>Speed improvement</title> <para> -Note that some people have found that setting DefaultRcvWindow in -the [MSTCP] section of the SYSTEM.INI file under WfWg to 3072 gives a +Note that some people have found that setting <parameter>DefaultRcvWindow</parameter> in +the <parameter>[MSTCP]</parameter> section of the +<filename>SYSTEM.INI</filename> file under WfWg to 3072 gives a big improvement. I don't know why. </para> @@ -270,16 +261,17 @@ Microsoft Web site for all currently available updates to your specific version of Windows 95. </para> -<orderedlist> -<listitem><para>Kernel Update: KRNLUPD.EXE</para></listitem> -<listitem><para>Ping Fix: PINGUPD.EXE</para></listitem> -<listitem><para>RPC Update: RPCRTUPD.EXE</para></listitem> -<listitem><para>TCP/IP Update: VIPUPD.EXE</para></listitem> -<listitem><para>Redirector Update: VRDRUPD.EXE</para></listitem> -</orderedlist> +<simplelist> +<member>Kernel Update: KRNLUPD.EXE</member> +<member>Ping Fix: PINGUPD.EXE</member> +<member>RPC Update: RPCRTUPD.EXE</member> +<member>TCP/IP Update: VIPUPD.EXE</member> +<member>Redirector Update: VRDRUPD.EXE</member> +</simplelist> <para> -Also, if using MS OutLook it is desirable to install the OLEUPD.EXE fix. This +Also, if using <application>MS OutLook</application> it is desirable to +install the <command>OLEUPD.EXE</command> fix. This fix may stop your machine from hanging for an extended period when exiting OutLook and you may also notice a significant speedup when accessing network neighborhood services. @@ -290,7 +282,7 @@ neighborhood services. <para> Configure the win95 TCPIP registry settings to give better -performance. I use a program called MTUSPEED.exe which I got off the +performance. I use a program called <command>MTUSPEED.exe</command> which I got off the net. There are various other utilities of this type freely available. </para> @@ -312,7 +304,7 @@ likely occur if it is not. <para> In order to serve profiles successfully to Windows 2000 SP2 clients (when not operating as a PDC), Samba must have -<command>nt acl support = no</command> +<parameter>nt acl support = no</parameter> added to the file share which houses the roaming profiles. If this is not done, then the Windows 2000 SP2 client will complain about not being able to access the profile (Access @@ -320,7 +312,7 @@ Denied) and create multiple copies of it on disk (DOMAIN.user.001, DOMAIN.user.002, etc...). See the <ulink url="smb.conf.5.html">smb.conf(5)</ulink> man page for more details on this option. Also note that the -<command>nt acl support</command> parameter was formally a global parameter in +<parameter>nt acl support</parameter> parameter was formally a global parameter in releases prior to Samba 2.2.2. </para> @@ -343,17 +335,17 @@ the security descriptor for the profile which contains the Samba server's SID, and not the domain SID. The client compares the SID for SAMBA\user and realizes it is different that the one assigned to DOMAIN\user. Hence the reason -for the "access denied" message. +for the <errorname>access denied</errorname> message. </para> <para> -By disabling the <command>nt acl support</command> parameter, Samba will send +By disabling the <parameter>nt acl support</parameter> parameter, Samba will send the Win2k client a response to the QuerySecurityDescriptor trans2 call which causes the client to set a default ACL for the profile. This default ACL includes </para> -<para><command>DOMAIN\user "Full Control"</command></para> +<para><emphasis>DOMAIN\user "Full Control"</emphasis>></para> <note><para>This bug does not occur when using winbind to create accounts on the Samba host for Domain users.</para></note> diff --git a/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml b/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml index 4b5179acc7..c9fd510219 100644 --- a/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml +++ b/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml @@ -1,46 +1,462 @@ <chapter id="pam"> <chapterinfo> &author.jht; - <pubdate> (Jun 21 2001) </pubdate> + <author> + <firstname>Stephen</firstname><surname>Langasek</surname> + <affiliation> + <address><email>vorlon@netexpress.net</email></address> + </affiliation> + </author> + <pubdate>May 31, 2003</pubdate> </chapterinfo> -<title>PAM Configuration for Centrally Managed Authentication</title> +<title>PAM based Distributed Authentication</title> + +<para> +This chapter you should help you to deploy winbind based authentication on any PAM enabled +Unix/Linux system. Winbind can be used to enable user level application access authentication +from any MS Windows NT Domain, MS Windows 200x Active Directory based domain, or any Samba +based domain environment. It will also help you to configure PAM based local host access +controls that are appropriate to your Samba configuration. +</para> + +<para> +In addition to knowing how to configure winbind into PAM, you will learn generic PAM managment +possibilities and in particular how to deploy tools like pam_smbpass.so to your adavantage. +</para> + +<note><para> +The use of Winbind require more than PAM configuration alone. Please refer to: <link linkend="winbind"></link> +</para></note> <sect1> -<title>Samba and PAM</title> - -<para> -A number of Unix systems (eg: Sun Solaris), as well as the -xxxxBSD family and Linux, now utilize the Pluggable Authentication -Modules (PAM) facility to provide all authentication, -authorization and resource control services. Prior to the -introduction of PAM, a decision to use an alternative to -the system password database (<filename>/etc/passwd</filename>) -would require the provision of alternatives for all programs that provide -security services. Such a choice would involve provision of -alternatives to such programs as: <command>login</command>, +<title>Features and Benefits</title> + +<para> +A number of Unix systems (eg: Sun Solaris), as well as the xxxxBSD family and Linux, +now utilize the Pluggable Authentication Modules (PAM) facility to provide all authentication, +authorization and resource control services. Prior to the introduction of PAM, a decision +to use an alternative to the system password database (<filename>/etc/passwd</filename>) +would require the provision of alternatives for all programs that provide security services. +Such a choice would involve provision of alternatives to such programs as: <command>login</command>, <command>passwd</command>, <command>chown</command>, etc. </para> <para> -PAM provides a mechanism that disconnects these security programs -from the underlying authentication/authorization infrastructure. -PAM is configured either through one file <filename>/etc/pam.conf</filename> (Solaris), -or by editing individual files that are located in <filename>/etc/pam.d</filename>. +PAM provides a mechanism that disconnects these security programs from the underlying +authentication/authorization infrastructure. PAM is configured either through one file +<filename>/etc/pam.conf</filename> (Solaris), or by editing individual files that are +located in <filename>/etc/pam.d</filename>. </para> -<note> - <para> - If the PAM authentication module (loadable link library file) is located in the - default location then it is not necessary to specify the path. In the case of - Linux, the default location is <filename>/lib/security</filename>. If the module - is located outside the default then the path must be specified as: - - <programlisting> - auth required /other_path/pam_strange_module.so - </programlisting> - </para> -</note> +<para> +On PAM enabled Unix/Linux systems it is an easy matter to configure the system to use any +authentication backend, so long as the appropriate dynamically loadable library modules +are available for it. The backend may be local to the system, or may be centralised on a +remote server. +</para> + +<para> +PAM support modules are available for: +</para> + +<variablelist> + <varlistentry><term><filename>/etc/passwd</filename></term><listitem><para>-</para> + <para> + There are several PAM modules that interact with this standard Unix user + database. The most common are called: pam_unix.so, pam_unix2.so, pam_pwdb.so + and pam_userdb.so. + </para> + </listitem></varlistentry> + + <varlistentry><term>Kerberos</term><listitem><para>-</para> + <para> + The pam_krb5.so module allows the use of any Kerberos compliant server. + This tool is used to access MIT Kerberos, Heimdal Kerberos, and potentially + Microsoft Active Directory (if enabled). + </para> + </listitem></varlistentry> + + <varlistentry><term>LDAP</term><listitem><para>-</para> + <para> + The pam_ldap.so module allows the use of any LDAP v2 or v3 compatible backend + server. Commonly used LDAP backend servers include: OpenLDAP v2.0 and v2.1, + Sun ONE iDentity server, Novell eDirectory server, Microsoft Active Directory. + </para> + </listitem></varlistentry> + + <varlistentry><term>NetWare Bindery</term><listitem><para>-</para> + <para> + The pam_ncp_auth.so module allows authentication off any bindery enabled + NetWare Core Protocol based server. + </para> + </listitem></varlistentry> + + <varlistentry><term>SMB Password</term><listitem><para>-</para> + <para> + This module, called pam_smbpass.so, will allow user authentication off + the passdb backend that is configured in the Samba &smb.conf; file. + </para> + </listitem></varlistentry> + + <varlistentry><term>SMB Server</term><listitem><para>-</para> + <para> + The pam_smb_auth.so module is the original MS Windows networking authentication + tool. This module has been somewhat outdated by the Winbind module. + </para> + </listitem></varlistentry> + + <varlistentry><term>Winbind</term><listitem><para>-</para> + <para> + The pam_winbind.so module allows Samba to obtain authentication from any + MS Windows Domain Controller. It can just as easily be used to authenticate + users for access to any PAM enabled application. + </para> + </listitem></varlistentry> + + <varlistentry><term>RADIUS</term><listitem><para>-</para> + <para> + There is a PAM RADIUS (Remote Access Dial-In User Service) authentication + module. In most cases the administrator will need to locate the source code + for this tool and compile and install it themselves. RADIUS protocols are + used by many routers and terminal servers. + </para> + </listitem></varlistentry> +</variablelist> + +<para> +Of the above, Samba provides the pam_smbpasswd.so and the pam_winbind.so modules alone. +</para> + +<para> +Once configured, these permit a remarkable level of flexibility in the location and use +of distributed samba domain controllers that can provide wide are network bandwidth +efficient authentication services for PAM capable systems. In effect, this allows the +deployment of centrally managed and maintained distributed authentication from a single +user account database. +</para> + +</sect1> + +<sect1> +<title>Technical Discussion</title> + +<para> +PAM is designed to provide the system administrator with a great deal of flexibility in +configuration of the privilege granting applications of their system. The local +configuration of system security controlled by PAM is contained in one of two places: +either the single system file, /etc/pam.conf; or the /etc/pam.d/ directory. +</para> + +<sect2> +<title>PAM Configuration Syntax</title> + +<para> +In this section we discuss the correct syntax of and generic options respected by entries to these files. +PAM specific tokens in the configuration file are case insensitive. The module paths, however, are case +sensitive since they indicate a file's name and reflect the case dependence of typical file-systems. +The case-sensitivity of the arguments to any given module is defined for each module in turn. +</para> + +<para> +In addition to the lines described below, there are two special characters provided for the convenience +of the system administrator: comments are preceded by a `#' and extend to the next end-of-line; also, +module specification lines may be extended with a `\' escaped newline. +</para> + +<para> +If the PAM authentication module (loadable link library file) is located in the +default location then it is not necessary to specify the path. In the case of +Linux, the default location is <filename>/lib/security</filename>. If the module +is located outside the default then the path must be specified as: +</para> + +<para> +<screen> +auth required /other_path/pam_strange_module.so +</screen> +</para> + +<sect3> +<title>Anatomy of <filename>/etc/pam.d</filename> Entries</title> + +<para> +The remaining information in this subsection was taken from the documentation of the Linux-PAM +project. For more information on PAM, see +<ulink url="http://ftp.kernel.org/pub/linux/libs/pam/"> +http://ftp.kernel.org/pub/linux/libs/pam</ulink> The Official Linux-PAM home page. +</para> + +<para> +A general configuration line of the /etc/pam.conf file has the following form: +</para> + +<para> +<screen> +service-name module-type control-flag module-path args +</screen> +</para> + +<para> +Below, we explain the meaning of each of these tokens. The second (and more recently adopted) +way of configuring Linux-PAM is via the contents of the <filename>/etc/pam.d/</filename> directory. +Once we have explained the meaning of the above tokens, we will describe this method. +</para> + +<variablelist> + <varlistentry><term>service-name</term><listitem><para>-</para> + <para> + The name of the service associated with this entry. Frequently the service name is the conventional + name of the given application. For example, `ftpd', `rlogind' and `su', etc. . + </para> + + <para> + There is a special service-name, reserved for defining a default authentication mechanism. It has + the name `OTHER' and may be specified in either lower or upper case characters. Note, when there + is a module specified for a named service, the `OTHER' entries are ignored. + </para></listitem> + </varlistentry> + + <varlistentry><term>module-type</term><listitem><para>-</para> + <para> + One of (currently) four types of module. The four types are as follows: + </para> + + <itemizedlist> + <listitem><para> + <emphasis>auth:</emphasis> this module type provides two aspects of authenticating the user. + Firstly, it establishes that the user is who they claim to be, by instructing the application + to prompt the user for a password or other means of identification. Secondly, the module can + grant group membership (independently of the <filename>/etc/groups</filename> file discussed + above) or other privileges through its credential granting properties. + </para></listitem> + + <listitem><para> + <emphasis>account:</emphasis> this module performs non-authentication based account management. + It is typically used to restrict/permit access to a service based on the time of day, currently + available system resources (maximum number of users) or perhaps the location of the applicant + user `root' login only on the console. + </para></listitem> + + <listitem><para> + <emphasis>session:</emphasis> primarily, this module is associated with doing things that need + to be done for the user before/after they can be given service. Such things include the loggin + of information concerning the opening/closing of some data exchange with a user, mountin + directories, etc. + </para></listitem> + + <listitem><para> + <emphasis>password:</emphasis> this last module type is required for updating the authentication + token associated with the user. Typically, there is one module for each `challenge/response' + based authentication (auth) module-type. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + + <varlistentry><term>control-flag</term><listitem><para>-</para> + <para> + The control-flag is used to indicate how the PAM library will react to the success or failure of the + module it is associated with. Since modules can be stacked (modules of the same type execute in series, + one after another), the control-flags determine the relative importance of each module. The application + is not made aware of the individual success or failure of modules listed in the + <filename>/etc/pam.conf</filename> file. Instead, it receives a summary success or fail response from + the Linux-PAM library. The order of execution of these modules is that of the entries in the + <filename>/etc/pam.conf</filename> file; earlier entries are executed before later ones. + As of Linux-PAM v0.60, this control-flag can be defined with one of two syntaxes. + </para> + + <para> + The simpler (and historical) syntax for the control-flag is a single keyword defined to indicate the + severity of concern associated with the success or failure of a specific module. There are four such + <emphasis>keywords: required, requisite, sufficient and optional</emphasis>. + </para> + + <para> + The Linux-PAM library interprets these keywords in the following manner: + </para> + + <itemizedlist> + <listitem><para> + <emphasis>required:</emphasis> this indicates that the success of the module is required for the + module-type facility to succeed. Failure of this module will not be apparent to the user until all + of the remaining modules (of the same module-type) have been executed. + </para></listitem> + + <listitem><para> + <emphasis>requisite:</emphasis> like required, however, in the case that such a module returns a + failure, control is directly returned to the application. The return value is that associated with + the first required or requisite module to fail. Note, this flag can be used to protect against the + possibility of a user getting the opportunity to enter a password over an unsafe medium. It is + conceivable that such behavior might inform an attacker of valid accounts on a system. This + possibility should be weighed against the not insignificant concerns of exposing a sensitive + password in a hostile environment. + </para></listitem> + + <listitem><para> + <emphasis>sufficient:</emphasis> the success of this module is deemed `sufficient' to satisfy + the Linux-PAM library that this module-type has succeeded in its purpose. In the event that no + previous required module has failed, no more `stacked' modules of this type are invoked. (Note, + in this case subsequent required modules are not invoked.). A failure of this module is not deemed + as fatal to satisfying the application that this module-type has succeeded. + </para></listitem> + + <listitem><para> + <emphasis>optional:</emphasis> as its name suggests, this control-flag marks the module as not + being critical to the success or failure of the user's application for service. In general, + Linux-PAM ignores such a module when determining if the module stack will succeed or fail. + However, in the absence of any definite successes or failures of previous or subsequent stacked + modules this module will determine the nature of the response to the application. One example of + this latter case, is when the other modules return something like PAM_IGNORE. + </para></listitem> + </itemizedlist> + + <para> + The more elaborate (newer) syntax is much more specific and gives the administrator a great deal of control + over how the user is authenticated. This form of the control flag is delimeted with square brackets and + consists of a series of value=action tokens: + </para> + + <para><screen> + [value1=action1 value2=action2 ...] + </screen></para> + + <para> + Here, valueI is one of the following return values: success; open_err; symbol_err; service_err; + system_err; buf_err; perm_denied; auth_err; cred_insufficient; authinfo_unavail; user_unknown; maxtries; + new_authtok_reqd; acct_expired; session_err; cred_unavail; cred_expired; cred_err; no_module_data; conv_err; + authtok_err; authtok_recover_err; authtok_lock_busy; authtok_disable_aging; try_again; ignore; abort; + authtok_expired; module_unknown; bad_item; and default. The last of these (default) can be used to set + the action for those return values that are not explicitly defined. + </para> + + <para> + The actionI can be a positive integer or one of the following tokens: ignore; ok; done; bad; die; and reset. + A positive integer, J, when specified as the action, can be used to indicate that the next J modules of the + current module-type will be skipped. In this way, the administrator can develop a moderately sophisticated + stack of modules with a number of different paths of execution. Which path is taken can be determined by the + reactions of individual modules. + </para> + + <itemizedlist> + <listitem><para> + <emphasis>ignore:</emphasis> when used with a stack of modules, the module's return status will not + contribute to the return code the application obtains. + </para></listitem> + + <listitem><para> + <emphasis>bad:</emphasis> this action indicates that the return code should be thought of as indicative + of the module failing. If this module is the first in the stack to fail, its status value will be used + for that of the whole stack. + </para></listitem> + + <listitem><para> + <emphasis>die:</emphasis> equivalent to bad with the side effect of terminating the module stack and + PAM immediately returning to the application. + </para></listitem> + + <listitem><para> + <emphasis>ok:</emphasis> this tells PAM that the administrator thinks this return code should + contribute directly to the return code of the full stack of modules. In other words, if the former + state of the stack would lead to a return of PAM_SUCCESS, the module's return code will override + this value. Note, if the former state of the stack holds some value that is indicative of a modules + failure, this 'ok' value will not be used to override that value. + </para></listitem> + + <listitem><para> + <emphasis>done:</emphasis> equivalent to ok with the side effect of terminating the module stack and + PAM immediately returning to the application. + </para></listitem> + + <listitem><para> + <emphasis>reset:</emphasis> clear all memory of the state of the module stack and start again with + the next stacked module. + </para></listitem> + </itemizedlist> + + <para> + Each of the four keywords: required; requisite; sufficient; and optional, have an equivalent expression in + terms of the [...] syntax. They are as follows: + </para> + + <para> + <itemizedlist> + <listitem><para> + required is equivalent to [success=ok new_authtok_reqd=ok ignore=ignore default=bad] + </para></listitem> + + <listitem><para> + requisite is equivalent to [success=ok new_authtok_reqd=ok ignore=ignore default=die] + </para></listitem> + + <listitem><para> + sufficient is equivalent to [success=done new_authtok_reqd=done default=ignore] + </para></listitem> + + <listitem><para> + optional is equivalent to [success=ok new_authtok_reqd=ok default=ignore] + </para></listitem> + </itemizedlist> + </para> + + <para> + Just to get a feel for the power of this new syntax, here is a taste of what you can do with it. With Linux-PAM-0.63, + the notion of client plug-in agents was introduced. This is something that makes it possible for PAM to support + machine-machine authentication using the transport protocol inherent to the client/server application. With the + <emphasis>[ ... value=action ... ]</emphasis> control syntax, it is possible for an application to be configured + to support binary prompts with compliant clients, but to gracefully fall over into an alternative authentication + mode for older, legacy, applications. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>module-path</term><listitem><para>-</para> + <para> + The path-name of the dynamically loadable object file; the pluggable module itself. If the first character of the + module path is `/', it is assumed to be a complete path. If this is not the case, the given module path is appended + to the default module path: <filename>/lib/security</filename> (but see the notes above). + </para> + + <para> + The args are a list of tokens that are passed to the module when it is invoked. Much like arguments to a typical + Linux shell command. Generally, valid arguments are optional and are specific to any given module. Invalid arguments + are ignored by a module, however, when encountering an invalid argument, the module is required to write an error + to syslog(3). For a list of generic options see the next section. + </para> + + <para> + Note, if you wish to include spaces in an argument, you should surround that argument with square brackets. For example: + </para> + +<para><screen> +squid auth required pam_mysql.so user=passwd_query passwd=mada \ + db=eminence [query=select user_name from internet_service where \ + user_name='%u' and password=PASSWORD('%p') and \ + service='web_proxy'] +</screen></para> + + <para> + Note, when using this convention, you can include `[' characters inside the string, and if you wish to include a `]' + character inside the string that will survive the argument parsing, you should use `\['. In other words: + </para> + +<para><screen> +[..[..\]..] --> ..[..].. +</screen></para> + + <para> + Any line in (one of) the configuration file(s), that is not formatted correctly, will generally tend (erring on the + side of caution) to make the authentication process fail. A corresponding error is written to the system log files + with a call to syslog(3). + </para></listitem> + </varlistentry> +</variablelist> + +</sect3> + +</sect2> + +<sect2> +<title>Example System Configurations</title> <para> The following is an example <filename>/etc/pam.d/login</filename> configuration file. @@ -50,43 +466,50 @@ of the login process. Essentially all conditions can be disabled by commenting them out except the calls to <filename>pam_pwdb.so</filename>. </para> -<para><programlisting> - #%PAM-1.0 - # The PAM configuration file for the `login' service - # - auth required pam_securetty.so - auth required pam_nologin.so - # auth required pam_dialup.so - # auth optional pam_mail.so - auth required pam_pwdb.so shadow md5 - # account requisite pam_time.so - account required pam_pwdb.so - session required pam_pwdb.so - # session optional pam_lastlog.so - # password required pam_cracklib.so retry=3 - password required pam_pwdb.so shadow md5 -</programlisting></para> +<sect3> +<title>PAM: original login config</title> + +<para><screen> +#%PAM-1.0 +# The PAM configuration file for the `login' service +# +auth required pam_securetty.so +auth required pam_nologin.so +# auth required pam_dialup.so +# auth optional pam_mail.so +auth required pam_pwdb.so shadow md5 +# account requisite pam_time.so +account required pam_pwdb.so +session required pam_pwdb.so +# session optional pam_lastlog.so +# password required pam_cracklib.so retry=3 +password required pam_pwdb.so shadow md5 +</screen></para> + +</sect3> + +<sect3> +<title>PAM: login using pam_smbpass</title> <para> -PAM allows use of replacable modules. Those available on a -sample system include: +PAM allows use of replacable modules. Those available on a sample system include: </para> <para><prompt>$</prompt><userinput>/bin/ls /lib/security</userinput> -<programlisting> - pam_access.so pam_ftp.so pam_limits.so - pam_ncp_auth.so pam_rhosts_auth.so pam_stress.so - pam_cracklib.so pam_group.so pam_listfile.so - pam_nologin.so pam_rootok.so pam_tally.so - pam_deny.so pam_issue.so pam_mail.so - pam_permit.so pam_securetty.so pam_time.so - pam_dialup.so pam_lastlog.so pam_mkhomedir.so - pam_pwdb.so pam_shells.so pam_unix.so - pam_env.so pam_ldap.so pam_motd.so - pam_radius.so pam_smbpass.so pam_unix_acct.so - pam_wheel.so pam_unix_auth.so pam_unix_passwd.so - pam_userdb.so pam_warn.so pam_unix_session.so -</programlisting></para> +<screen> +pam_access.so pam_ftp.so pam_limits.so +pam_ncp_auth.so pam_rhosts_auth.so pam_stress.so +pam_cracklib.so pam_group.so pam_listfile.so +pam_nologin.so pam_rootok.so pam_tally.so +pam_deny.so pam_issue.so pam_mail.so +pam_permit.so pam_securetty.so pam_time.so +pam_dialup.so pam_lastlog.so pam_mkhomedir.so +pam_pwdb.so pam_shells.so pam_unix.so +pam_env.so pam_ldap.so pam_motd.so +pam_radius.so pam_smbpass.so pam_unix_acct.so +pam_wheel.so pam_unix_auth.so pam_unix_passwd.so +pam_userdb.so pam_warn.so pam_unix_session.so +</screen></para> <para> The following example for the login program replaces the use of @@ -102,37 +525,37 @@ hashes. This database is stored in either Samba implementation for your Unix/Linux system. The <filename>pam_smbpass.so</filename> module is provided by Samba version 2.2.1 or later. It can be compiled by specifying the -<command>--with-pam_smbpass</command> options when running Samba's -<filename>configure</filename> script. For more information +<option>--with-pam_smbpass</option> options when running Samba's +<command>configure</command> script. For more information on the <filename>pam_smbpass</filename> module, see the documentation in the <filename>source/pam_smbpass</filename> directory of the Samba source distribution. </para> -<para><programlisting> - #%PAM-1.0 - # The PAM configuration file for the `login' service - # - auth required pam_smbpass.so nodelay - account required pam_smbpass.so nodelay - session required pam_smbpass.so nodelay - password required pam_smbpass.so nodelay -</programlisting></para> +<para><screen> +#%PAM-1.0 +# The PAM configuration file for the `login' service +# +auth required pam_smbpass.so nodelay +account required pam_smbpass.so nodelay +session required pam_smbpass.so nodelay +password required pam_smbpass.so nodelay +</screen></para> <para> The following is the PAM configuration file for a particular Linux system. The default condition uses <filename>pam_pwdb.so</filename>. </para> -<para><programlisting> - #%PAM-1.0 - # The PAM configuration file for the `samba' service - # - auth required pam_pwdb.so nullok nodelay shadow audit - account required pam_pwdb.so audit nodelay - session required pam_pwdb.so nodelay - password required pam_pwdb.so shadow md5 -</programlisting></para> +<para><screen> +#%PAM-1.0 +# The PAM configuration file for the `samba' service +# +auth required pam_pwdb.so nullok nodelay shadow audit +account required pam_pwdb.so audit nodelay +session required pam_pwdb.so nodelay +password required pam_pwdb.so shadow md5 +</screen></para> <para> In the following example the decision has been made to use the @@ -142,15 +565,15 @@ thus allow the smbpasswd passwords to be changed using the passwd program. </para> -<para><programlisting> - #%PAM-1.0 - # The PAM configuration file for the `samba' service - # - auth required pam_smbpass.so nodelay - account required pam_pwdb.so audit nodelay - session required pam_pwdb.so nodelay - password required pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf -</programlisting></para> +<para><screen> +#%PAM-1.0 +# The PAM configuration file for the `samba' service +# +auth required pam_smbpass.so nodelay +account required pam_pwdb.so audit nodelay +session required pam_pwdb.so nodelay +password required pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf +</screen></para> <note><para>PAM allows stacking of authentication mechanisms. It is also possible to pass information obtained within one PAM module through @@ -165,8 +588,12 @@ life though, every decision makes trade-offs, so you may want examine the PAM documentation for further helpful information. </para></note> +</sect3> + +</sect2> + <sect2> -<title>PAM Configuration in smb.conf</title> +<title>smb.conf PAM Configuration</title> <para> There is an option in smb.conf called <ulink @@ -175,8 +602,8 @@ The following is from the on-line help for this option in SWAT; </para> <para> -When Samba is configured to enable PAM support (i.e. -<constant>--with-pam</constant>), this parameter will +When Samba-3 is configured to enable PAM support (i.e. +<option>--with-pam</option>), this parameter will control whether or not Samba should obey PAM's account and session management directives. The default behavior is to use PAM for clear text authentication only and to @@ -188,12 +615,53 @@ authentication mechanism needed in the presence of SMB password encryption. </para> -<para>Default: <command>obey pam restrictions = no</command></para> +<para>Default: <parameter>obey pam restrictions = no</parameter></para> </sect2> <sect2> -<title>Password Synchronisation using pam_smbpass.so</title> +<title>Remote CIFS Authentication using winbindd.so</title> + +<para> +All operating systems depend on the provision of users credentials accecptable to the platform. +Unix requires the provision of a user identifier (UID) as well as a group identifier (GID). +These are both simple integer type numbers that are obtained from a password backend such +as <filename>/etc/passwd</filename>. +</para> + +<para> +Users and groups on a Windows NT server are assigned a relative id (rid) which is unique for +the domain when the user or group is created. To convert the Windows NT user or group into +a unix user or group, a mapping between rids and unix user and group ids is required. This +is one of the jobs that winbind performs. +</para> + +<para> +As winbind users and groups are resolved from a server, user and group ids are allocated +from a specified range. This is done on a first come, first served basis, although all +existing users and groups will be mapped as soon as a client performs a user or group +enumeration command. The allocated unix ids are stored in a database file under the Samba +lock directory and will be remembered. +</para> + +<para> +The astute administrator will realize from this that the combination of <filename>pam_smbpass.so</filename>, +<command>winbindd</command>, and a distributed passdb backend, such as ldap, will allow the establishment of a +centrally managed, distributed user/password database that can also be used by all PAM (eg: Linux) aware +programs and applications. This arrangement can have particularly potent advantages compared with the use of +Microsoft Active Directory Service (ADS) in so far as reduction of wide area network authentication traffic. +</para> + +<warning><para> +The rid to unix id database is the only location where the user and group mappings are +stored by winbindd. If this file is deleted or corrupted, there is no way for winbindd +to determine which user and group ids correspond to Windows NT user and group rids. +</para></warning> + +</sect2> + +<sect2> +<title>Password Synchronization using pam_smbpass.so</title> <para> pam_smbpass is a PAM module which can be used on conforming systems to @@ -204,62 +672,48 @@ generic interface to authentication mechanisms. </para> <para> -For more information on PAM, see http://ftp.kernel.org/pub/linux/libs/pam/ -</para> - -<para> This module authenticates a local smbpasswd user database. If you require support for authenticating against a remote SMB server, or if you're concerned about the presence of suid root binaries on your system, it is recommended that you use pam_winbind instead. </para> -<para><programlisting> +<para> Options recognized by this module are as follows: +<table frame="all"> + <title>Options recognized by pam_smbpass</title> + <tgroup cols="2" align="left"> + <tbody> + <row><entry>debug</entry><entry>log more debugging info</entry></row> + <row><entry>audit</entry><entry>like debug, but also logs unknown usernames</entry></row> + <row><entry>use_first_pass</entry><entry>don't prompt the user for passwords; take them from PAM_ items instead</entry></row> + <row><entry>try_first_pass</entry><entry>try to get the password from a previous PAM module, fall back to prompting the user</entry></row> + <row><entry>use_authtok</entry><entry>like try_first_pass, but *fail* if the new PAM_AUTHTOK has not been previously set. (intended for stacking password modules only)</entry></row> + <row><entry>not_set_pass</entry><entry>don't make passwords used by this module available to other modules.</entry></row> + <row><entry>nodelay</entry><entry>don't insert ~1 second delays on authentication failure.</entry></row> + <row><entry>nullok</entry><entry>null passwords are allowed.</entry></row> + <row><entry>nonull</entry><entry>null passwords are not allowed. Used to override the Samba configuration.</entry></row> + <row><entry>migrate</entry><entry>only meaningful in an "auth" context; used to update smbpasswd file with a password used for successful authentication.</entry></row> + <row><entry>smbconf=<replaceable>file</replaceable></entry><entry>specify an alternate path to the &smb.conf; file.</entry></row> + </tbody> +</tgroup> +</table> +</para> - debug - log more debugging info - audit - like debug, but also logs unknown usernames - use_first_pass - don't prompt the user for passwords; - take them from PAM_ items instead - try_first_pass - try to get the password from a previous - PAM module, fall back to prompting the user - use_authtok - like try_first_pass, but *fail* if the new - PAM_AUTHTOK has not been previously set. - (intended for stacking password modules only) - not_set_pass - don't make passwords used by this module - available to other modules. - nodelay - don't insert ~1 second delays on authentication - failure. - nullok - null passwords are allowed. - nonull - null passwords are not allowed. Used to - override the Samba configuration. - migrate - only meaningful in an "auth" context; - used to update smbpasswd file with a - password used for successful authentication. - smbconf=< file > - specify an alternate path to the smb.conf - file. -</programlisting></para> - -<para><programlisting> +<para> Thanks go to the following people: +<simplelist> + <member><ulink url="mailto:morgan@transmeta.com">Andrew Morgan</ulink>, for providing the Linux-PAM + framework, without which none of this would have happened</member> - * Andrew Morgan < morgan@transmeta.com >, for providing the Linux-PAM - framework, without which none of this would have happened - - * Christian Gafton < gafton@redhat.com > and Andrew Morgan again, for the - pam_pwdb module upon which pam_smbpass was originally based + <member><ulink url="gafton@redhat.com">Christian Gafton</ulink> and Andrew Morgan again, for the + pam_pwdb module upon which pam_smbpass was originally based</member> - * Luke Leighton < lkcl@switchboard.net > for being receptive to the idea, + <member><ulink url="lkcl@switchboard.net">Luke Leighton</ulink> for being receptive to the idea, and for the occasional good-natured complaint about the project's status - that keep me working on it :) - - * and of course, all the other members of the Samba team - <http://www.samba.org/samba/team.html>, for creating a great product - and for giving this project a purpose - - --------------------- - Stephen Langasek < vorlon@netexpress.net > -</programlisting></para> + that keep me working on it :)</member> +</simplelist>. +</para> <para> The following are examples of the use of pam_smbpass.so in the format of Linux @@ -268,7 +722,7 @@ tool on other platforms will need to adapt this appropriately. </para> <sect3> -<title>Password Synchonisation Configuration</title> +<title>Password Synchronisation Configuration</title> <para> A sample PAM configuration that shows the use of pam_smbpass to make @@ -277,18 +731,18 @@ is changed. Useful when an expired password might be changed by an application (such as ssh). </para> -<para><programlisting> - #%PAM-1.0 - # password-sync - # - auth requisite pam_nologin.so - auth required pam_unix.so - account required pam_unix.so - password requisite pam_cracklib.so retry=3 - password requisite pam_unix.so shadow md5 use_authtok try_first_pass - password required pam_smbpass.so nullok use_authtok try_first_pass - session required pam_unix.so -</programlisting></para> +<para><screen> +#%PAM-1.0 +# password-sync +# +auth requisite pam_nologin.so +auth required pam_unix.so +account required pam_unix.so +password requisite pam_cracklib.so retry=3 +password requisite pam_unix.so shadow md5 use_authtok try_first_pass +password required pam_smbpass.so nullok use_authtok try_first_pass +session required pam_unix.so +</screen></para> </sect3> <sect3> @@ -302,20 +756,20 @@ password migration takes place when users ftp in, login using ssh, pop their mail, etc. </para> -<para><programlisting> - #%PAM-1.0 - # password-migration - # - auth requisite pam_nologin.so - # pam_smbpass is called IFF pam_unix succeeds. - auth requisite pam_unix.so - auth optional pam_smbpass.so migrate - account required pam_unix.so - password requisite pam_cracklib.so retry=3 - password requisite pam_unix.so shadow md5 use_authtok try_first_pass - password optional pam_smbpass.so nullok use_authtok try_first_pass - session required pam_unix.so -</programlisting></para> +<para><screen> +#%PAM-1.0 +# password-migration +# +auth requisite pam_nologin.so +# pam_smbpass is called IF pam_unix succeeds. +auth requisite pam_unix.so +auth optional pam_smbpass.so migrate +account required pam_unix.so +password requisite pam_cracklib.so retry=3 +password requisite pam_unix.so shadow md5 use_authtok try_first_pass +password optional pam_smbpass.so nullok use_authtok try_first_pass +session required pam_unix.so +</screen></para> </sect3> <sect3> @@ -327,18 +781,18 @@ private/smbpasswd is fully populated, and we consider it an error if the smbpasswd doesn't exist or doesn't match the Unix password. </para> -<para><programlisting> - #%PAM-1.0 - # password-mature - # - auth requisite pam_nologin.so - auth required pam_unix.so - account required pam_unix.so - password requisite pam_cracklib.so retry=3 - password requisite pam_unix.so shadow md5 use_authtok try_first_pass - password required pam_smbpass.so use_authtok use_first_pass - session required pam_unix.so -</programlisting></para> +<para><screen> +#%PAM-1.0 +# password-mature +# +auth requisite pam_nologin.so +auth required pam_unix.so +account required pam_unix.so +password requisite pam_cracklib.so retry=3 +password requisite pam_unix.so shadow md5 use_authtok try_first_pass +password required pam_smbpass.so use_authtok use_first_pass +session required pam_unix.so +</screen></para> </sect3> <sect3> @@ -350,40 +804,71 @@ pam_krb5. This could be useful on a Samba PDC that is also a member of a Kerberos realm. </para> -<para><programlisting> - #%PAM-1.0 - # kdc-pdc - # - auth requisite pam_nologin.so - auth requisite pam_krb5.so - auth optional pam_smbpass.so migrate - account required pam_krb5.so - password requisite pam_cracklib.so retry=3 - password optional pam_smbpass.so nullok use_authtok try_first_pass - password required pam_krb5.so use_authtok try_first_pass - session required pam_krb5.so -</programlisting></para> +<para><screen> +#%PAM-1.0 +# kdc-pdc +# +auth requisite pam_nologin.so +auth requisite pam_krb5.so +auth optional pam_smbpass.so migrate +account required pam_krb5.so +password requisite pam_cracklib.so retry=3 +password optional pam_smbpass.so nullok use_authtok try_first_pass +password required pam_krb5.so use_authtok try_first_pass +session required pam_krb5.so +</screen></para> + </sect3> </sect2> + </sect1> <sect1> -<title>Distributed Authentication</title> +<title>Common Errors</title> <para> -The astute administrator will realize from this that the -combination of <filename>pam_smbpass.so</filename>, -<command>winbindd</command>, and a distributed -passdb backend, such as ldap, will allow the establishment of a -centrally managed, distributed -user/password database that can also be used by all -PAM (eg: Linux) aware programs and applications. This arrangement -can have particularly potent advantages compared with the -use of Microsoft Active Directory Service (ADS) in so far as -reduction of wide area network authentication traffic. +PAM can be a very fickle and sensitive to configuration glitches. Here we look at a few cases from +the Samba mailing list. </para> + <sect2> + <title>pam_winbind problem</title> + + <para> + I have the following PAM configuration: + </para> + +<para> +<screen> +auth required /lib/security/pam_securetty.so +auth sufficient /lib/security/pam_winbind.so +auth sufficient /lib/security/pam_unix.so use_first_pass nullok +auth required /lib/security/pam_stack.so service=system-auth +auth required /lib/security/pam_nologin.so +account required /lib/security/pam_stack.so service=system-auth +account required /lib/security/pam_winbind.so +password required /lib/security/pam_stack.so service=system-auth +</screen> +</para> + + <para> + When I open a new console with [ctrl][alt][F1], then I cant log in with my user "pitie". + I've tried with user "scienceu+pitie" also. + </para> + + <para> + Answer: The problem may lie with your inclusion of <parameter>pam_stack.so + service=system-auth</parameter>. That file often contains a lot of stuff that may + duplicate what you're already doing. Try commenting out the pam_stack lines + for auth and account and see if things work. If they do, look at + <filename>/etc/pam.d/system-auth</filename> and copy only what you need from it into your + <filename>/etc/pam.d/login</filename> file. Alternatively, if you want all services to use + winbind, you can put the winbind-specific stuff in <filename>/etc/pam.d/system-auth</filename>. + </para> + + </sect2> + </sect1> </chapter> diff --git a/docs/docbook/projdoc/PolicyMgmt.xml b/docs/docbook/projdoc/PolicyMgmt.xml index 2ae3fa5ea7..10f1bca6c7 100644 --- a/docs/docbook/projdoc/PolicyMgmt.xml +++ b/docs/docbook/projdoc/PolicyMgmt.xml @@ -3,8 +3,51 @@ &author.jht; <pubdate>April 3 2003</pubdate> </chapterinfo> + <title>System and Account Policies</title> +<para> +This chapter summarises the current state of knowledge derived from personal +practice and knowledge from samba mailing list subscribers. Before reproduction +of posted information effort has been made to validate the information provided. +Where additional information was uncovered through this validation it is provided +also. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +When MS Windows NT3.5 was introduced the hot new topic was the ability to implmement +Group Policies for users and group. Then along came MS Windows NT4 and a few sites +started to adopt this capability. How do we know that? By way of the number of "booboos" +(or mistakes) administrators made and then requested help to resolve. +</para> + +<para> +By the time that MS Windows 2000 and Active Directory was released, administrators +got the message: Group Policies are a good thing! They can help reduce administrative +costs and actually can help to create happier users. But adoption of the true +potential of MS Windows 200x Active Directory and Group Policy Objects (GPOs) for users +and machines were picked up on rather slowly. This was very obvious from the samba +mailing list as in 2000 and 2001 there were very few postings regarding GPOs and +how to replicate them in a Samba environment. +</para> + +<para> +Judging by the traffic volume since mid 2002, GPOs have become a standard part of +the deployment in many sites. This chapter reviews techniques and methods that can +be used to exploit opportunities for automation of control over user desktops and +network client workstations. +</para> + +<para> +A tool new to Samba-3 may become an important part of the future Samba Administrators' +arsenal. The <command>editreg</command> tool is described in this document. +</para> + +</sect1> + <sect1> <title>Creating and Managing System Policies</title> @@ -55,194 +98,193 @@ What follows is a very brief discussion with some helpful notes. The information here is incomplete - you are warned. </para> -<sect2> -<title>Windows 9x/Me Policies</title> - -<para> -You need the Win98 Group Policy Editor to set Group Profiles up under Windows 9x/Me. -It can be found on the Original full product Win98 installation CD under -<filename>tools/reskit/netadmin/poledit</filename>. Install this using the -Add/Remove Programs facility and then click on the 'Have Disk' tab. -</para> - -<para> -Use the Group Policy Editor to create a policy file that specifies the location of -user profiles and/or the <filename>My Documents</filename> etc. stuff. Then -save these settings in a file called <filename>Config.POL</filename> that needs to -be placed in the root of the [NETLOGON] share. If Win98 is configured to log onto -the Samba Domain, it will automatically read this file and update the Win9x/Me registry -of the machine as it logs on. -</para> - -<para> -Further details are covered in the Win98 Resource Kit documentation. -</para> - -<para> -If you do not take the right steps, then every so often Win9x/Me will check the -integrity of the registry and will restore it's settings from the back-up -copy of the registry it stores on each Win9x/Me machine. Hence, you will -occasionally notice things changing back to the original settings. -</para> + <sect2> + <title>Windows 9x/Me Policies</title> -<para> -Install the group policy handler for Win9x to pick up group policies. Look on the -Win98 CD in <filename>\tools\reskit\netadmin\poledit</filename>. -Install group policies on a Win9x client by double-clicking -<filename>grouppol.inf</filename>. Log off and on again a couple of times and see -if Win98 picks up group policies. Unfortunately this needs to be done on every -Win9x/Me machine that uses group policies. -</para> - -</sect2> -<sect2> -<title>Windows NT4 Style Policy Files</title> - -<para> -To create or edit <filename>ntconfig.pol</filename> you must use the NT Server -Policy Editor, <command>poledit.exe</command> which is included with NT4 Server -but <emphasis>not NT Workstation</emphasis>. There is a Policy Editor on a NT4 -Workstation but it is not suitable for creating <emphasis>Domain Policies</emphasis>. -Further, although the Windows 95 Policy Editor can be installed on an NT4 -Workstation/Server, it will not work with NT clients. However, the files from -the NT Server will run happily enough on an NT4 Workstation. -</para> - -<para> -You need <filename>poledit.exe, common.adm</filename> and <filename>winnt.adm</filename>. -It is convenient to put the two *.adm files in the <filename>c:\winnt\inf</filename> -directory which is where the binary will look for them unless told otherwise. Note also that that -directory is normally 'hidden'. -</para> + <para> + You need the Win98 Group Policy Editor to set Group Profiles up under Windows 9x/Me. + It can be found on the Original full product Win98 installation CD under + <filename>tools/reskit/netadmin/poledit</filename>. Install this using the + Add/Remove Programs facility and then click on the 'Have Disk' tab. + </para> -<para> -The Windows NT policy editor is also included with the Service Pack 3 (and -later) for Windows NT 4.0. Extract the files using <command>servicepackname /x</command>, -i.e. that's <command>Nt4sp6ai.exe /x</command> for service pack 6a. The policy editor, -<command>poledit.exe</command> and the associated template files (*.adm) should -be extracted as well. It is also possible to downloaded the policy template -files for Office97 and get a copy of the policy editor. Another possible -location is with the Zero Administration Kit available for download from Microsoft. -</para> + <para> + Use the Group Policy Editor to create a policy file that specifies the location of + user profiles and/or the <filename>My Documents</filename> etc. Then save these + settings in a file called <filename>Config.POL</filename> that needs to be placed in the + root of the <parameter>[NETLOGON]</parameter> share. If Win98 is configured to log onto + the Samba Domain, it will automatically read this file and update the Win9x/Me registry + of the machine as it logs on. + </para> -<sect3> -<title>Registry Tattoos</title> + <para> + Further details are covered in the Win98 Resource Kit documentation. + </para> <para> - With NT4 style registry based policy changes, a large number of settings are not - automatically reversed as the user logs off. Since the settings that were in the - NTConfig.POL file were applied to the client machine registry and that apply to the - hive key HKEY_LOCAL_MACHINE are permanent until explicitly reversed. This is known - as tattooing. It can have serious consequences down-stream and the administrator must - be extremely careful not to lock out the ability to manage the machine at a later date. + If you do not take the right steps, then every so often Win9x/Me will check the + integrity of the registry and will restore it's settings from the back-up + copy of the registry it stores on each Win9x/Me machine. Hence, you will + occasionally notice things changing back to the original settings. </para> + <para> + Install the group policy handler for Win9x to pick up group policies. Look on the + Win98 CD in <filename>\tools\reskit\netadmin\poledit</filename>. + Install group policies on a Win9x client by double-clicking + <filename>grouppol.inf</filename>. Log off and on again a couple of times and see + if Win98 picks up group policies. Unfortunately this needs to be done on every + Win9x/Me machine that uses group policies. + </para> -</sect3> -</sect2> -<sect2> -<title>MS Windows 200x / XP Professional Policies</title> + </sect2> + <sect2> + <title>Windows NT4 Style Policy Files</title> -<para> -Windows NT4 System policies allows setting of registry parameters specific to -users, groups and computers (client workstations) that are members of the NT4 -style domain. Such policy file will work with MS Windows 2000 / XP clients also. -</para> + <para> + To create or edit <filename>ntconfig.pol</filename> you must use the NT Server + Policy Editor, <command>poledit.exe</command> which is included with NT4 Server + but <emphasis>not NT Workstation</emphasis>. There is a Policy Editor on a NT4 + Workstation but it is not suitable for creating <emphasis>Domain Policies</emphasis>. + Further, although the Windows 95 Policy Editor can be installed on an NT4 + Workstation/Server, it will not work with NT clients. However, the files from + the NT Server will run happily enough on an NT4 Workstation. + </para> -<para> -New to MS Windows 2000 Microsoft introduced a new style of group policy that confers -a superset of capabilities compared with NT4 style policies. Obviously, the tool used -to create them is different, and the mechanism for implementing them is much changed. -</para> + <para> + You need <filename>poledit.exe</filename>, <filename>common.adm</filename> and <filename>winnt.adm</filename>. + It is convenient to put the two *.adm files in the <filename>c:\winnt\inf</filename> + directory which is where the binary will look for them unless told otherwise. Note also that that + directory is normally 'hidden'. + </para> -<para> -The older NT4 style registry based policies are known as <emphasis>Administrative Templates</emphasis> -in MS Windows 2000/XP Group Policy Objects (GPOs). The later includes ability to set various security -configurations, enforce Internet Explorer browser settings, change and redirect aspects of the -users' desktop (including: the location of <emphasis>My Documents</emphasis> files (directory), as -well as intrinsics of where menu items will appear in the Start menu). An additional new -feature is the ability to make available particular software Windows applications to particular -users and/or groups. -</para> + <para> + The Windows NT policy editor is also included with the Service Pack 3 (and + later) for Windows NT 4.0. Extract the files using <command>servicepackname /x</command>, + i.e. that's <command>Nt4sp6ai.exe /x</command> for service pack 6a. The policy editor, + <command>poledit.exe</command> and the associated template files (*.adm) should + be extracted as well. It is also possible to downloaded the policy template + files for Office97 and get a copy of the policy editor. Another possible + location is with the Zero Administration Kit available for download from Microsoft. + </para> -<para> -Remember: NT4 policy files are named <filename>NTConfig.POL</filename> and are stored in the root -of the NETLOGON share on the domain controllers. A Windows NT4 user enters a username, a password -and selects the domain name to which the logon will attempt to take place. During the logon -process the client machine reads the NTConfig.POL file from the NETLOGON share on the authenticating -server, modifies the local registry values according to the settings in this file. -</para> + <sect3> + <title>Registry Spoiling</title> -<para> -Windows 2K GPOs are very feature rich. They are NOT stored in the NETLOGON share, rather part of -a Windows 200x policy file is stored in the Active Directory itself and the other part is stored -in a shared (and replicated) volume called the SYSVOL folder. This folder is present on all Active -Directory domain controllers. The part that is stored in the Active Directory itself is called the -group policy container (GPC), and the part that is stored in the replicated share called SYSVOL is -known as the group policy template (GPT). -</para> + <para> + With NT4 style registry based policy changes, a large number of settings are not + automatically reversed as the user logs off. Since the settings that were in the + NTConfig.POL file were applied to the client machine registry and that apply to the + hive key HKEY_LOCAL_MACHINE are permanent until explicitly reversed. This is known + as tattooing. It can have serious consequences down-stream and the administrator must + be extremely careful not to lock out the ability to manage the machine at a later date. + </para> -<para> -With NT4 clients the policy file is read and executed upon only as each user logs onto the network. -MS Windows 200x policies are much more complex - GPOs are processed and applied at client machine -startup (machine specific part) and when the user logs onto the network the user specific part -is applied. In MS Windows 200x style policy management each machine and/or user may be subject -to any number of concurently applicable (and applied) policy sets (GPOs). Active Directory allows -the administrator to also set filters over the policy settings. No such equivalent capability -exists with NT4 style policy files. -</para> -<sect3> -<title>Administration of Win2K / XP Policies</title> + </sect3> + </sect2> + <sect2> + <title>MS Windows 200x / XP Professional Policies</title> -<title>Instructions</title> -<para> -Instead of using the tool called "The System Policy Editor", commonly called Poledit (from the -executable name poledit.exe), GPOs are created and managed using a Microsoft Management Console -(MMC) snap-in as follows:</para> -<procedure> -<step> -<para> -Go to the Windows 200x / XP menu <filename>Start->Programs->Administrative Tools</filename> - and select the MMC snap-in called "Active Directory Users and Computers" -</para> -</step> + <para> + Windows NT4 System policies allows setting of registry parameters specific to + users, groups and computers (client workstations) that are members of the NT4 + style domain. Such policy file will work with MS Windows 2000 / XP clients also. + </para> -<step><para> -Select the domain or organizational unit (OU) that you wish to manage, then right click -to open the context menu for that object, select the properties item. -</para></step> + <para> + New to MS Windows 2000 Microsoft introduced a new style of group policy that confers + a superset of capabilities compared with NT4 style policies. Obviously, the tool used + to create them is different, and the mechanism for implementing them is much changed. + </para> -<step><para> -Now left click on the Group Policy tab, then left click on the New tab. Type a name -for the new policy you will create. -</para></step> + <para> + The older NT4 style registry based policies are known as <emphasis>Administrative Templates</emphasis> + in MS Windows 2000/XP Group Policy Objects (GPOs). The later includes ability to set various security + configurations, enforce Internet Explorer browser settings, change and redirect aspects of the + users' desktop (including: the location of <filename>My Documents</filename> files (directory), as + well as intrinsics of where menu items will appear in the Start menu). An additional new + feature is the ability to make available particular software Windows applications to particular + users and/or groups. + </para> -<step><para> -Now left click on the Edit tab to commence the steps needed to create the GPO. -</para></step> -</procedure> + <para> + Remember: NT4 policy files are named <filename>NTConfig.POL</filename> and are stored in the root + of the NETLOGON share on the domain controllers. A Windows NT4 user enters a username, a password + and selects the domain name to which the logon will attempt to take place. During the logon + process the client machine reads the NTConfig.POL file from the NETLOGON share on the authenticating + server, modifies the local registry values according to the settings in this file. + </para> -<para> -All policy configuration options are controlled through the use of policy administrative -templates. These files have a .adm extension, both in NT4 as well as in Windows 200x / XP. -Beware however, since the .adm files are NOT interchangible across NT4 and Windows 200x. -The later introduces many new features as well as extended definition capabilities. It is -well beyond the scope of this documentation to explain how to program .adm files, for that -the adminsitrator is referred to the Microsoft Windows Resource Kit for your particular -version of MS Windows. -</para> + <para> + Windows 2K GPOs are very feature rich. They are NOT stored in the NETLOGON share, rather part of + a Windows 200x policy file is stored in the Active Directory itself and the other part is stored + in a shared (and replicated) volume called the SYSVOL folder. This folder is present on all Active + Directory domain controllers. The part that is stored in the Active Directory itself is called the + group policy container (GPC), and the part that is stored in the replicated share called SYSVOL is + known as the group policy template (GPT). + </para> -<note> -<para> -The MS Windows 2000 Resource Kit contains a tool called gpolmig.exe. This tool can be used -to migrate an NT4 NTConfig.POL file into a Windows 200x style GPO. Be VERY careful how you -use this powerful tool. Please refer to the resource kit manuals for specific usage information. -</para> -</note> + <para> + With NT4 clients the policy file is read and executed upon only as each user logs onto the network. + MS Windows 200x policies are much more complex - GPOs are processed and applied at client machine + startup (machine specific part) and when the user logs onto the network the user specific part + is applied. In MS Windows 200x style policy management each machine and/or user may be subject + to any number of concurently applicable (and applied) policy sets (GPOs). Active Directory allows + the administrator to also set filters over the policy settings. No such equivalent capability + exists with NT4 style policy files. + </para> -</sect3> -</sect2> + <sect3> + <title>Administration of Win2K / XP Policies</title> + + <para> + Instead of using the tool called <application>The System Policy Editor</application>, commonly called Poledit (from the + executable name <command>poledit.exe</command>), <acronym>GPOs</acronym> are created and managed using a + <application>Microsoft Management Console</application> <acronym>(MMC)</acronym> snap-in as follows:</para> + <procedure> + <step> + <para> + Go to the Windows 200x / XP menu <guimenu>Start->Programs->Administrative Tools</guimenu> + and select the MMC snap-in called <guimenuitem>Active Directory Users and Computers</guimenuitem> + </para> + </step> + + <step><para> + Select the domain or organizational unit (OU) that you wish to manage, then right click + to open the context menu for that object, select the properties item. + </para></step> + + <step><para> + Now left click on the <guilabel>Group Policy</guilabel> tab, then left click on the New tab. Type a name + for the new policy you will create. + </para></step> + + <step><para> + Now left click on the <guilabel>Edit</guilabel> tab to commence the steps needed to create the GPO. + </para></step> + </procedure> + + <para> + All policy configuration options are controlled through the use of policy administrative + templates. These files have a .adm extension, both in NT4 as well as in Windows 200x / XP. + Beware however, since the .adm files are NOT interchangible across NT4 and Windows 200x. + The later introduces many new features as well as extended definition capabilities. It is + well beyond the scope of this documentation to explain how to program .adm files, for that + the adminsitrator is referred to the Microsoft Windows Resource Kit for your particular + version of MS Windows. + </para> + + <note> + <para> + The MS Windows 2000 Resource Kit contains a tool called gpolmig.exe. This tool can be used + to migrate an NT4 NTConfig.POL file into a Windows 200x style GPO. Be VERY careful how you + use this powerful tool. Please refer to the resource kit manuals for specific usage information. + </para> + </note> + + </sect3> + </sect2> </sect1> <sect1> @@ -272,7 +314,7 @@ applied to the user's part of the registry. <para> MS Windows 200x/XP clients that log onto an MS Windows Active Directory security domain may additionally, acquire policy settings through Group Policy Objects (GPOs) that are defined and stored in Active Directory -itself. The key benefit of using AS GPOs is that they impose no registry <emphasis>tatooing</emphasis> effect. +itself. The key benefit of using AS GPOs is that they impose no registry <emphasis>spoiling</emphasis> effect. This has considerable advanage compared with the use of NTConfig.POL (NT4) style policy updates. </para> @@ -293,27 +335,37 @@ Common restrictions that are frequently used includes: </simplelist> </para> -<sect2> -<title>With Windows NT4/200x</title> + <sect2> + <title>Samba Editreg Toolset</title> -<para> -The tools that may be used to configure these types of controls from the MS Windows environment are: -The NT4 User Manager for domains, the NT4 System and Group Policy Editor, the registry editor (regedt32.exe). -Under MS Windows 200x/XP this is done using the Microsoft Managment Console (MMC) with approapriate -"snap-ins", the registry editor, and potentially also the NT4 System and Group Policy Editor. -</para> -</sect2> + <para> + Describe in detail the benefits of <command>editreg</command> and how to use it. + </para> -<sect2> -<title>With a Samba PDC</title> + </sect2> -<para> -With a Samba Domain Controller, the new tools for managing of user account and policy information includes: -<filename>smbpasswd, pdbedit, net, rpcclient.</filename>. The administrator should read the -man pages for these tools and become familiar with their use. -</para> + <sect2> + <title>Windows NT4/200x</title> -</sect2> + <para> + The tools that may be used to configure these types of controls from the MS Windows environment are: + The NT4 User Manager for domains, the NT4 System and Group Policy Editor, the registry editor (regedt32.exe). + Under MS Windows 200x/XP this is done using the Microsoft Managment Console (MMC) with approapriate + "snap-ins", the registry editor, and potentially also the NT4 System and Group Policy Editor. + </para> + </sect2> + + <sect2> + <title>Samba PDC</title> + + <para> + With a Samba Domain Controller, the new tools for managing of user account and policy information includes: + <command>smbpasswd</command>, <command>pdbedit</command>, <command>net</command>, <command>rpcclient</command>. + The administrator should read the + man pages for these tools and become familiar with their use. + </para> + + </sect2> </sect1> <sect1> @@ -381,4 +433,32 @@ reboot and as part of the user logon: </orderedlist> </sect1> + +<sect1> +<title>Common Errors</title> + +<para> +Policy related problems can be very difficult to diagnose and even more difficult to rectify. The following +collection demonstrates only basic issues. +</para> + +<sect2> +<title>Policy Does Not Work</title> + +<para> +Question: We have created the <filename>config.pol</filename> file and put it in the <emphasis>NETLOGON</emphasis> share. +It has made no difference to our Win XP Pro machines, they just don't see it. IT worked fine with Win 98 but does not +work any longer since we upgraded to Win XP Pro. Any hints? +</para> + +<para> +<emphasis>ANSWER:</emphasis> Policy files are NOT portable between Windows 9x / Me and MS Windows NT4 / 200x / XP based +platforms. You need to use the NT4 Group Policy Editor to create a file called <filename>NTConfig.POL</filename> so that +it is in the correct format for your MS Windows XP Pro clients. +</para> + +</sect2> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/Portability.xml b/docs/docbook/projdoc/Portability.xml index 72c3d20547..9f1188e4a2 100644 --- a/docs/docbook/projdoc/Portability.xml +++ b/docs/docbook/projdoc/Portability.xml @@ -1,6 +1,8 @@ <chapter id="Portability"> <chapterinfo> &author.jelmer; + <!-- Some other people as well, but there were no author names in the text files + this file is based on--> </chapterinfo> <title>Portability</title> @@ -14,14 +16,14 @@ platform-specific information about compiling and using samba.</para> <para> HP's implementation of supplementary groups is, er, non-standard (for -hysterical reasons). There are two group files, /etc/group and -/etc/logingroup; the system maps UIDs to numbers using the former, but +hysterical reasons). There are two group files, <filename>/etc/group</filename> and +<filename>/etc/logingroup</filename>; the system maps UIDs to numbers using the former, but initgroups() reads the latter. Most system admins who know the ropes -symlink /etc/group to /etc/logingroup (hard link doesn't work for reasons -too stupid to go into here). initgroups() will complain if one of the -groups you're in in /etc/logingroup has what it considers to be an invalid -ID, which means outside the range [0..UID_MAX], where UID_MAX is (I think) -60000 currently on HP-UX. This precludes -2 and 65534, the usual 'nobody' +symlink <filename>/etc/group</filename> to <filename>/etc/logingroup</filename> +(hard link doesn't work for reasons too stupid to go into here). initgroups() will complain if one of the +groups you're in in <filename>/etc/logingroup</filename> has what it considers to be an invalid +ID, which means outside the range <constant>[0..UID_MAX]</constant>, where <constant>UID_MAX</constant> is (I think) +60000 currently on HP-UX. This precludes -2 and 65534, the usual <constant>nobody</constant> GIDs. </para> @@ -46,14 +48,15 @@ Samba. <title>SCO Unix</title> <para> -If you run an old version of SCO Unix then you may need to get important +If you run an old version of SCO Unix then you may need to get important TCP/IP patches for Samba to work correctly. Without the patch, you may encounter corrupt data transfers using samba. </para> <para> The patch you need is UOD385 Connection Drivers SLS. It is available from -SCO (ftp.sco.com, directory SLS, files uod385a.Z and uod385a.ltr.Z). +SCO (<ulink url="ftp://ftp.sco.com/">ftp.sco.com</ulink>, directory SLS, +files uod385a.Z and uod385a.ltr.Z). </para> </sect1> @@ -121,8 +124,10 @@ _seteuid: after creating the above files you then assemble them using </para> -<para><command>as seteuid.s</command></para> -<para><command>as setegid.s</command></para> +<screen> + <prompt>$ </prompt><userinput>as seteuid.s</userinput> + <prompt>$ </prompt><userinput>as setegid.s</userinput> +</screen> <para> that should produce the files <filename>seteuid.o</filename> and @@ -155,7 +160,7 @@ You should then remove the line: <para> By default RedHat Rembrandt-II during installation adds an -entry to /etc/hosts as follows: +entry to <filename>/etc/hosts</filename> as follows: <programlisting> 127.0.0.1 loopback "hostname"."domainname" </programlisting> @@ -209,8 +214,7 @@ has not been released yet. <para> The patch revision for 2.6 is 105181-34 -for 8 is 108528-19 -and for 9 is 112233-04 +for 8 is 108528-19 and for 9 is 112233-04 </para> <para> diff --git a/docs/docbook/projdoc/Problems.xml b/docs/docbook/projdoc/Problems.xml index eb43b63b63..59cfbe3a13 100644 --- a/docs/docbook/projdoc/Problems.xml +++ b/docs/docbook/projdoc/Problems.xml @@ -26,15 +26,15 @@ general SMB topics such as browsing.</para> <para> One of the best diagnostic tools for debugging problems is Samba itself. -You can use the -d option for both smbd and nmbd to specify what -'debug level' at which to run. See the man pages on smbd, nmbd and +You can use the <option>-d option</option> for both &smbd; and &nmbd; to specify what +<parameter>debug level</parameter> at which to run. See the man pages on smbd, nmbd and smb.conf for more information on debugging options. The debug level can range from 1 (the default) to 10 (100 for debugging passwords). </para> <para> Another helpful method of debugging is to compile samba using the -<command>gcc -g </command> flag. This will include debug +<userinput>gcc -g </userinput> flag. This will include debug information in the binaries and allow you to attach gdb to the running smbd / nmbd process. In order to attach gdb to an smbd process for an NT workstation, first get the workstation to make the @@ -51,10 +51,10 @@ typing in your password, you can attach gdb and continue. Some useful samba commands worth investigating: </para> -<itemizedlist> - <listitem><para>testparam | more</para></listitem> - <listitem><para>smbclient -L //{netbios name of server}</para></listitem> -</itemizedlist> +<screen> + <prompt>$ </prompt><userinput>testparam | more</userinput> + <prompt>$ </prompt><userinput>smbclient -L //{netbios name of server}</userinput> +</screen> <para> An SMB enabled version of tcpdump is available from @@ -91,18 +91,18 @@ NT Server 4.0 Install CD and the Workstation 4.0 Install CD. </para> <para> -Initially you will need to install 'Network Monitor Tools and Agent' +Initially you will need to install <application>Network Monitor Tools and Agent</application> on the NT Server. To do this </para> <itemizedlist> - <listitem><para>Goto Start - Settings - Control Panel - - Network - Services - Add </para></listitem> + <listitem><para>Goto <guibutton>Start</guibutton> - <guibutton>Settings</guibutton> - <guibutton>Control Panel</guibutton> - + <guibutton>Network</guibutton> - <guibutton>Services</guibutton> - <guibutton>Add</guibutton> </para></listitem> - <listitem><para>Select the 'Network Monitor Tools and Agent' and - click on 'OK'.</para></listitem> + <listitem><para>Select the <guilabel>Network Monitor Tools and Agent</guilabel> and + click on <guibutton>OK</guibutton>.</para></listitem> - <listitem><para>Click 'OK' on the Network Control Panel. + <listitem><para>Click <guibutton>OK</guibutton> on the Network Control Panel. </para></listitem> <listitem><para>Insert the Windows NT Server 4.0 install CD @@ -124,13 +124,13 @@ install CD. </para> <itemizedlist> - <listitem><para>Goto Start - Settings - Control Panel - - Network - Services - Add</para></listitem> + <listitem><para>Goto <guibutton>Start</guibutton> - <guibutton>Settings</guibutton> - <guibutton>Control Panel</guibutton> - + <guibutton>Network</guibutton> - <guibutton>Services</guibutton> - <guibutton>Add</guibutton></para></listitem> - <listitem><para>Select the 'Network Monitor Agent' and click - on 'OK'.</para></listitem> + <listitem><para>Select the <guilabel>Network Monitor Agent</guilabel> and click + on <guibutton>OK</guibutton>.</para></listitem> - <listitem><para>Click 'OK' on the Network Control Panel. + <listitem><para>Click <guibutton>OK</guibutton> on the Network Control Panel. </para></listitem> <listitem><para>Insert the Windows NT Workstation 4.0 install @@ -138,15 +138,15 @@ install CD. </itemizedlist> <para> -Now copy the files from the NT Server in %SYSTEMROOT%\System32\netmon\*.* -to %SYSTEMROOT%\System32\netmon\*.* on the Workstation and set -permissions as you deem appropriate for your site. You will need +Now copy the files from the NT Server in <filename>%SYSTEMROOT%\System32\netmon\*.*</filename> +to <filename>%SYSTEMROOT%\System32\netmon\*.*</filename> on the Workstation and set +permissions as you deem appropriate for your site. You will need administrative rights on the NT box to run netmon. </para> <para> To install Netmon on a Windows 9x box install the network monitor agent -from the Windows 9x CD (\admin\nettools\netmon). There is a readme +from the Windows 9x CD (<filename>\admin\nettools\netmon</filename>). There is a readme file located with the netmon driver files on the CD if you need information on how to do this. Copy the files from a working Netmon installation. @@ -158,32 +158,16 @@ Netmon installation. <title>Useful URL's</title> <itemizedlist> -<listitem><para>Home of Samba site <ulink url="http://samba.org"> - http://samba.org</ulink>. We have a mirror near you !</para></listitem> - -<listitem><para> The <emphasis>Development</emphasis> document -on the Samba mirrors might mention your problem. If so, -it might mean that the developers are working on it.</para></listitem> - <listitem><para>See how Scott Merrill simulates a BDC behavior at <ulink url="http://www.skippy.net/linux/smb-howto.html"> http://www.skippy.net/linux/smb-howto.html</ulink>. </para></listitem> -<listitem><para>Although 2.0.7 has almost had its day as a PDC, David Bannon will - keep the 2.0.7 PDC pages at <ulink url="http://bioserve.latrobe.edu.au/samba"> - http://bioserve.latrobe.edu.au/samba</ulink> going for a while yet.</para></listitem> - -<listitem><para>Misc links to CIFS information - <ulink url="http://samba.org/cifs/">http://samba.org/cifs/</ulink></para></listitem> - -<listitem><para>NT Domains for Unix <ulink url="http://mailhost.cb1.com/~lkcl/ntdom/"> - http://mailhost.cb1.com/~lkcl/ntdom/</ulink></para></listitem> - <listitem><para>FTP site for older SMB specs: <ulink url="ftp://ftp.microsoft.com/developr/drg/CIFS/"> ftp://ftp.microsoft.com/developr/drg/CIFS/</ulink></para></listitem> </itemizedlist> +<!-- FIXME: Merge with Further Resources --> </sect1> diff --git a/docs/docbook/projdoc/ProfileMgmt.xml b/docs/docbook/projdoc/ProfileMgmt.xml index 140dd44ba1..fc51b1826c 100644 --- a/docs/docbook/projdoc/ProfileMgmt.xml +++ b/docs/docbook/projdoc/ProfileMgmt.xml @@ -7,6 +7,30 @@ <title>Desktop Profile Management</title> <sect1> +<title>Features and Benefits</title> + +<para> +Roaming Profiles are feared by some, hated by a few, loved by many, and a Godsend for +some administrators. +</para> + +<para> +Roaming Profiles allow an administrator to make available a consistent user desktop +as the user moves from one machine to another. This chapter provides much information +regarding how to configure and manage Roaming Profiles. +</para> + +<para> +While Roaming Profiles might sound like nirvana to some, they are a real and tangible +problem to others. In particular, users of mobile computing tools, where often there may not +be a sustained network connection, are often better served by purely Local Profiles. +This chapter provides information to help the Samba administrator to deal with those +situations also. +</para> + +</sect1> + +<sect1> <title>Roaming Profiles</title> <warning> @@ -62,17 +86,18 @@ where %L translates to the name of the Samba server and %u translates to the use </para> <para> -The default for this option is \\%N\%U\profile, namely \\sambaserver\username\profile. -The \\N%\%U service is created automatically by the [homes] service. If you are using +The default for this option is <filename>\\%N\%U\profile</filename>, +namely <filename>\\sambaserver\username\profile</filename>. +The <filename>\\N%\%U</filename> service is created automatically by the [homes] service. If you are using a samba server for the profiles, you _must_ make the share specified in the logon path -browseable. Please refer to the man page for smb.conf in respect of the different +browseable. Please refer to the man page for &smb.conf; in respect of the different symantics of %L and %N, as well as %U and %u. </para> <note> <para> MS Windows NT/2K clients at times do not disconnect a connection to a server -between logons. It is recommended to NOT use the <command>homes</command> +between logons. It is recommended to NOT use the <parameter>homes</parameter> meta-service name as part of the profile share path. </para> </note> @@ -82,7 +107,7 @@ meta-service name as part of the profile share path. <title>Windows 9x / Me User Profiles</title> <para> -To support Windows 9x / Me clients, you must use the "logon home" parameter. Samba has + To support Windows 9x / Me clients, you must use the <parameter>logon home</parameter> parameter. Samba has now been fixed so that <userinput>net use /home</userinput> now works as well, and it, too, relies on the <command>logon home</command> parameter. </para> @@ -90,7 +115,7 @@ on the <command>logon home</command> parameter. <para> By using the logon home parameter, you are restricted to putting Win9x / Me profiles in the user's home directory. But wait! There is a trick you -can use. If you set the following in the <command>[global]</command> section of your &smb.conf; file: +can use. If you set the following in the <parameter>[global]</parameter> section of your &smb.conf; file: </para> <para><programlisting> logon home = \\%L\%U\.profiles @@ -105,7 +130,7 @@ of your home directory called <filename>.profiles</filename> (thus making them h Not only that, but <userinput>net use /home</userinput> will also work, because of a feature in Windows 9x / Me. It removes any directory stuff off the end of the home directory area and only uses the server and share portion. That is, it looks like you -specified \\%L\%U for <command>logon home</command>. +specified <filename>\\%L\%U</filename> for <parameter>logon home</parameter>. </para> </sect3> @@ -114,7 +139,7 @@ specified \\%L\%U for <command>logon home</command>. <para> You can support profiles for both Win9X and WinNT clients by setting both the -<command>logon home</command> and <command>logon path</command> parameters. For example: +<parameter>logon home</parameter> and <parameter>logon path</parameter> parameters. For example: </para> <para><programlisting> @@ -127,27 +152,32 @@ You can support profiles for both Win9X and WinNT clients by setting both the <title>Disabling Roaming Profile Support</title> <para> -A question often asked is "How may I enforce use of local profiles?" or -"How do I disable Roaming Profiles?" + A question often asked is <quote>How may I enforce use of local profiles?</quote> or + <quote>How do I disable Roaming Profiles?</quote> </para> <para> There are three ways of doing this: </para> -<itemizedlist> - <listitem><para> - <command>In smb.conf:</command> affect the following settings and ALL clients - will be forced to use a local profile: - <programlisting> - logon home = - logon path = - </programlisting></para></listitem> - - <listitem><para> - <command>MS Windows Registry:</command> by using the Microsoft Management Console - gpedit.msc to instruct your MS Windows XP machine to use only a local profile. This - of course modifies registry settings. The full path to the option is: +<variablelist> + <varlistentry> + <term>In &smb.conf;</term> + <listitem><para> + Affect the following settings and ALL clients + will be forced to use a local profile: + <programlisting> + logon home = + logon path = + </programlisting> + </para></listitem> + </varlistentry> + + <varlistentry> + <term>MS Windows Registry:</term> + <listitem><para> + By using the Microsoft Management Console gpedit.msc to instruct your MS Windows XP machine to use only a local profile. This of course modifies registry settings. The full path to the option is: + <!-- FIXME: Diagram for this ? --> <programlisting> Local Computer Policy\ Computer Configuration\ @@ -158,15 +188,18 @@ There are three ways of doing this: Disable: Only Allow Local User Profiles Disable: Prevent Roaming Profile Change from Propogating to the Server </programlisting> - </para> - </listitem> + </para> </listitem> + </varlistentry> - <listitem><para> - <command>Change of Profile Type:</command> From the start menu right click on the - MY Computer icon, select <emphasis>Properties</emphasis>, click on the "<emphasis>User Profiles</emphasis> - tab, select the profile you wish to change from Roaming type to Local, click <emphasis>Change Type</emphasis>. - </para></listitem> -</itemizedlist> + <varlistentry> + <term>Change of Profile Type:</term> + <listitem><para> + From the start menu right click on the + My Computer icon, select <guimenuitem>Properties</guimenuitem>, click on the <guilabel>User Profiles</guilabel> + tab, select the profile you wish to change from Roaming type to Local, click <guibutton>Change Type</guibutton>. + </para></listitem> + </varlistentry> +</variablelist> <para> Consult the MS Windows registry guide for your particular MS Windows version for more @@ -191,12 +224,13 @@ Microsoft MS Windows Resource Kit for your version of Windows for specific infor <para> When a user first logs in on Windows 9X, the file user.DAT is created, -as are folders "Start Menu", "Desktop", "Programs" and "Nethood". +as are folders <filename>Start Menu</filename>, <filename>Desktop</filename>, +<filename>Programs</filename> and <filename>Nethood</filename>. These directories and their contents will be merged with the local -versions stored in c:\windows\profiles\username on subsequent logins, -taking the most recent from each. You will need to use the [global] -options "preserve case = yes", "short preserve case = yes" and -"case sensitive = no" in order to maintain capital letters in shortcuts +versions stored in <filename>c:\windows\profiles\username</filename> on subsequent logins, +taking the most recent from each. You will need to use the <parameter>[global]</parameter> +options <parameter>preserve case = yes</parameter>, <parameter>short preserve case = yes</parameter> and +<parameter>case sensitive = no</parameter> in order to maintain capital letters in shortcuts in any of the profile folders. </para> @@ -209,19 +243,19 @@ and deny them write access to this file. <orderedlist> <listitem> <para> - On the Windows 9x / Me machine, go to Control Panel -> Passwords and - select the User Profiles tab. Select the required level of - roaming preferences. Press OK, but do _not_ allow the computer + On the Windows 9x / Me machine, go to <guimenu>Control Panel</guimenu> -> <guimenuitem>Passwords</guimenuitem> and + select the <guilabel>User Profiles</guilabel> tab. Select the required level of + roaming preferences. Press <guibutton>OK</guibutton>, but do _not_ allow the computer to reboot. </para> </listitem> <listitem> <para> - On the Windows 9x / Me machine, go to Control Panel -> Network -> - Client for Microsoft Networks -> Preferences. Select 'Log on to - NT Domain'. Then, ensure that the Primary Logon is 'Client for - Microsoft Networks'. Press OK, and this time allow the computer + On the Windows 9x / Me machine, go to <guimenu>Control Panel</guimenu> -> <guimenuitem>Network</guimenuitem> -> + <guimenuitem>Client for Microsoft Networks</guimenuitem> -> <guilabel>Preferences</guilabel>. Select <guilabel>Log on to + NT Domain</guilabel>. Then, ensure that the Primary Logon is <guilabel>Client for + Microsoft Networks</guilabel>. Press <guibutton>OK</guibutton>, and this time allow the computer to reboot. </para> </listitem> @@ -247,15 +281,15 @@ supports it), user name and user's password. <para> Once the user has been successfully validated, the Windows 9x / Me machine -will inform you that 'The user has not logged on before' and asks you -if you wish to save the user's preferences? Select 'yes'. +will inform you that <computeroutput>The user has not logged on before' and asks you + if you wish to save the user's preferences?</computeroutput> Select <guibutton>yes</guibutton>. </para> <para> Once the Windows 9x / Me client comes up with the desktop, you should be able -to examine the contents of the directory specified in the "logon path" -on the samba server and verify that the "Desktop", "Start Menu", -"Programs" and "Nethood" folders have been created. +to examine the contents of the directory specified in the <parameter>logon path</parameter> +on the samba server and verify that the <filename>Desktop</filename>, <filename>Start Menu</filename>, +<filename>Programs</filename> and <filename>Nethood</filename> folders have been created. </para> <para> @@ -286,32 +320,31 @@ they will be told that they are logging in "for the first time". <listitem> <para> instead of logging in under the [user, password, domain] dialog, - press escape. + press <guibutton>escape</guibutton>. </para> </listitem> <listitem> <para> - run the regedit.exe program, and look in: + run the <command>regedit.exe</command> program, and look in: </para> - <para> - HKEY_LOCAL_MACHINE\Windows\CurrentVersion\ProfileList + <para> + <filename>HKEY_LOCAL_MACHINE\Windows\CurrentVersion\ProfileList</filename> </para> <para> you will find an entry, for each user, of ProfilePath. Note the - contents of this key (likely to be c:\windows\profiles\username), + contents of this key (likely to be <filename>c:\windows\profiles\username</filename>), then delete the key ProfilePath for the required user. + </para> - [Exit the registry editor]. - - </para> + <para>[Exit the registry editor].</para> </listitem> - <listitem> - <para> - <emphasis>WARNING</emphasis> - before deleting the contents of the + <warning> + <para> + Before deleting the contents of the directory listed in the ProfilePath (this is likely to be <filename>c:\windows\profiles\username)</filename>, ask them if they have any important files stored on their desktop or in their start menu. @@ -324,11 +357,11 @@ they will be told that they are logging in "for the first time". system file) user.DAT in their profile directory, as well as the local "desktop", "nethood", "start menu" and "programs" folders. </para> - </listitem> + </warning> <listitem> <para> - search for the user's .PWL password-caching file in the c:\windows + search for the user's .PWL password-caching file in the <filename>c:\windows</filename> directory, and delete it. </para> </listitem> @@ -341,8 +374,8 @@ they will be told that they are logging in "for the first time". <listitem> <para> - check the contents of the profile path (see "logon path" described - above), and delete the user.DAT or user.MAN file for the user, + check the contents of the profile path (see <parameter>logon path</parameter> described + above), and delete the <filename>user.DAT</filename> or <filename>user.MAN</filename> file for the user, making a backup if required. </para> </listitem> @@ -351,7 +384,7 @@ they will be told that they are logging in "for the first time". <para> If all else fails, increase samba's debug log levels to between 3 and 10, -and / or run a packet trace program such as ethereal or netmon.exe, and +and / or run a packet trace program such as ethereal or <command>netmon.exe</command>, and look for error messages. </para> @@ -370,12 +403,12 @@ differences are with the equivalent samba trace. <para> When a user first logs in to a Windows NT Workstation, the profile NTuser.DAT is created. The profile location can be now specified -through the "logon path" parameter. +through the <parameter>logon path</parameter> parameter. </para> <para> There is a parameter that is now available for use with NT Profiles: -"logon drive". This should be set to <filename>H:</filename> or any other drive, and +<parameter>logon drive</parameter>. This should be set to <filename>H:</filename> or any other drive, and should be used in conjunction with the new "logon home" parameter. </para> @@ -389,23 +422,23 @@ for those situations where it might be created.) <para> In the profile directory, Windows NT4 creates more folders than Windows 9x / Me. -It creates "Application Data" and others, as well as "Desktop", "Nethood", -"Start Menu" and "Programs". The profile itself is stored in a file -NTuser.DAT. Nothing appears to be stored in the .PDS directory, and +It creates <filename>Application Data</filename> and others, as well as <filename>Desktop</filename>, <filename>Nethood</filename>, +<filename>Start Menu</filename> and <filename>Programs</filename>. The profile itself is stored in a file +<filename>NTuser.DAT</filename>. Nothing appears to be stored in the .PDS directory, and its purpose is currently unknown. </para> <para> -You can use the System Control Panel to copy a local profile onto +You can use the <application>System Control Panel</application> to copy a local profile onto a samba server (see NT Help on profiles: it is also capable of firing -up the correct location in the System Control Panel for you). The -NT Help file also mentions that renaming NTuser.DAT to NTuser.MAN +up the correct location in the <application>System Control Panel</application> for you). The +NT Help file also mentions that renaming <filename>NTuser.DAT</filename> to <filename>NTuser.MAN</filename> turns a profile into a mandatory one. </para> <para> The case of the profile is significant. The file must be called -NTuser.DAT or, for a mandatory profile, NTuser.MAN. +<filename>NTuser.DAT</filename> or, for a mandatory profile, <filename>NTuser.MAN</filename>. </para> </sect3> @@ -417,58 +450,58 @@ You must first convert the profile from a local profile to a domain profile on the MS Windows workstation as follows: </para> -<itemizedlist> - <listitem><para> - Log on as the LOCAL workstation administrator. - </para></listitem> +<procedure> + <step><para> + Log on as the <emphasis>LOCAL</emphasis> workstation administrator. + </para></step> - <listitem><para> - Right click on the 'My Computer' Icon, select 'Properties' - </para></listitem> + <step><para> + Right click on the <guiicon>My Computer</guiicon> Icon, select <guimenuitem>Properties</guimenuitem> + </para></step> - <listitem><para> - Click on the 'User Profiles' tab - </para></listitem> + <step><para> + Click on the <guilabel>User Profiles</guilabel> tab + </para></step> - <listitem><para> + <step><para> Select the profile you wish to convert (click on it once) - </para></listitem> + </para></step> - <listitem><para> - Click on the button 'Copy To' - </para></listitem> + <step><para> + Click on the button <guibutton>Copy To</guibutton> + </para></step> - <listitem><para> - In the "Permitted to use" box, click on the 'Change' button. - </para></listitem> + <step><para> + In the <guilabel>Permitted to use</guilabel> box, click on the <guibutton>Change</guibutton> button. + </para></step> - <listitem><para> + <step><para> Click on the 'Look in" area that lists the machine name, when you click here it will open up a selection box. Click on the domain to which the profile must be accessible. </para> <note><para>You will need to log on if a logon box opens up. Eg: In the connect - as: MIDEARTH\root, password: mypassword.</para></note> - </listitem> + as: <replaceable>MIDEARTH</replaceable>\root, password: <replaceable>mypassword</replaceable>.</para></note> + </step> - <listitem><para> + <step><para> To make the profile capable of being used by anyone select 'Everyone' - </para></listitem> + </para></step> - <listitem><para> - Click OK. The Selection box will close. - </para></listitem> + <step><para> + Click <guibutton>OK</guibutton>. The Selection box will close. + </para></step> - <listitem><para> - Now click on the 'Ok' button to create the profile in the path you + <step><para> + Now click on the <guibutton>Ok</guibutton> button to create the profile in the path you nominated. - </para></listitem> -</itemizedlist> + </para></step> +</procedure> <para> Done. You now have a profile that can be editted using the samba-3.0.0 -<filename>profiles</filename> tool. +<command>profiles</command> tool. </para> <note> @@ -479,16 +512,16 @@ storage of mail data. That keeps desktop profiles usable. </note> <note> -<itemizedlist> -<listitem><para> +<procedure> +<step><para> This is a security check new to Windows XP (or maybe only Windows XP service pack 1). It can be disabled via a group policy in Active Directory. The policy is:</para> -<para>"Computer Configuration\Administrative Templates\System\User -Profiles\Do not check for user ownership of Roaming Profile Folders"</para> +<para><filename>Computer Configuration\Administrative Templates\System\User +Profiles\Do not check for user ownership of Roaming Profile Folders</filename></para> -<para>...and it should be set to "Enabled". +<para>...and it should be set to <constant>Enabled</constant>. Does the new version of samba have an Active Directory analogue? If so, then you may be able to set the policy through this. </para> @@ -500,36 +533,35 @@ the following (N.B. I don't know for sure that this will work in the same way as a domain group policy): </para> -</listitem> +</step> -<listitem><para> +<step><para> On the XP workstation log in with an Administrator account. -</para></listitem> - - <listitem><para>Click: "Start", "Run"</para></listitem> - <listitem><para>Type: "mmc"</para></listitem> - <listitem><para>Click: "OK"</para></listitem> - - <listitem><para>A Microsoft Management Console should appear.</para></listitem> - <listitem><para>Click: File, "Add/Remove Snap-in...", "Add"</para></listitem> - <listitem><para>Double-Click: "Group Policy"</para></listitem> - <listitem><para>Click: "Finish", "Close"</para></listitem> - <listitem><para>Click: "OK"</para></listitem> - - <listitem><para>In the "Console Root" window:</para></listitem> - <listitem><para>Expand: "Local Computer Policy", "Computer Configuration",</para></listitem> - <listitem><para>"Administrative Templates", "System", "User Profiles"</para></listitem> - <listitem><para>Double-Click: "Do not check for user ownership of Roaming Profile</para></listitem> - <listitem><para>Folders"</para></listitem> - <listitem><para>Select: "Enabled"</para></listitem> - <listitem><para>Click: OK"</para></listitem> - - <listitem><para>Close the whole console. You do not need to save the settings (this +</para></step> + + <step><para>Click: <guimenu>Start</guimenu>, <guimenuitem>Run</guimenuitem></para></step> + <step><para>Type: <userinput>mmc</userinput></para></step> + <step><para>Click: <guibutton>OK</guibutton></para></step> + + <step><para>A Microsoft Management Console should appear.</para></step> + <step><para>Click: <guimenu>File</guimenu>, <guimenuitem>Add/Remove Snap-in...</guimenuitem>, <guimenuitem>Add</guimenuitem></para></step> + <step><para>Double-Click: <guiicon>Group Policy</guiicon></para></step> + <step><para>Click: <guibutton>Finish</guibutton>, <guibutton>Close</guibutton></para></step> + <step><para>Click: <guibutton>OK</guibutton></para></step> + + <step><para>In the "Console Root" window:</para></step> + <step><para>Expand: <guiicon>Local Computer Policy</guiicon>, <guiicon>Computer Configuration</guiicon>, + <guiicon>Administrative Templates</guiicon>, <guiicon>System</guiicon>, <guiicon>User Profiles</guiicon></para></step> + <step><para>Double-Click: <guilabel>Do not check for user ownership of Roaming Profile Folders</guilabel></para></step> + <step><para>Select: <guilabel>Enabled</guilabel></para></step> + <step><para>Click: <guibutton>OK</guibutton></para></step> + + <step><para>Close the whole console. You do not need to save the settings (this refers to the console settings rather than the policies you have - changed).</para></listitem> + changed).</para></step> - <listitem><para>Reboot</para></listitem> -</itemizedlist> + <step><para>Reboot</para></step> +</procedure> </note> </sect3> </sect2> @@ -551,13 +583,13 @@ on again with the newer version of MS Windows. <para> If you then want to share the same Start Menu / Desktop with W9x/Me, you will need to specify a common location for the profiles. The smb.conf parameters -that need to be common are <emphasis>logon path</emphasis> and -<emphasis>logon home</emphasis>. +that need to be common are <parameter>logon path</parameter> and +<parameter>logon home</parameter>. </para> <para> -If you have this set up correctly, you will find separate user.DAT and -NTuser.DAT files in the same profile directory. +If you have this set up correctly, you will find separate <filename>user.DAT</filename> and +<filename>NTuser.DAT</filename> files in the same profile directory. </para> </sect2> @@ -584,14 +616,14 @@ NT4/200x. The correct resource kit is required for each platform. Here is a quick guide: </para> -<itemizedlist> +<procedure> -<listitem><para> -On your NT4 Domain Controller, right click on 'My Computer', then -select the tab labelled 'User Profiles'. -</para></listitem> +<step><para> +On your NT4 Domain Controller, right click on <guiicon>My Computer</guiicon>, then +select the tab labelled <guilabel>User Profiles</guilabel>. +</para></step> -<listitem><para> +<step><para> Select a user profile you want to migrate and click on it. </para> @@ -599,20 +631,20 @@ Select a user profile you want to migrate and click on it. create a group profile. You can give the user 'Everyone' rights to the profile you copy this to. That is what you need to do, since your samba domain is not a member of a trust relationship with your NT4 PDC.</para></note> -</listitem> +</step> - <listitem><para>Click the 'Copy To' button.</para></listitem> +<step><para>Click the <guibutton>Copy To</guibutton> button.</para></step> - <listitem><para>In the box labelled 'Copy Profile to' add your new path, eg: - <filename>c:\temp\foobar</filename></para></listitem> + <step><para>In the box labelled <guilabel>Copy Profile to</guilabel> add your new path, eg: + <filename>c:\temp\foobar</filename></para></step> - <listitem><para>Click on the button labelled 'Change' in the "Permitted to use" box.</para></listitem> + <step><para>Click on the button <guibutton>Change</guibutton> in the <guilabel>Permitted to use</guilabel> box.</para></step> - <listitem><para>Click on the group 'Everyone' and then click OK. This closes the - 'chose user' box.</para></listitem> + <step><para>Click on the group 'Everyone' and then click <guibutton>OK</guibutton>. This closes the + 'choose user' box.</para></step> - <listitem><para>Now click OK.</para></listitem> -</itemizedlist> + <step><para>Now click <guibutton>OK</guibutton>.</para></step> +</procedure> <para> Follow the above for every profile you need to migrate. @@ -657,7 +689,7 @@ Resource Kit. <para> Windows NT 4.0 stores the local profile information in the registry under the following key: -HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList +<filename>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList</filename> </para> <para> @@ -697,7 +729,7 @@ file in the copied profile and rename it to NTUser.MAN. </para> <para> -For MS Windows 9x / Me it is the User.DAT file that must be renamed to User.MAN to +For MS Windows 9x / Me it is the <filename>User.DAT</filename> file that must be renamed to <filename>User.MAN</filename> to affect a mandatory profile. </para> @@ -717,7 +749,7 @@ to the group profile. </para> <para> -The next step is rather important. PLEASE NOTE: Instead of assigning a group profile +The next step is rather important. <strong>Please note:</strong> Instead of assigning a group profile to users (ie: Using User Manager) on a "per user" basis, the group itself is assigned the now modified profile. </para> @@ -747,18 +779,19 @@ advantages. <title>MS Windows 9x/Me</title> <para> -To enable default per use profiles in Windows 9x / Me you can either use the Windows 98 System -Policy Editor or change the registry directly. +To enable default per use profiles in Windows 9x / Me you can either use the <application>Windows 98 System +Policy Editor</application> or change the registry directly. </para> <para> -To enable default per user profiles in Windows 9x / Me, launch the System Policy Editor, then -select File -> Open Registry, then click on the Local Computer icon, click on Windows 98 System, -select User Profiles, click on the enable box. Do not forget to save the registry changes. +To enable default per user profiles in Windows 9x / Me, launch the <application>System Policy Editor</application>, then +select <guimenu>File</guimenu> -> <guimenuitem>Open Registry</guimenuitem>, then click on the +<guiicon>Local Computer</guiicon> icon, click on <guilabel>Windows 98 System</guilabel>, +select <guilabel>User Profiles</guilabel>, click on the enable box. Do not forget to save the registry changes. </para> <para> -To modify the registry directly, launch the Registry Editor (regedit.exe), select the hive +To modify the registry directly, launch the <application>Registry Editor</application> (<command>regedit.exe</command>), select the hive <filename>HKEY_LOCAL_MACHINE\Network\Logon</filename>. Now add a DWORD type key with the name "User Profiles", to enable user profiles set the value to 1, to disable user profiles set it to 0. </para> @@ -798,7 +831,7 @@ profile, the changes are written to the user's profile on the server. On MS Windows NT4 the default user profile is obtained from the location <filename>%SystemRoot%\Profiles</filename> which in a default installation will translate to <filename>C:\WinNT\Profiles</filename>. Under this directory on a clean install there will be -three (3) directories: <filename>Administrator, All Users, Default User</filename>. +three (3) directories: <filename>Administrator</filename>, <filename>All Users</filename>, <filename>Default User</filename>. </para> <para> @@ -821,8 +854,8 @@ When a user logs onto an MS Windows NT4 machine that is a member of a Microsoft the following steps are followed in respect of profile handling: </para> -<orderedlist> - <listitem> +<procedure> + <step> <para> The users' account information which is obtained during the logon process contains the location of the users' desktop profile. The profile path may be local to the @@ -832,25 +865,25 @@ the following steps are followed in respect of profile handling: settings in the <filename>All Users</filename> profile in the <filename>%SystemRoot%\Profiles</filename> location. </para> - </listitem> + </step> - <listitem> + <step> <para> If the user account has a profile path, but at it's location a profile does not exist, then a new profile is created in the <filename>%SystemRoot%\Profiles\%USERNAME%</filename> directory from reading the <filename>Default User</filename> profile. </para> - </listitem> + </step> - <listitem> + <step> <para> If the NETLOGON share on the authenticating server (logon server) contains a policy file (<filename>NTConfig.POL</filename>) then it's contents are applied to the <filename>NTUser.DAT</filename> which is applied to the <filename>HKEY_CURRENT_USER</filename> part of the registry. </para> - </listitem> + </step> - <listitem> + <step> <para> When the user logs out, if the profile is set to be a roaming profile it will be written out to the location of the profile. The <filename>NTuser.DAT</filename> file is then @@ -859,8 +892,8 @@ the following steps are followed in respect of profile handling: next logon, the effect of the provious <filename>NTConfig.POL</filename> will still be held in the profile. The effect of this is known as <emphasis>tatooing</emphasis>. </para> - </listitem> -</orderedlist> + </step> +</procedure> <para> MS Windows NT4 profiles may be <emphasis>Local</emphasis> or <emphasis>Roaming</emphasis>. A Local profile @@ -892,59 +925,58 @@ are controlled by entries on Windows NT4 is: </para> <para> -<programlisting> - HKEY_CURRENT_USER - \Software - \Microsoft - \Windows - \CurrentVersion - \Explorer - \User Shell Folders\ -</programlisting> +<filename>HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders\</filename> </para> <para> The above hive key contains a list of automatically managed folders. The default entries are: </para> - <para> - <programlisting> - Name Default Value - -------------- ----------------------------------------- - AppData %USERPROFILE%\Application Data - Desktop %USERPROFILE%\Desktop - Favorites %USERPROFILE%\Favorites - NetHood %USERPROFILE%\NetHood - PrintHood %USERPROFILE%\PrintHood - Programs %USERPROFILE%\Start Menu\Programs - Recent %USERPROFILE%\Recent - SendTo %USERPROFILE%\SendTo - Start Menu %USERPROFILE%\Start Menu - Startup %USERPROFILE%\Start Menu\Programs\Startup - </programlisting> - </para> +<para> +<table frame="all"> + <title>User Shell Folder registry keys default values</title> + <tgroup cols="2"> + <thead> + <row><entry>Name</entry><entry>Default Value</entry></row> + </thead> + <tbody> + <row><entry>AppData</entry><entry>%USERPROFILE%\Application Data</entry></row> + <row><entry>Desktop</entry><entry>%USERPROFILE%\Desktop</entry></row> + <row><entry>Favorites</entry><entry>%USERPROFILE%\Favorites</entry></row> + <row><entry>NetHood</entry><entry>%USERPROFILE%\NetHood</entry></row> + <row><entry>PrintHood</entry><entry>%USERPROFILE%\PrintHood</entry></row> + <row><entry>Programs</entry><entry>%USERPROFILE%\Start Menu\Programs</entry></row> + <row><entry>Recent</entry><entry>%USERPROFILE%\Recent</entry></row> + <row><entry>SendTo</entry><entry>%USERPROFILE%\SendTo</entry></row> + <row><entry>Start Menu </entry><entry>%USERPROFILE%\Start Menu</entry></row> + <row><entry>Startup</entry><entry>%USERPROFILE%\Start Menu\Programs\Startup</entry></row> + </tbody> + </tgroup> +</table> +</para> <para> The registry key that contains the location of the default profile settings is: +</para> -<programlisting> - HKEY_LOCAL_MACHINE - \SOFTWARE - \Microsoft - \Windows - \CurrentVersion - \Explorer - \User Shell Folders -</programlisting> +<para> +<filename>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders</filename> +</para> +<para> The default entries are: -<programlisting> - Common Desktop %SystemRoot%\Profiles\All Users\Desktop - Common Programs %SystemRoot%\Profiles\All Users\Programs - Common Start Menu %SystemRoot%\Profiles\All Users\Start Menu - Common Startup %SystemRoot%\Profiles\All Users\Start Menu\Progams\Startup -</programlisting> +<table frame="all"> + <title>Defaults of profile settings registry keys</title> + <tgroup cols="2"> + <tbody> + <row><entry>Common Desktop</entry><entry>%SystemRoot%\Profiles\All Users\Desktop</entry></row> + <row><entry>Common Programs</entry><entry>%SystemRoot%\Profiles\All Users\Programs</entry></row> + <row><entry>Common Start Menu</entry><entry>%SystemRoot%\Profiles\All Users\Start Menu</entry></row> + <row><entry>Common Startup</entry><entry>%SystemRoot%\Profiles\All Users\Start Menu\Progams\Startup</entry></row> + </tbody> + </tgroup> +</table> </para> </sect2> @@ -981,7 +1013,7 @@ login name of the user. <note> <para> - This path translates, in Samba parlance, to the smb.conf [NETLOGON] share. The directory + This path translates, in Samba parlance, to the &smb.conf; <parameter>[NETLOGON]</parameter> share. The directory should be created at the root of this share and must be called <filename>Default Profile</filename>. </para> </note> @@ -1031,49 +1063,43 @@ are controlled by entries on Windows 200x/XP is: </para> <para> -<programlisting> - HKEY_CURRENT_USER - \Software - \Microsoft - \Windows - \CurrentVersion - \Explorer - \User Shell Folders\ -</programlisting> +<filename>HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders\</filename> </para> <para> The above hive key contains a list of automatically managed folders. The default entries are: </para> - <para> - <programlisting> - Name Default Value - -------------- ----------------------------------------- - AppData %USERPROFILE%\Application Data - Cache %USERPROFILE%\Local Settings\Temporary Internet Files - Cookies %USERPROFILE%\Cookies - Desktop %USERPROFILE%\Desktop - Favorites %USERPROFILE%\Favorites - History %USERPROFILE%\Local Settings\History - Local AppData %USERPROFILE%\Local Settings\Application Data - Local Settings %USERPROFILE%\Local Settings - My Pictures %USERPROFILE%\My Documents\My Pictures - NetHood %USERPROFILE%\NetHood - Personal %USERPROFILE%\My Documents - PrintHood %USERPROFILE%\PrintHood - Programs %USERPROFILE%\Start Menu\Programs - Recent %USERPROFILE%\Recent - SendTo %USERPROFILE%\SendTo - Start Menu %USERPROFILE%\Start Menu - Startup %USERPROFILE%\Start Menu\Programs\Startup - Templates %USERPROFILE%\Templates - </programlisting> - </para> +<para> +<table frame="all"> + <title>Defaults of default user profile paths registry keys</title> + <tgroup cols="2"> + <thead><row><entry>Name</entry><entry>Default Value</entry></row></thead> + <tbody> + <row><entry>AppData</entry><entry>%USERPROFILE%\Application Data</entry></row> + <row><entry>Cache</entry><entry>%USERPROFILE%\Local Settings\Temporary Internet Files</entry></row> + <row><entry>Cookies</entry><entry>%USERPROFILE%\Cookies</entry></row> + <row><entry>Desktop</entry><entry>%USERPROFILE%\Desktop</entry></row> + <row><entry>Favorites</entry><entry>%USERPROFILE%\Favorites</entry></row> + <row><entry>History</entry><entry>%USERPROFILE%\Local Settings\History</entry></row> + <row><entry>Local AppData</entry><entry>%USERPROFILE%\Local Settings\Application Data</entry></row> + <row><entry>Local Settings</entry><entry>%USERPROFILE%\Local Settings</entry></row> + <row><entry>My Pictures</entry><entry>%USERPROFILE%\My Documents\My Pictures</entry></row> + <row><entry>NetHood</entry><entry>%USERPROFILE%\NetHood</entry></row> + <row><entry>Personal</entry><entry>%USERPROFILE%\My Documents</entry></row> + <row><entry>PrintHood</entry><entry>%USERPROFILE%\PrintHood</entry></row> + <row><entry>Programs</entry><entry>%USERPROFILE%\Start Menu\Programs</entry></row> + <row><entry>Recent</entry><entry>%USERPROFILE%\Recent</entry></row> + <row><entry>SendTo</entry><entry>%USERPROFILE%\SendTo</entry></row> + <row><entry>Start Menu</entry><entry>%USERPROFILE%\Start Menu</entry></row> + <row><entry>Startup</entry><entry>%USERPROFILE%\Start Menu\Programs\Startup</entry></row> + <row><entry>Templates</entry><entry>%USERPROFILE%\Templates</entry></row> + </tbody></tgroup></table> +</para> <para> -There is also an entry called "Default" that has no value set. The default entry is of type REG_SZ, all -the others are of type REG_EXPAND_SZ. +There is also an entry called "Default" that has no value set. The default entry is of type <constant>REG_SZ</constant>, all +the others are of type <constant>REG_EXPAND_SZ</constant>. </para> <para> @@ -1084,21 +1110,20 @@ write the Outlook PST file over the network for every login and logout. <para> To set this to a network location you could use the following examples: +</para> -<programlisting> - %LOGONSERVER%\%USERNAME%\Default Folders -</programlisting> - -This would store the folders in the user's home directory under a directory called "Default Folders" +<para><filename>%LOGONSERVER%\%USERNAME%\Default Folders</filename></para> +<para> +This would store the folders in the user's home directory under a directory called <filename>Default Folders</filename> You could also use: +</para> -<programlisting> - \\SambaServer\FolderShare\%USERNAME% -</programlisting> +<para><filename>\\<replaceable>SambaServer</replaceable>\<replaceable>FolderShare</replaceable>\%USERNAME%</filename></para> -in which case the default folders will be stored in the server named <emphasis>SambaServer</emphasis> -in the share called <emphasis>FolderShare</emphasis> under a directory that has the name of the MS Windows +<para> + in which case the default folders will be stored in the server named <replaceable>SambaServer</replaceable> +in the share called <replaceable>FolderShare</replaceable> under a directory that has the name of the MS Windows user as seen by the Linux/Unix file system. </para> @@ -1112,12 +1137,9 @@ MS Windows 200x/XP profiles may be <emphasis>Local</emphasis> or <emphasis>Roami A roaming profile will be cached locally unless the following registry key is created: </para> -<para> -<programlisting> - HKEY_LOCAL_MACHINE\SYSTEM\Software\Microsoft\Windows NT\CurrentVersion\winlogon\ - "DeleteRoamingCache"=dword:00000001 -</programlisting> +<para><filename>HKEY_LOCAL_MACHINE\SYSTEM\Software\Microsoft\Windows NT\CurrentVersion\winlogon\"DeleteRoamingCache"=dword:00000001</filename></para> +<para> In which case, the local cache copy will be deleted on logout. </para> </sect2> @@ -1159,17 +1181,172 @@ In any case, you can configure only one profile per user. That profile can be either: </para> -<itemizedlist> - <listitem><para> - A profile unique to that user - </para></listitem> - <listitem><para> - A mandatory profile (one the user can not change) - </para></listitem> - <listitem><para> - A group profile (really should be mandatory ie:unchangable) - </para></listitem> -</itemizedlist> +<simplelist> + <member>A profile unique to that user</member> + <member>A mandatory profile (one the user can not change)</member> + <member>A group profile (really should be mandatory ie:unchangable)</member> +</simplelist> + +</sect2> + +<sect2> +<title>Can NOT use Roaming Profiles</title> + +<para> +<quote> + I dont want Roaming profile to be implemented, I just want to give users + local profiles only. +... + Please help me I am totally lost with this error from past two days I tried + everything and googled around quite a bit but of no help. Please help me. +</quote></para> + +<para> +Your choices are: +<!-- FIXME: Write to whole sentences --> + +<variablelist> + <varlistentry> + <term>Local profiles</term> + <listitem><para> + I know of no registry keys that will allow auto-deletion of LOCAL profiles on log out + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Roaming profiles</term> + <listitem><para> + <simplelist> + <member>can use auto-delete on logout option</member> + <member>requires a registry key change on workstation</member> + </simplelist> + + Your choices are: + + <variablelist> + <varlistentry> + <term>Personal Roaming profiles</term> + <listitem><para> + - should be preserved on a central server + - workstations 'cache' (store) a local copy + - used in case the profile can not be downloaded + at next logon + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Group profiles</term> + <listitem><para>- loaded from a cetral place</para></listitem> + </varlistentry> + + <varlistentry> + <term>Mandatory profiles</term> + <listitem><para> + - can be personal or group + - can NOT be changed (except by an administrator + </para></listitem> + </varlistentry> + </variablelist> + </para></listitem> + </varlistentry> +</variablelist> + +</para> + +<para> +A WinNT4/2K/XP profile can vary in size from 130KB to off the scale. +Outlook PST files are most often part of the profile and can be many GB in +size. On average (in a well controlled environment) roaming profie size of +2MB is a good rule of thumb to use for planning purposes. In an +undisciplined environment I have seen up to 2GB profiles. Users tend to +complain when it take an hour to log onto a workstation but they harvest +the fuits of folly (and ignorance). +</para> + +<para> +The point of all the above is to show that roaming profiles and good +controls of how they can be changed as well as good discipline make up for +a problem free site. +</para> + +<para> +Microsoft's answer to the PST problem is to store all email in an MS +Exchange Server back-end. But this is another story ...! +</para> + +<para> +So, having LOCAL profiles means: + +<simplelist> + <member>If lots of users user each machine - lot's of local disk storage needed for local profiles</member> + <member>Every workstation the user logs into has it's own profile - can be very different from machine to machine</member> +</simplelist> + +On the other hand, having roaming profiles means: +<simplelist> + <member>The network administrator can control EVERY aspect of user profiles</member> + <member>With the use of mandatory profiles - a drastic reduction in network management overheads</member> + <member>User unhappiness about not being able to change their profiles soon fades as they get used to being able to work reliably</member> +</simplelist> + +</para> + +<para> +I have managed and installed MANY NT/2K networks and have NEVER found one +where users who move from machine to machine are happy with local +profiles. In the long run local profiles bite them. +</para> + +</sect2> + +<!-- FIXME: Everything below this is a mess. I didn't quite understand it - Jelmer --> + +<sect2> + <title>Changing the default profile</title> + +<para><quote> +When the client tries to logon to the PDC it looks for a profile to download +where do I put this default profile. +</quote></para> + +<para> +Firstly, your samba server need to be configured as a domain controller. +</para> + +<programlisting> + server = user + os level = 32 (or more) + domain logons = Yes +</programlisting> + +<para> +Plus you need to have a <parameter>[netlogon]</parameter> share that is world readable. +It is a good idea to add a logon script to pre-set printer and +drive connections. There is also a facility for automatically +synchronizing the workstation time clock with that of the logon +server (another good thing to do). +</para> + +<note><para> +To invoke auto-deletion of roaming profile from the local +workstation cache (disk storage) you need to use the <application>Group Policy Editor</application> +to create a file called <filename>NTConfig.POL</filename> with the appropriate entries. This +file needs to be located in the <parameter>netlogon</parameter> share root directory.</para></note> + +<para> +Oh, of course the windows clients need to be members of the domain. +Workgroup machines do NOT do network logons - so they never see domain +profiles. +</para> + +<para> +Secondly, for roaming profiles you need: + + logon path = \\%N\profiles\%U (with some such path) + logon drive = H: (Z: is the default) + + Plus you need a PROFILES share that is world writable. +</para> </sect2> </sect1> diff --git a/docs/docbook/projdoc/SWAT.xml b/docs/docbook/projdoc/SWAT.xml index f238e8e1b0..e1702659f9 100644 --- a/docs/docbook/projdoc/SWAT.xml +++ b/docs/docbook/projdoc/SWAT.xml @@ -4,7 +4,7 @@ <pubdate>April 21, 2003</pubdate> </chapterinfo> -<title>SWAT - The Samba Web Admininistration Tool</title> +<title>SWAT - The Samba Web Administration Tool</title> <para> There are many and varied opinions regarding the usefulness or otherwise of SWAT. @@ -17,7 +17,7 @@ management. </para> <sect1> -<title>SWAT Features and Benefits</title> +<title>Features and Benefits</title> <para> There are network administrators who believe that it is a good idea to write systems @@ -25,7 +25,7 @@ documentation inside configuration files, for them SWAT will aways be a nasty to does not store the configuration file in any intermediate form, rather, it stores only the parameter settings, so when SWAT writes the smb.conf file to disk it will write only those parameters that are at other than the default settings. The result is that all comments -will be lost from the smb.conf file. Additionally, the parameters will be written back in +will be lost from the &smb.conf; file. Additionally, the parameters will be written back in internal ordering. </para> @@ -40,8 +40,8 @@ and only non-default settings will be written to the file. <para> SWAT should be installed to run via the network super daemon. Depending on which system -your Unix/Linux system has you will have either an <filename>inetd</filename> or -<filename>xinetd</filename> based system. +your Unix/Linux system has you will have either an <command>inetd</command> or +<command>xinetd</command> based system. </para> <para> @@ -86,7 +86,7 @@ A control file for the newer style xinetd could be: </para> <para> -Both the above examples assume that the <filename>swat</filename> binary has been +Both the above examples assume that the <command>swat</command> binary has been located in the <filename>/usr/sbin</filename> directory. In addition to the above SWAT will use a directory access point from which it will load it's help files as well as other control information. The default location for this on most Linux @@ -98,14 +98,16 @@ location using samba defaults will be <filename>/usr/local/samba/swat</filename> Access to SWAT will prompt for a logon. If you log onto SWAT as any non-root user the only permission allowed is to view certain aspects of configuration as well as access to the password change facility. The buttons that will be exposed to the non-root -user are: <emphasis>HOME, STATUS, VIEW, PASSWORD</emphasis>. The only page that allows -change capability in this case is <emphasis>PASSWORD</emphasis>. +user are: <guibutton>HOME</guibutton>, <guibutton>STATUS</guibutton>, <guibutton>VIEW</guibutton>, +<guibutton>PASSWORD</guibutton>. The only page that allows +change capability in this case is <guibutton>PASSWORD</guibutton>. </para> <para> -So long as you log onto SWAT as the user <command>root</command> you should obtain +So long as you log onto SWAT as the user <emphasis>root</emphasis> you should obtain full change and commit ability. The buttons that will be exposed includes: -<emphasis>HOME, GLOBALS, SHARES, PRINTERS, WIZARD, STATUS, VIEW, PASSWORD</emphasis>. +<guibutton>HOME</guibutton>, <guibutton>GLOBALS</guibutton>, <guibutton>SHARES</guibutton>, <guibutton>PRINTERS</guibutton>, +<guibutton>WIZARD</guibutton>, <guibutton>STATUS</guibutton>, <guibutton>VIEW</guibutton>, <guibutton>PASSWORD</guibutton>. </para> </sect2> @@ -122,35 +124,35 @@ administration of Samba. Here is a method that works, courtesy of Markus Krieger Modifications to the swat setup are as following: </para> -<itemizedlist> - <listitem><para> +<procedure> + <step><para> install OpenSSL - </para></listitem> + </para></step> - <listitem><para> + <step><para> generate certificate and private key - <programlisting> - root# /usr/bin/openssl req -new -x509 -days 365 -nodes -config \ - /usr/share/doc/packages/stunnel/stunnel.cnf \ - -out /etc/stunnel/stunnel.pem -keyout /etc/stunnel/stunnel.pem - </programlisting></para></listitem> + <screen> +&rootprompt;<userinput>/usr/bin/openssl req -new -x509 -days 365 -nodes -config \ + /usr/share/doc/packages/stunnel/stunnel.cnf \ + -out /etc/stunnel/stunnel.pem -keyout /etc/stunnel/stunnel.pem</userinput> + </screen></para></step> - <listitem><para> + <step><para> remove swat-entry from [x]inetd - </para></listitem> + </para></step> - <listitem><para> + <step><para> start stunnel - <programlisting> - root# stunnel -p /etc/stunnel/stunnel.pem -d 901 \ - -l /usr/local/samba/bin/swat swat - </programlisting></para></listitem> -</itemizedlist> + <screen> +&rootprompt;<userinput>stunnel -p /etc/stunnel/stunnel.pem -d 901 \ + -l /usr/local/samba/bin/swat swat </userinput> + </screen></para></step> +</procedure> <para> -afterwards simply contact to swat by using the URL "https://myhost:901", accept the certificate +afterwards simply contact to swat by using the URL <ulink url="https://myhost:901">https://myhost:901</ulink>, accept the certificate and the SSL connection is up. </para> @@ -173,13 +175,13 @@ useful is <command>ethereal</command>, available from <ulink url="http://www.eth http://www.ethereal.com</ulink>. </para> -<note><para> +<warning><para> SWAT can be configured to run in <emphasis>demo</emphasis> mode. This is NOT recommended as it runs SWAT without authentication and with full administrative ability. ie: Allows changes to smb.conf as well as general operation with root privilidges. The option that -creates this ability is the <command>-a</command> flag to swat. DO NOT USE THIS IN ANY -PRODUCTION ENVIRONMENT - you have been warned! -</para></note> +creates this ability is the <option>-a</option> flag to swat. <strong>Do not use this in any +production environment.</strong> +</para></warning> </sect2> @@ -193,16 +195,16 @@ in smb.conf. There are three levels of exposure of the parameters: <itemizedlist> <listitem><para> - <command>Basic</command> - exposes common configuration options. + <emphasis>Basic</emphasis> - exposes common configuration options. </para></listitem> <listitem><para> - <command>Advanced</command> - exposes configuration options needed in more + <emphasis>Advanced</emphasis> - exposes configuration options needed in more complex environments. </para></listitem> <listitem><para> - <command>Developer</command> - exposes configuration options that only the brave + <emphasis>Developer</emphasis> - exposes configuration options that only the brave will want to tamper with. </para></listitem> </itemizedlist> @@ -210,18 +212,18 @@ in smb.conf. There are three levels of exposure of the parameters: <para> To switch to other than <emphasis>Basic</emphasis> editing ability click on either the <emphasis>Advanced</emphasis> or the <emphasis>Developer</emphasis> dial, then click the -<emphasis>Commit Changes</emphasis> button. +<guibutton>Commit Changes</guibutton> button. </para> <para> After making any changes to configuration parameters make sure that you click on the -<emphasis>Commit Changes</emphasis> button before moving to another area otherwise +<guibutton>Commit Changes</guibutton> button before moving to another area otherwise your changes will be immediately lost. </para> <note><para> SWAT has context sensitive help. To find out what each parameter is for simply click the -<command>Help</command> link to the left of the configurartion parameter. +<guibutton>Help</guibutton> link to the left of the configurartion parameter. </para></note> </sect2> @@ -231,16 +233,16 @@ SWAT has context sensitive help. To find out what each parameter is for simply c <para> To affect a currenly configured share, simply click on the pull down button between the -<emphasis>Choose Share</emphasis> and the <emphasis>Delete Share</emphasis> buttons, +<guibutton>Choose Share</guibutton> and the <guibutton>Delete Share</guibutton> buttons, select the share you wish to operate on, then to edit the settings click on the -<emphasis>Choose Share</emphasis> button, to delete the share simply press the -<emphasis>Delete Share</emphasis> button. +<guibutton>Choose Share</guibutton> button, to delete the share simply press the +<guibutton>Delete Share</guibutton> button. </para> <para> -To create a new share, next to the button labelled <emphasis>Create Share</emphasis> enter +To create a new share, next to the button labelled <guibutton>Create Share</guibutton> enter into the text field the name of the share to be created, then click on the -<emphasis>Create Share</emphasis> button. +<guibutton>Create Share</guibutton> button. </para> </sect2> @@ -250,16 +252,16 @@ into the text field the name of the share to be created, then click on the <para> To affect a currenly configured printer, simply click on the pull down button between the -<emphasis>Choose Printer</emphasis> and the <emphasis>Delete Printer</emphasis> buttons, +<guibutton>Choose Printer</guibutton> and the <guibutton>Delete Printer</guibutton> buttons, select the printer you wish to operate on, then to edit the settings click on the -<emphasis>Choose Printer</emphasis> button, to delete the share simply press the -<emphasis>Delete Printer</emphasis> button. +<guibutton>Choose Printer</guibutton> button, to delete the share simply press the +<guibutton>Delete Printer</guibutton> button. </para> <para> -To create a new printer, next to the button labelled <emphasis>Create Printer</emphasis> enter +To create a new printer, next to the button labelled <guibutton>Create Printer</guibutton> enter into the text field the name of the share to be created, then click on the -<emphasis>Create Printer</emphasis> button. +<guibutton>Create Printer</guibutton> button. </para> </sect2> @@ -280,7 +282,7 @@ affected. </para> <para> -The <emphasis>Edit</emphasis> button permits the editing (setting) of the minimal set of +The <guibutton>Edit</guibutton> button permits the editing (setting) of the minimal set of options that may be necessary to create a working samba server. </para> @@ -298,7 +300,7 @@ home directories. <para> The status page serves a limited purpose. Firstly, it allows control of the samba daemons. -The key daemons that create the samba server environment are: <command> smbd, nmbd, winbindd</command>. +The key daemons that create the samba server environment are: &smbd;, &nmbd;, &winbindd;. </para> <para> @@ -319,7 +321,7 @@ free files that may be locked. <title>The View Page</title> <para> -This page allows the administrator to view the optimised smb.conf file and if you are +This page allows the administrator to view the optimised &smb.conf; file and if you are particularly massochistic will permit you also to see all possible global configuration parameters and their settings. </para> @@ -337,7 +339,7 @@ this tool to change a local password for a user account. <para> When logged in as a non-root account the user will have to provide the old password as well as -the new password (twice). When logged in as <command>root</command> only the new password is +the new password (twice). When logged in as <emphasis>root</emphasis> only the new password is required. </para> diff --git a/docs/docbook/projdoc/Samba-BDC-HOWTO.xml b/docs/docbook/projdoc/Samba-BDC-HOWTO.xml index 552834e929..b0cdf50b69 100644 --- a/docs/docbook/projdoc/Samba-BDC-HOWTO.xml +++ b/docs/docbook/projdoc/Samba-BDC-HOWTO.xml @@ -225,7 +225,7 @@ Server Manager for Domains. <para> Since version 2.2 Samba officially supports domain logons for all current Windows Clients, including Windows NT4, 2003 and XP Professional. For samba to be enabled as a PDC some -parameters in the [global]-section of the smb.conf have to be set: +parameters in the <parameter>[global]</parameter>-section of the &smb.conf; have to be set: </para> <para><programlisting> @@ -235,7 +235,7 @@ parameters in the [global]-section of the smb.conf have to be set: </programlisting></para> <para> -Several other things like a [homes] and a [netlogon] share also need to be set along with +Several other things like a <parameter>[homes]</parameter> and a <parameter>[netlogon]</parameter> share also need to be set along with settings for the profile path, the users home drive, etc.. This will not be covered in this chapter, for more information please refer to the chapter on Domain Control. </para> @@ -343,14 +343,13 @@ Finally, the BDC has to be found by the workstations. This can be done by settin </para> <para><programlisting> -<title>Essential Parameters for BDC Operation</title> workgroup = SAMBA domain master = no domain logons = yes </programlisting></para> <para> -in the [global]-section of the smb.conf of the BDC. This makes the BDC +in the <parameter>[global]</parameter>-section of the &smb.conf; of the BDC. This makes the BDC only register the name SAMBA<#1c> with the WINS server. This is no problem as the name SAMBA<#1c> is a NetBIOS group name that is meant to be registered by more than one machine. The parameter 'domain master = @@ -365,7 +364,7 @@ name is reserved for the Primary Domain Controller. <title>Common Errors</title> <para> -As this is a rather new area for Samba there are not many examples thta we may refer to. Keep +As this is a rather new area for Samba there are not many examples that we may refer to. Keep watching for updates to this section. </para> diff --git a/docs/docbook/projdoc/Samba-PDC-HOWTO.xml b/docs/docbook/projdoc/Samba-PDC-HOWTO.xml index e8c60c8d6d..af05b32e4a 100644 --- a/docs/docbook/projdoc/Samba-PDC-HOWTO.xml +++ b/docs/docbook/projdoc/Samba-PDC-HOWTO.xml @@ -39,15 +39,15 @@ sections of this HOWTO that deal with it. These are the most common causes of MS networking problems: </para> -<itemizedlist> - <listitem><para>Basic TCP/IP configuration</para></listitem> - <listitem><para>NetBIOS name resolution</para></listitem> - <listitem><para>Authentication configuration</para></listitem> - <listitem><para>User and Group configuration</para></listitem> - <listitem><para>Basic File and Directory Permission Control in Unix/Linux</para></listitem> - <listitem><para>Understanding of how MS Windows clients interoperate in a network - environment</para></listitem> -</itemizedlist> +<simplelist> + <member>Basic TCP/IP configuration</member> + <member>NetBIOS name resolution</member> + <member>Authentication configuration</member> + <member>User and Group configuration</member> + <member>Basic File and Directory Permission Control in Unix/Linux</member> + <member>Understanding of how MS Windows clients interoperate in a network + environment</member> +</simplelist> <para> Do not be put off, on the surface of it MS Windows networking seems so simple that any fool @@ -55,7 +55,7 @@ can do it. In fact, it is not a good idea to set up an MS Windows network with inadequate training and preparation. But let's get our first indelible principle out of the way: <emphasis>It is perfectly OK to make mistakes!</emphasis> In the right place and at the right time, mistakes are the essence of learning. It is <emphasis>very much</emphasis> -not Ok to make mistakes that cause loss of productivity and impose an avoidable financial +not ok to make mistakes that cause loss of productivity and impose an avoidable financial burden on an organisation. </para> @@ -106,7 +106,7 @@ The following functionalities are new to the Samba-3 release: <listitem><para> Adding users via the User Manager for Domains. This can be done on any MS Windows client using the Nexus toolkit that is available from Microsoft's web site. - At some later date Samba-3 may get support for the use of the Microsoft Manangement + At some later date Samba-3 may get support for the use of the Microsoft Management Console for user management. </para></listitem> @@ -164,6 +164,8 @@ user and machine trust account information in a suitable backend data store. Wit there can be multiple back-ends for this including: </para> +<!-- FIXME: Doesn't this belong in passdb.xml ? --> + <itemizedlist> <listitem><para> <emphasis>smbpasswd</emphasis> - the plain ascii file stored used by @@ -200,7 +202,7 @@ there can be multiple back-ends for this including: </itemizedlist> <para> -Read the chapter about the <link linkend="passdb">User Database</link> for details +Read the chapter about <link linkend="passdb">Account Information Database</link> for details regarding the choices available and how to configure them. </para> @@ -263,8 +265,8 @@ LDAP based user and machine account back end. New to Samba-3 is the ability to use a back-end database that holds the same type of data as the NT4 style SAM (Security Account Manager) database (one of the registry files). The samba-3 SAM can be specified via the smb.conf file parameter -<emphasis>passwd backend</emphasis> and valid options include -<emphasis>smbpasswd, tdbsam, ldapsam, nisplussam, xmlsam, mysqlsam, plugin, guest</emphasis>. +<parameter>passwd backend</parameter> and valid options include +<emphasis>smbpasswd, tdbsam, ldapsam, nisplussam, xmlsam, mysqlsam, guest</emphasis>. </para> <para> @@ -285,10 +287,10 @@ reinstall it. The install time choices offered are: </para> <itemizedlist> - <listitem><para>Primary Domain Controller - The one that seeds the domain SAM</para></listitem> - <listitem><para>Backup Domain Controller - One that obtains a copy of the domain SAM</para></listitem> - <listitem><para>Domain Member Server - One that has NO copy of the domain SAM, rather it obtains authentication from a Domain Controller for all access controls.</para></listitem> - <listitem><para>Stand-Alone Server - One that plays NO part is SAM synchronisation, has it's own authentication database and plays no role in Domain security.</para></listitem> + <listitem><para><emphasis>Primary Domain Controller</emphasis> - The one that seeds the domain SAM</para></listitem> + <listitem><para><emphasis>Backup Domain Controller</emphasis> - One that obtains a copy of the domain SAM</para></listitem> + <listitem><para><emphasis>Domain Member Server</emphasis> - One that has NO copy of the domain SAM, rather it obtains authentication from a Domain Controller for all access controls.</para></listitem> + <listitem><para><emphasis>Stand-Alone Server</emphasis> - One that plays NO part is SAM synchronisation, has it's own authentication database and plays no role in Domain security.</para></listitem> </itemizedlist> <para> @@ -329,14 +331,14 @@ other than the machine being configured so that the network configuration has a for it's workgroup entry. It is not uncommon for the name WORKGROUP to be used for this. With this mode of configuration there are NO machine trust accounts and any concept of membership as such is limited to the fact that all machines appear in the network neighbourhood to be logically -groupped together. Again, just to be clear: WORKGROUP MODE DOES NOT INVOLVE ANY SECURITY MACHINE -ACCOUNTS. +groupped together. Again, just to be clear: <strong>workgroup mode does not involve any security machine +accounts</strong>. </para> <para> Domain member machines have a machine account in the Domain accounts database. A special procedure must be followed on each machine to affect Domain membership. This procedure, which can be done -only by the local machine Adminisistrator account, will create the Domain machine account (if +only by the local machine Administrator account, will create the Domain machine account (if if does not exist), and then initializes that account. When the client first logs onto the Domain it triggers a machine password change. </para> @@ -353,81 +355,35 @@ The following are necessary for configuring Samba-3 as an MS Windows NT4 style P NT4 / 200x / XP clients. </para> -<orderedlist> - <listitem><para> - Configuration of basic TCP/IP and MS Windows Networking - </para></listitem> - - <listitem><para> - Correct designation of the Server Role (<emphasis>security = user</emphasis>) - </para></listitem> - - <listitem><para> - Consistent configuration of Name Resolution (See chapter on Browsing and on - MS Windows network Integration) - </para></listitem> - - <listitem><para> - Domain logons for Windows NT4 / 200x / XP Professional clients - </para></listitem> - - <listitem><para> - Configuration of Roaming Profiles or explicit configuration to force local profile usage - </para></listitem> - - <listitem><para> - Configuration of Network/System Policies - </para></listitem> - - <listitem><para> - Adding and managing domain user accounts - </para></listitem> - - <listitem><para> - Configuring MS Windows client machines to become domain members - </para></listitem> -</orderedlist> +<simplelist> + <member>Configuration of basic TCP/IP and MS Windows Networking</member> + <member>Correct designation of the Server Role (<parameter>security = user</parameter>)</member> + <member>Consistent configuration of Name Resolution (See <link linkend="NetworkBrowsing">chapter on Browsing</link> and on + <link linkend="integrate-ms-networks">MS Windows network Integration</link>)</member> + <member>Domain logons for Windows NT4 / 200x / XP Professional clients</member> + <member>Configuration of Roaming Profiles or explicit configuration to force local profile usage</member> + <member>Configuration of Network/System Policies</member> + <member>Adding and managing domain user accounts</member> + <member>Configuring MS Windows client machines to become domain members</member> +</simplelist> <para> The following provisions are required to serve MS Windows 9x / Me Clients: </para> -<orderedlist> - <listitem><para> - Configuration of basic TCP/IP and MS Windows Networking - </para></listitem> - - <listitem><para> - Correct designation of the Server Role (<emphasis>security = user</emphasis>) - </para></listitem> - - <listitem><para> - Network Logon Configuration (Since Windows 9x / XP Home are not technically domain - members, they do not really particpate in the security aspects of Domain logons as such) - </para></listitem> - - <listitem><para> - Roaming Profile Configuration - </para></listitem> - - <listitem><para> - Configuration of System Policy handling - </para></listitem> - - <listitem><para> - Installation of the Network driver "Client for MS Windows Networks" and configuration - to log onto the domain - </para></listitem> - - <listitem><para> - Placing Windows 9x / Me clients in user level security - if it is desired to allow - all client share access to be controlled according to domain user / group identities. - </para></listitem> - - <listitem><para> - Adding and managing domain user accounts - </para></listitem> -</orderedlist> +<simplelist> + <member>Configuration of basic TCP/IP and MS Windows Networking</member> + <member>Correct designation of the Server Role (<parameter>security = user</parameter>)</member> + <member>Network Logon Configuration (Since Windows 9x / XP Home are not technically domain + members, they do not really particpate in the security aspects of Domain logons as such)</member> + <member>Roaming Profile Configuration</member> + <member>Configuration of System Policy handling</member> + <member>Installation of the Network driver "Client for MS Windows Networks" and configuration + to log onto the domain</member> + <member>Placing Windows 9x / Me clients in user level security - if it is desired to allow + all client share access to be controlled according to domain user / group identities.</member> + <member>Adding and managing domain user accounts</member> +</simplelist> <note><para> Roaming Profiles and System/Network policies are advanced network administration topics @@ -557,12 +513,12 @@ There are a couple of points to emphasize in the above configuration. <itemizedlist> <listitem><para> Encrypted passwords must be enabled. For more details on how - to do this, refer to <link linkend="passdb">the User Database chapter</link>. + to do this, refer to <link linkend="passdb">Account Information Database chapter</link>. </para></listitem> <listitem><para> The server must support domain logons and have a - <filename>[netlogon]</filename> share + <parameter>[netlogon]</parameter> share </para></listitem> <listitem><para> @@ -602,8 +558,8 @@ an integral part of the essential functionality that is provided by a Domain Con <para> All Domain Controllers must run the netlogon service (<emphasis>domain logons</emphasis> -in Samba. One Domain Controller must be configured with <emphasis>domain master = Yes</emphasis> -(the Primary Domain Controller), on ALL Backup Domain Controllers <emphasis>domain master = No</emphasis> +in Samba. One Domain Controller must be configured with <parameter>domain master = Yes</parameter> +(the Primary Domain Controller), on ALL Backup Domain Controllers <parameter>domain master = No</parameter> must be set. </para> @@ -611,8 +567,6 @@ must be set. <title>Example Configuration</title> <programlisting> -<title> A minimal configuration to support Domain Logons</title> -<para> [globals] domain logons = Yes domain master = (Yes on PDC, No on BDCs) @@ -622,7 +576,6 @@ must be set. path = /var/lib/samba/netlogon guest ok = Yes browseable = No -</para> </programlisting> </sect3> @@ -710,7 +663,7 @@ worthwhile to look at how a Windows 9x/ME client performs a logon: a NetLogon request. This is sent to the NetBIOS name DOMAIN<#1c> at the NetBIOS layer. The client chooses the first response it receives, which contains the NetBIOS name of the logon server to use in the format of - \\SERVER. + <filename>\\SERVER</filename>. </para> </listitem> @@ -750,7 +703,7 @@ worthwhile to look at how a Windows 9x/ME client performs a logon: <para> The client then connects to the user's home share and searches for the user's profile. As it turns out, you can specify the user's home share as - a sharename and path. For example, \\server\fred\.winprofile. + a sharename and path. For example, <filename>\\server\fred\.winprofile</filename>. If the profiles are found, they are implemented. </para> </listitem> @@ -758,7 +711,7 @@ worthwhile to look at how a Windows 9x/ME client performs a logon: <listitem> <para> The client then disconnects from the user's home share, and reconnects to - the NetLogon share and looks for CONFIG.POL, the policies file. If this is + the NetLogon share and looks for <filename>CONFIG.POL</filename>, the policies file. If this is found, it is read and implemented. </para> </listitem> @@ -816,12 +769,12 @@ For this reason, it is very wise to configure the Samba DC as the DMB. <para> Now back to the issue of configuring a Samba DC to use a mode other -than <emphasis>security = user</emphasis>. If a Samba host is configured to use +than <parameter>security = user</parameter>. If a Samba host is configured to use another SMB server or DC in order to validate user connection requests, then it is a fact that some other machine on the network -(the <emphasis>password server</emphasis>) knows more about the user than the Samba host. +(the <parameter>password server</parameter>) knows more about the user than the Samba host. 99% of the time, this other host is a domain controller. Now -in order to operate in domain mode security, the <emphasis>workgroup</emphasis> parameter +in order to operate in domain mode security, the <parameter>workgroup</parameter> parameter must be set to the name of the Windows NT domain (which already has a domain controller). If the domain does NOT already have a Domain Controller then you do not yet have a Domain! @@ -830,7 +783,7 @@ then you do not yet have a Domain! <para> Configuring a Samba box as a DC for a domain that already by definition has a PDC is asking for trouble. Therefore, you should always configure the Samba DC -to be the DMB for its domain and set <emphasis>security = user</emphasis>. +to be the DMB for its domain and set <parameter>security = user</parameter>. This is the only officially supported mode of operation. </para> @@ -868,9 +821,9 @@ to a share (or IPC$) on the Samba PDC. The following command will remove all network drive connections: </para> -<para> -<prompt>C:\WINNT\></prompt> <command>net use * /d</command> -</para> +<screen> + <prompt>C:\WINNT\></prompt> <userinput>net use * /d</userinput> +</screen> <para> Further, if the machine is already a 'member of a workgroup' that @@ -884,9 +837,9 @@ does not matter what, reboot, and try again. <title>The system can not log you on (C000019B)....</title> <para>I joined the domain successfully but after upgrading -to a newer version of the Samba code I get the message, "The system +to a newer version of the Samba code I get the message, <errorname>The system can not log you on (C000019B), Please try again or consult your -system administrator" when attempting to logon. +system administrator</errorname> when attempting to logon. </para> <para> @@ -901,10 +854,10 @@ SID may be reset using either the net or rpcclient utilities. <para> The reset or change the domain SID you can use the net command as follows: -<programlisting> - net getlocalsid 'OLDNAME' - net setlocalsid 'SID' -</programlisting> +<screen> +<prompt>$ </prompt><userinput>net getlocalsid 'OLDNAME'</userinput> +<prompt>$ </prompt><userinput>net setlocalsid 'SID'</userinput> +</screen> </para> </sect2> @@ -914,8 +867,8 @@ The reset or change the domain SID you can use the net command as follows: exist or is not accessible.</title> <para> -When I try to join the domain I get the message "The machine account -for this computer either does not exist or is not accessible". What's +When I try to join the domain I get the message <errorname>The machine account +for this computer either does not exist or is not accessible</errorname>. What's wrong? </para> @@ -945,10 +898,18 @@ for both client and server. I get a message about my account being disabled.</title> <para> -At first be ensure to enable the useraccounts with <command>smbpasswd -e -%user%</command>, this is normally done, when you create an account. +Enable the user accounts with <userinput>smbpasswd -e <replaceable>username</replaceable> +</userinput>, this is normally done, as an account is created. </para> </sect2> + +<sect2> + <title>Until a few minutes after samba has started, clients get the error "Domain Controller Unavailable"</title> + <para> + A domain controller has to announce on the network who it is. This usually takes a while. + </para> +</sect2> + </sect1> </chapter> diff --git a/docs/docbook/projdoc/ServerType.xml b/docs/docbook/projdoc/ServerType.xml index ecfeb41735..a1a52b2545 100644 --- a/docs/docbook/projdoc/ServerType.xml +++ b/docs/docbook/projdoc/ServerType.xml @@ -97,17 +97,17 @@ different type of servers:</para> <itemizedlist> <listitem><para>Domain Controller</para> - <itemizedlist> - <listitem><para>Primary Domain Controller</para></listitem> - <listitem><para>Backup Domain Controller</para></listitem> - <listitem><para>ADS Domain Controller</para></listitem> - </itemizedlist> + <simplelist> + <member>Primary Domain Controller</member> + <member>Backup Domain Controller</member> + <member>ADS Domain Controller</member> + </simplelist> </listitem> <listitem><para>Domain Member Server</para> - <itemizedlist> - <listitem><para>Active Directory Member Server</para></listitem> - <listitem><para>NT4 Style Domain Member Server</para></listitem> - </itemizedlist> + <simplelist> + <member>Active Directory Member Server</member> + <member>NT4 Style Domain Member Server</member> + </simplelist> </listitem> <listitem><para>Stand Alone Server</para></listitem> </itemizedlist> @@ -125,7 +125,7 @@ presented. <title>Samba Security Modes</title> <para> -In this section the function and purpose of Samba's <emphasis>security</emphasis> +In this section the function and purpose of Samba's <parameter>security</parameter> modes are described. An acurate understanding of how Samba implements each security mode as well as how to configure MS Windows clients for each mode will significantly reduce user complaints and administrator heartache. @@ -136,14 +136,15 @@ There are in the SMB/CIFS networking world only two types of security: <emphasis and <emphasis>SHARE Level</emphasis>. We refer to these collectively as <emphasis>security levels</emphasis>. In implementing these two <emphasis>security levels</emphasis> samba provides flexibilities that are not available with Microsoft Windows NT4 / 200x servers. Samba knows of five (5) ways that allow the security levels to be implemented. In actual fact, Samba implements -<emphasis>SHARE Level</emphasis> security only one way, but has for ways of implementing +<emphasis>SHARE Level</emphasis> security only one way, but has four ways of implementing <emphasis>USER Level</emphasis> security. Collectively, we call the samba implementations -<emphasis>Security Modes</emphasis>. These are: <emphasis>SHARE, USER, DOMAIN, ADS, and SERVER</emphasis> +<emphasis>Security Modes</emphasis>. These are: <emphasis>SHARE</emphasis>, <emphasis>USER</emphasis>, <emphasis>DOMAIN</emphasis>, +<emphasis>ADS</emphasis>, and <emphasis>SERVER</emphasis> modes. They are documented in this chapter. </para> <para> -A SMB server tells the client at startup what <emphasis>security level</emphasis> +A SMB server tells the client at startup what <parameter>security level</parameter> it is running. There are two options <emphasis>share level</emphasis> and <emphasis>user level</emphasis>. Which of these two the client receives affects the way the client then tries to authenticate itself. It does not directly affect @@ -157,7 +158,7 @@ available and whether an action is allowed. <title>User Level Security</title> <para> -We will describe<emphasis>user level</emphasis> security first, as its simpler. +We will describe <parameter>user level</parameter> security first, as its simpler. In <emphasis>user level</emphasis> security the client will send a <emphasis>session setup</emphasis> command directly after the protocol negotiation. This contains a username and password. The server can either accept or reject that @@ -230,7 +231,7 @@ level security. They normally send a valid username but no password. Samba recor this username in a list of <emphasis>possible usernames</emphasis>. When the client then does a <emphasis>tree connection</emphasis> it also adds to this list the name of the share they try to connect to (useful for home directories) and any users -listed in the <command>user =</command> &smb.conf; line. The password is then checked +listed in the <parameter>user =</parameter> &smb.conf; line. The password is then checked in turn against these <emphasis>possible usernames</emphasis>. If a match is found then the client is authenticated as that user. </para> @@ -258,7 +259,7 @@ with share mode security servers. You are strongly discouraged from use of this <title>Domain Security Mode (User Level Security)</title> <para> -When samba is operating in <emphasis>security = domain</emphasis> mode this means that +When samba is operating in <parameter>security = domain</parameter> mode this means that the Samba server has a domain security trust account (a machine account) and will cause all authentication requests to be passed through to the domain controllers. </para> @@ -281,7 +282,7 @@ This method involves addition of the following parameters in the &smb.conf; file </programlisting></para> <para> -The use of the "*" argument to <command>password server</command> will cause samba to locate the +The use of the "*" argument to <parameter>password server</parameter> will cause samba to locate the domain controller in a way analogous to the way this is done within MS Windows NT. This is the default behaviour. </para> @@ -291,34 +292,32 @@ In order for this method to work the Samba server needs to join the MS Windows N security domain. This is done as follows: </para> -<itemizedlist> - <listitem><para>On the MS Windows NT domain controller using +<procedure> + <step><para>On the MS Windows NT domain controller using the Server Manager add a machine account for the Samba server. - </para></listitem> + </para></step> - <listitem><para>Next, on the Unix/Linux system execute:</para> - <para><programlisting> - <command>smbpasswd -r PDC_NAME -j DOMAIN_NAME</command> (samba 2.x) + <step><para>Next, on the Unix/Linux system execute:</para> + + <para>&rootprompt;<userinput>smbpasswd -r PDC_NAME -j DOMAIN_NAME</userinput> (samba 2.x)</para> - <command>net join -U administrator%password</command> (samba-3) - </programlisting> - </para> - </listitem> -</itemizedlist> + <para>&rootprompt;<userinput>net join -U administrator%password</userinput> (samba-3)</para> + </step> +</procedure> <note><para> As of Samba-2.2.4 the Samba 2.2.x series can auto-join a Windows NT4 style Domain just by executing: -<programlisting> - smbpasswd -j DOMAIN_NAME -r PDC_NAME -U Administrator%password -</programlisting> +<screen> +&rootprompt;<userinput>smbpasswd -j <replaceable>DOMAIN_NAME</replaceable> -r <replaceable>PDC_NAME</replaceable> -U Administrator%<replaceable>password</replaceable></userinput> +</screen> As of Samba-3 the same can be done by executing: -<programlisting> - net join -U Administrator%password -</programlisting> -It is not necessary with Samba-3 to specify the DOMAIN_NAME or the PDC_NAME as it figures this -out from the smb.conf file settings. +<screen> + &rootprompt;<userinput>net join -U Administrator%<replaceable>password</replaceable></userinput> +</screen> +It is not necessary with Samba-3 to specify the <replaceable>DOMAIN_NAME</replaceable> or the <replaceable>PDC_NAME</replaceable> as it +figures this out from the &smb.conf; file settings. </para></note> <para> @@ -362,17 +361,19 @@ AD-member mode can accept Kerberos. <sect3> <title>Example Configuration</title> -<para> -<programlisting> +<para><programlisting> realm = your.kerberos.REALM security = ADS encrypt passwords = Yes +</programlisting></para> -The following parameter may be required: +<para> + The following parameter may be required: +</para> +<para><programlisting> ads server = your.kerberos.server -</programlisting> -</para> +</programlisting></para> <para> Please refer to the Domain Membership section, Active Directory Membership for more information @@ -391,23 +392,23 @@ as a domain member server. It is highly recommended NOT to use this feature. Ser security has many draw backs. The draw backs include: </para> -<itemizedlist> - <listitem><para>Potential Account Lockout on MS Windows NT4/200x password servers</para></listitem> - <listitem><para>Lack of assurance that the password server is the one specified</para></listitem> - <listitem><para>Does not work with Winbind, particularly needed when storing profiles remotely</para></listitem> - <listitem><para>This mode may open connections to the password server, and keep them open for extended periods.</para></listitem> - <listitem><para>Security on the samba server breaks badly when the remote password server suddenly shuts down</para></listitem> - <listitem><para>With this mode there is NO security account in the domain that the password server belongs to for the samba server.</para></listitem> -</itemizedlist> +<simplelist> + <member>Potential Account Lockout on MS Windows NT4/200x password servers</member> + <member>Lack of assurance that the password server is the one specified</member> + <member>Does not work with Winbind, particularly needed when storing profiles remotely</member> + <member>This mode may open connections to the password server, and keep them open for extended periods.</member> + <member>Security on the samba server breaks badly when the remote password server suddenly shuts down</member> + <member>With this mode there is NO security account in the domain that the password server belongs to for the samba server.</member> +</simplelist> <para> In server level security the samba server reports to the client that it is in user level security. The client then does a <emphasis>session setup</emphasis> as described earlier. The samba server takes the username/password that the client sends and attempts to login to the -<emphasis>password server</emphasis> by sending exactly the same username/password that +<parameter>password server</parameter> by sending exactly the same username/password that it got from the client. If that server is in user level security and accepts the password then samba accepts the clients connection. This allows the samba server to use another SMB -server as the <emphasis>password server</emphasis>. +server as the <parameter>password server</parameter>. </para> <para> @@ -418,10 +419,10 @@ passwords in encrypted form. Samba supports this type of encryption by default. </para> <para> -The parameter <emphasis>security = server</emphasis> means that Samba reports to clients that +The parameter <parameter>security = server</parameter> means that Samba reports to clients that it is running in <emphasis>user mode</emphasis> but actually passes off all authentication requests to another <emphasis>user mode</emphasis> server. This requires an additional -parameter <emphasis>password server</emphasis> that points to the real authentication server. +parameter <parameter>password server</parameter> that points to the real authentication server. That real authentication server can be another Samba server or can be a Windows NT server, the later natively capable of encrypted password support. </para> @@ -589,7 +590,7 @@ to those for whom English is not their native tongue. <para> To some the nature of the samba <emphasis>security</emphasis> mode is very obvious, but entirely -wrong all the same. It is assumed that <emphasis>security = server</emphasis> means that Samba +wrong all the same. It is assumed that <parameter>security = server</parameter> means that Samba will act as a server. Not so! See above - this setting means that samba will <emphasis>try</emphasis> to use another SMB server as it's source of user authentication alone. </para> @@ -600,7 +601,7 @@ to use another SMB server as it's source of user authentication alone. <title>What makes Samba a Domain Controller?</title> <para> -The &smb.conf; parameter <emphasis>security = domain</emphasis> does NOT really make Samba behave +The &smb.conf; parameter <parameter>security = domain</parameter> does NOT really make Samba behave as a Domain Controller! This setting means we want samba to be a domain member! </para> @@ -610,12 +611,31 @@ as a Domain Controller! This setting means we want samba to be a domain member! <title>What makes Samba a Domain Member?</title> <para> -Guess! So many others do. But whatever you do, do NOT think that <emphasis>security = user</emphasis> +Guess! So many others do. But whatever you do, do NOT think that <parameter>security = user</parameter> makes Samba act as a domain member. Read the manufacturers manual before the warranty expires! </para> </sect2> + +<sect2> +<title>Constantly Losing Connections to Password Server</title> + +<para> +Why does server_validate() simply give up rather than re-establishing its connection to the +password server? Though I am not fluent in the SMB protocol, perhaps the cluster server +process passes along to its client workstation the session key it receives from the password +server, which means the password hashes submitted by the client would not work on a subsequent +connection, whose session key would be different. So server_validate() must give up. +</para> + +<para> +Indeed. That's why security = server is at best a nasty hack. Please use security = domain. +<parameter>security = server</parameter> mode is also known as pass-through authentication. +</para> + +</sect2> + </sect1> </chapter> diff --git a/docs/docbook/projdoc/Speed.xml b/docs/docbook/projdoc/Speed.xml index e2ede62ac7..6fa361d50c 100644 --- a/docs/docbook/projdoc/Speed.xml +++ b/docs/docbook/projdoc/Speed.xml @@ -9,9 +9,10 @@ </affiliation> </author> &author.jelmer; + &author.jht; </chapterinfo> -<title>Samba performance issues</title> +<title>Samba Performance Tuning</title> <sect1> <title>Comparisons</title> @@ -58,11 +59,11 @@ performance of a TCP based server like Samba. <para> The socket options that Samba uses are settable both on the command -line with the -O option, or in the smb.conf file. +line with the <option>-O</option> option, or in the &smb.conf; file. </para> <para> -The <command>socket options</command> section of the &smb.conf; manual page describes how +The <parameter>socket options</parameter> section of the &smb.conf; manual page describes how to set these and gives recommendations. </para> @@ -75,7 +76,7 @@ much. The correct settings are very dependent on your local network. <para> The socket option TCP_NODELAY is the one that seems to make the biggest single difference for most networks. Many people report that -adding <command>socket options = TCP_NODELAY</command> doubles the read +adding <parameter>socket options = TCP_NODELAY</parameter> doubles the read performance of a Samba drive. The best explanation I have seen for this is that the Microsoft TCP/IP stack is slow in sending tcp ACKs. </para> @@ -86,7 +87,7 @@ that the Microsoft TCP/IP stack is slow in sending tcp ACKs. <title>Read size</title> <para> -The option <command>read size</command> affects the overlap of disk +The option <parameter>read size</parameter> affects the overlap of disk reads/writes with network reads/writes. If the amount of data being transferred in several of the SMB commands (currently SMBwrite, SMBwriteX and SMBreadbraw) is larger than this value then the server begins writing @@ -114,9 +115,9 @@ pointless and will cause you to allocate memory unnecessarily. <title>Max xmit</title> <para> -At startup the client and server negotiate a <command>maximum transmit</command> size, +At startup the client and server negotiate a <parameter>maximum transmit</parameter> size, which limits the size of nearly all SMB commands. You can set the -maximum size that Samba will negotiate using the <command>max xmit = </command> option +maximum size that Samba will negotiate using the <parameter>max xmit = </parameter> option in &smb.conf;. Note that this is the maximum size of SMB requests that Samba will accept, but not the maximum size that the *client* will accept. The client maximum receive size is sent to Samba by the client and Samba @@ -139,7 +140,7 @@ In most cases the default is the best option. <title>Log level</title> <para> -If you set the log level (also known as <command>debug level</command>) higher than 2 +If you set the log level (also known as <parameter>debug level</parameter>) higher than 2 then you may suffer a large drop in performance. This is because the server flushes the log file after each operation, which can be very expensive. @@ -150,20 +151,20 @@ expensive. <title>Read raw</title> <para> -The <command>read raw</command> operation is designed to be an optimised, low-latency +The <parameter>read raw</parameter> operation is designed to be an optimised, low-latency file read operation. A server may choose to not support it, -however. and Samba makes support for <command>read raw</command> optional, with it +however. and Samba makes support for <parameter>read raw</parameter> optional, with it being enabled by default. </para> <para> -In some cases clients don't handle <command>read raw</command> very well and actually +In some cases clients don't handle <parameter>read raw</parameter> very well and actually get lower performance using it than they get using the conventional read operations. </para> <para> -So you might like to try <command>read raw = no</command> and see what happens on your +So you might like to try <parameter>read raw = no</parameter> and see what happens on your network. It might lower, raise or not affect your performance. Only testing can really tell. </para> @@ -174,14 +175,14 @@ testing can really tell. <title>Write raw</title> <para> -The <command>write raw</command> operation is designed to be an optimised, low-latency +The <parameter>write raw</parameter> operation is designed to be an optimised, low-latency file write operation. A server may choose to not support it, -however. and Samba makes support for <command>write raw</command> optional, with it +however. and Samba makes support for <parameter>write raw</parameter> optional, with it being enabled by default. </para> <para> -Some machines may find <command>write raw</command> slower than normal write, in which +Some machines may find <parameter>write raw</parameter> slower than normal write, in which case you may wish to change this option. </para> @@ -192,7 +193,7 @@ case you may wish to change this option. <para> Slow logins are almost always due to the password checking time. Using -the lowest practical <command>password level</command> will improve things. +the lowest practical <parameter>password level</parameter> will improve things. </para> </sect1> @@ -202,7 +203,7 @@ the lowest practical <command>password level</command> will improve things. <para> LDAP can be vastly improved by using the -<ulink url="smb.conf.5.html#LDAPTRUSTIDS">ldap trust ids</ulink> parameter. +<ulink url="smb.conf.5.html#LDAPTRUSTIDS"><parameter>ldap trust ids</parameter></ulink> parameter. </para> </sect1> @@ -219,4 +220,62 @@ performance. Check the sections on the various clients in </para> </sect1> + +<sect1> +<title>Samba performance problem due changing kernel (2.4.20 Linux kernel)</title> + +<para> +Hi everyone. I am running Gentoo on my server and samba 2.2.8a. Recently +I changed kernel version from linux-2.4.19-gentoo-r10 to +linux-2.4.20-wolk4.0s. And now I have performance issue with samba. Ok +many of you will probably say that move to vanilla sources...well I ried +it too and it didn't work. I have 100mb LAN and two computers (linux + +Windows2000). Linux server shares directory with DivX files, client +(windows2000) plays them via LAN. Before when I was running 2.4.19 kernel +everything was fine, but now movies freezes and stops...I tried moving +files between server and Windows and it's trerribly slow. +</para> + +<para> +Grab mii-tool and check the duplex settings on the NIC. +My guess is that it is a link layer issue, not an application +layer problem. Also run ifconfig and verify that the framing +error, collisions, etc... look normal for ethernet. +</para> + +</sect1> + +<sect1> +<title>Corrupt tdb Files</title> + +<para> +Well today it happend, our first major problem using samba. +Our samba PDC server has been hosting 3 TB of data to our 500+ users +[Windows NT/XP] for the last 3 years using samba, no problem. +But today all shares went SLOW; very slow. Also the main smbd kept +spawning new processes so we had 1600+ running smbd's (normally we avg. 250). +It crashed the SUN E3500 cluster twice. After alot of searching I +decided to <command>rm /var/locks/*.tbl</command>. Happy again. +</para> + +<para> +Q1) Is there any method of keeping the *.tbl files in top condition or +how to early detect corruption? +</para> + +<para> +A1) Yes, run <command>tdbbackup</command> each time after stoping nmbd and before starting nmbd. +</para> + +<para> +Q2) What I also would like to mention is that the service latency seems +alot lower then before the locks cleanup, any ideas on keeping it top notch? +</para> + +<para> +A2) Yes! Samba answer as for Q1! +</para> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/StandAloneServer.xml b/docs/docbook/projdoc/StandAloneServer.xml index d8f5992191..1b24e35272 100644 --- a/docs/docbook/projdoc/StandAloneServer.xml +++ b/docs/docbook/projdoc/StandAloneServer.xml @@ -72,7 +72,8 @@ 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 +(<filename>/etc/passwd</filename> or <filename>/etc/shadow</filename>), 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. </para> @@ -99,9 +100,7 @@ nobody. No home directories are shared, that are no users in the <filename>/etc/ Unix system database. This is a very simple system to administer. </para> -<para> <programlisting> - <title>Share Mode Read Only Stand-Alone Server</title> # Global parameters [global] workgroup = MYGROUP @@ -115,7 +114,6 @@ Unix system database. This is a very simple system to administer. path = /export guest only = Yes </programlisting> -</para> <para> In the above example the machine name is set to REFDOCS, the workgroup is set to the name @@ -172,9 +170,9 @@ the anonymous (guest) user two things will be required: The default for this is usually the account <command>nobody</command>. To find the correct name to use for your version of Samba do the following: - <programlisting> - testparm -s -v | grep "guest account" - </programlisting> + <screen> +<prompt>$ </prompt><userinput>testparm -s -v | grep "guest account"</userinput> + </screen> Then make sure that this account exists in your system password database (<filename>/etc/passwd</filename>). </para></listitem> @@ -183,17 +181,16 @@ the anonymous (guest) user two things will be required: The directory into which Samba will spool the file must have write access for the guest account. The following commands will ensure that this directory is available for use: - <programlisting> - mkdir /var/spool/samba - chown nobody.nobody /var/spool/samba - chmod a+rwt /var/spool/samba - </programlisting> + <screen> +&rootprompt;<userinput>mkdir /var/spool/samba</userinput> +&rootprompt;<userinput>chown nobody.nobody /var/spool/samba</userinput> +&rootprompt;<userinput>chmod a+rwt /var/spool/samba</userinput> + </screen> </para></listitem> </itemizedlist> <para> <programlisting> - <title>Simple Central Print Server</title> # Global parameters [global] workgroup = MYGROUP diff --git a/docs/docbook/projdoc/UNIX_INSTALL.xml b/docs/docbook/projdoc/UNIX_INSTALL.xml index 3dff9a5528..f305686915 100644 --- a/docs/docbook/projdoc/UNIX_INSTALL.xml +++ b/docs/docbook/projdoc/UNIX_INSTALL.xml @@ -33,7 +33,7 @@ <title>Configuring samba (smb.conf)</title> <para> - Samba's configuration is stored in the smb.conf file, + Samba's configuration is stored in the &smb.conf; file, that usually resides in <filename>/etc/samba/smb.conf</filename> or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either edit this file yourself or do it using one of the many graphical @@ -67,7 +67,7 @@ <para> This will allow connections by anyone with an account on the server, using either - their login name or "<command>homes</command>" as the service name. + their login name or "<parameter>homes</parameter>" as the service name. (Note that the workgroup that Samba must also be set.) </para> @@ -79,7 +79,7 @@ <para> For more information about security settings for the - <command>[homes]</command> share please refer to the chapter + <parameter>[homes]</parameter> share please refer to the chapter <link linkend="securing-samba">Securing Samba</link>. </para> @@ -88,7 +88,7 @@ <para> It's important that you test the validity of your <filename>smb.conf</filename> - file using the <application>testparm</application> program. If testparm runs OK + file using the &testparm; program. If testparm runs OK then it will list the loaded services. If not it will give an error message. </para> @@ -97,7 +97,7 @@ </para> <para> - Always run testparm again when you change <filename>smb.conf</filename>! + Always run testparm again when you change &smb.conf;! </para> </sect3> @@ -115,7 +115,7 @@ <para> To launch SWAT just run your favorite web browser and - point it at "http://localhost:901/". Replace + point it at <ulink url="http://localhost:901/">http://localhost:901/</ulink>. Replace <replaceable>localhost</replaceable> with the name of the computer you are running samba on if you are running samba on a different computer than your browser. @@ -160,7 +160,7 @@ would be the name of the host where you installed &smbd;. The <replaceable>aservice</replaceable> is any service you have defined in the &smb.conf; - file. Try your user name if you just have a <command>[homes]</command> + file. Try your user name if you just have a <parameter>[homes]</parameter> section in &smb.conf;.</para> @@ -212,19 +212,23 @@ The following questions and issues get raised on the samba mailing list over and <title>Why are so many smbd processes eating memory?</title> <para> +<quote> Site that is running Samba on an AIX box. They are sharing out about 2 terabytes using samba. Samba was installed using smitty and the binaries. We seem to be experiencing a memory problem -with this box. When I do a svmon -Pu the monitoring program shows that smbd has several +with this box. When I do a <command>svmon -Pu</command> the monitoring program shows that &smbd; has several processes of smbd running: +</quote> </para> <para> + <quote> Is samba suppose to start this many different smbd processes? Or does it run as one smbd process? Also is it normal for it to be taking up this much memory? +</quote> </para> <para> -<programlisting> +<screen> Inuse * 4096 = amount of memory being used by this process Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd @@ -251,34 +255,40 @@ Inuse * 4096 = amount of memory being used by this process 19110 smbd 8404 1906 181 4862 N N Total memory used: 841,592,832 bytes -</programlisting> +</screen> </para> <para> -<emphasis>ANSWER:</emphasis> Samba consists on three core programs: -<emphasis>nmbd, smbd, winbindd</emphasis>. <command>nmbd</command> is the name server message daemon, -<command>smbd</command> is the server message daemon, <command>winbind</command> is the daemon that +Samba consists on three core programs: +&nmbd;, &smbd;, &winbindd;. &nmbd; is the name server message daemon, +&smbd; is the server message daemon, &winbindd; is the daemon that handles communication with Domain Controllers. </para> <para> If your system is NOT running as a WINS server, then there will be one (1) single instance of - <command>nmbd</command> running on your system. If it is running as a WINS server then there will be + &nmbd; running on your system. If it is running as a WINS server then there will be two (2) instances - one to handle the WINS requests. </para> <para> -<command>smbd</command> handles ALL connection requests and then spawns a new process for each client +&smbd; handles ALL connection requests and then spawns a new process for each client connection made. That is why you are seeing so many of them, one (1) per client connection. </para> <para> -<command>winbindd</command> will run as one or two daemons, depending on whether or not it is being +&winbindd; will run as one or two daemons, depending on whether or not it is being run in "split mode" (in which case there will be two instances). </para> </sect2> + + <sect2> + <title>I'm getting "open_oplock_ipc: Failed to get local UDP socket for address 100007f. Error was Cannot assign requested" in the logs</title> + <para>Your loopback device isn't working correctly. Make sure it's running. </para> + </sect2> + </sect1> </chapter> diff --git a/docs/docbook/projdoc/VFS.xml b/docs/docbook/projdoc/VFS.xml index 225411b427..2ae1cfc9e0 100644 --- a/docs/docbook/projdoc/VFS.xml +++ b/docs/docbook/projdoc/VFS.xml @@ -9,34 +9,40 @@ <title>Stackable VFS modules</title> <sect1> -<title>Introduction and configuration</title> +<title>Features and Benefits</title> <para> -Since samba 3.0, samba supports stackable VFS(Virtual File System) modules. +Since Samba-3, there is support for stackable VFS(Virtual File System) modules. Samba passes each request to access the unix file system thru the loaded VFS modules. This chapter covers all the modules that come with the samba source and references to some external modules. </para> + +</sect1> + +<sect1> +<title>Discussion</title> + <para> -You may have problems to compile these modules, as shared libraries are -compiled and linked in different ways on different systems. -They currently have been tested against GNU/linux and IRIX. +If not supplied with your platform distribution binary Samba package you may have problems +to compile these modules, as shared libraries are compiled and linked in different ways +on different systems. They currently have been tested against GNU/Linux and IRIX. </para> <para> To use the VFS modules, create a share similar to the one below. The -important parameter is the <command>vfs object</command> parameter which must point to +important parameter is the <parameter>vfs object</parameter> parameter which must point to the exact pathname of the shared library objects. For example, to log all access to files and use a recycle bin: <programlisting> - [audit] - comment = Audited /data directory - path = /data - vfs object = /path/to/audit.so /path/to/recycle.so - writeable = yes - browseable = yes +[audit] + comment = Audited /data directory + path = /data + vfs object = /path/to/audit.so /path/to/recycle.so + writeable = yes + browseable = yes </programlisting> </para> @@ -54,117 +60,135 @@ the Samba Developers Guide. <sect1> <title>Included modules</title> -<sect2> -<title>audit</title> -<para>A simple module to audit file access to the syslog -facility. The following operations are logged: -<simplelist> -<member>share</member> -<member>connect/disconnect</member> -<member>directory opens/create/remove</member> -<member>file open/close/rename/unlink/chmod</member> -</simplelist> -</para> -</sect2> - -<sect2> -<title>extd_audit</title> -<para> -This module is identical with the <emphasis>audit</emphasis> module above except -that it sends audit logs to both syslog as well as the smbd log file/s. The -loglevel for this module is set in the smb.conf file. -</para> - -<para> -The logging information that will be written to the smbd log file is controlled by -the <emphasis>log level</emphasis> parameter in <filename>smb.conf</filename>. The -following information will be recorded: -</para> - -<table frame="all"><title>Extended Auditing Log Information</title> -<tgroup cols="2" align="center"> - <thead> - <row><entry align="center">Log Level</entry><entry>Log Details - File and Directory Operations</entry></row> - </thead> - <tbody> - <row><entry align="center">0</entry><entry align="left">Creation / Deletion</entry></row> - <row><entry align="center">1</entry><entry align="left">Create / Delete / Rename / Permission Changes</entry></row> - <row><entry align="center">2</entry><entry align="left">Create / Delete / Rename / Perm Change / Open / Close</entry></row> - </tbody> -</tgroup> -</table> - -</sect2> - -<sect2> -<title>recycle</title> -<para> -A recycle-bin like module. When used any unlink call -will be intercepted and files moved to the recycle -directory instead of being deleted. -</para> - -<para>Supported options: -<variablelist> - <varlistentry> - <term>vfs_recycle_bin:repository</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:keeptree</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:versions</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:touch</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:maxsize</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:exclude</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:exclude_dir</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> - - <varlistentry> - <term>vfs_recycle_bin:noversions</term> - <listitem><para>FIXME</para></listitem> - </varlistentry> -</variablelist> -</para> - -</sect2> - -<sect2> -<title>netatalk</title> -<para> -A netatalk module, that will ease co-existence of samba and -netatalk file sharing services. -</para> - -<para>Advantages compared to the old netatalk module: -<simplelist> -<member>it doesn't care about creating of .AppleDouble forks, just keeps them in sync</member> -<member>if share in smb.conf doesn't contain .AppleDouble item in hide or veto list, it will be added automatically</member> -</simplelist> -</para> - -</sect2> + <sect2> + <title>audit</title> + + <para> + A simple module to audit file access to the syslog + facility. The following operations are logged: + <simplelist> + <member>share</member> + <member>connect/disconnect</member> + <member>directory opens/create/remove</member> + <member>file open/close/rename/unlink/chmod</member> + </simplelist> + </para> + + </sect2> + + <sect2> + <title>extd_audit</title> + + <para> + This module is identical with the <emphasis>audit</emphasis> module above except + that it sends audit logs to both syslog as well as the smbd log file/s. The + loglevel for this module is set in the smb.conf file. + </para> + + <para> + The logging information that will be written to the smbd log file is controlled by + the <parameter>log level</parameter> parameter in <filename>smb.conf</filename>. The + following information will be recorded: + </para> + + <table frame="all"><title>Extended Auditing Log Information</title> + <tgroup cols="2" align="center"> + <thead> + <row><entry align="center">Log Level</entry><entry>Log Details - File and Directory Operations</entry></row> + </thead> + <tbody> + <row><entry align="center">0</entry><entry align="left">Creation / Deletion</entry></row> + <row><entry align="center">1</entry><entry align="left">Create / Delete / Rename / Permission Changes</entry></row> + <row><entry align="center">2</entry><entry align="left">Create / Delete / Rename / Perm Change / Open / Close</entry></row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>fake_perms</title> + + <para> + This module was created to allow Roaming Profile files and directories to be set (on the Samba server + under Unix) as read only. This module will if installed on the Profiles share will report to the client + that the Profile files and directories are writable. This satisfies the client even though the files + will never be overwritten as the client logs out or shuts down. + </para> + + </sect2> + + <sect2> + <title>recycle</title> + + <para> + A recycle-bin like module. When used any unlink call + will be intercepted and files moved to the recycle + directory instead of being deleted. + </para> + + <para>Supported options: + <variablelist> + <varlistentry> + <term>vfs_recycle_bin:repository</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:keeptree</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:versions</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:touch</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:maxsize</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:exclude</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:exclude_dir</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + + <varlistentry> + <term>vfs_recycle_bin:noversions</term> + <listitem><para>FIXME</para></listitem> + </varlistentry> + </variablelist> + </para> + + </sect2> + + <sect2> + <title>netatalk</title> + + <para> + A netatalk module, that will ease co-existence of samba and + netatalk file sharing services. + </para> + + <para>Advantages compared to the old netatalk module: + <simplelist> + <member>it doesn't care about creating of .AppleDouble forks, just keeps them in sync</member> + <member>if a share in &smb.conf; doesn't contain .AppleDouble item in hide or veto list, it will be added automatically</member> + </simplelist> + </para> + + </sect2> </sect1> @@ -179,52 +203,60 @@ to have his or her own CVS tree). </para> <para> -No statemets about the stability or functionality of any module +No statements about the stability or functionality of any module should be implied due to its presence here. </para> -<sect2> -<title>DatabaseFS</title> + <sect2> + <title>DatabaseFS</title> -<para> -URL: <ulink url="http://www.css.tayloru.edu/~elorimer/databasefs/index.php">http://www.css.tayloru.edu/~elorimer/databasefs/index.php</ulink> -</para> + <para> + URL: <ulink url="http://www.css.tayloru.edu/~elorimer/databasefs/index.php">http://www.css.tayloru.edu/~elorimer/databasefs/index.php</ulink> + </para> -<para>By <ulink url="mailto:elorimer@css.tayloru.edu">Eric Lorimer</ulink>.</para> + <para>By <ulink url="mailto:elorimer@css.tayloru.edu">Eric Lorimer</ulink>.</para> -<para> -I have created a VFS module which implements a fairly complete read-only -filesystem. It presents information from a database as a filesystem in -a modular and generic way to allow different databases to be used -(originally designed for organizing MP3s under directories such as -"Artists," "Song Keywords," etc... I have since applied it to a student -roster database very easily). The directory structure is stored in the -database itself and the module makes no assumptions about the database -structure beyond the table it requires to run. -</para> + <para> + I have created a VFS module which implements a fairly complete read-only + filesystem. It presents information from a database as a filesystem in + a modular and generic way to allow different databases to be used + (originally designed for organizing MP3s under directories such as + "Artists," "Song Keywords," etc... I have since applied it to a student + roster database very easily). The directory structure is stored in the + database itself and the module makes no assumptions about the database + structure beyond the table it requires to run. + </para> -<para> -Any feedback would be appreciated: comments, suggestions, patches, -etc... If nothing else, hopefully it might prove useful for someone -else who wishes to create a virtual filesystem. -</para> + <para> + Any feedback would be appreciated: comments, suggestions, patches, + etc... If nothing else, hopefully it might prove useful for someone + else who wishes to create a virtual filesystem. + </para> -</sect2> + </sect2> -<sect2> -<title>vscan</title> -<para>URL: <ulink url="http://www.openantivirus.org/">http://www.openantivirus.org/</ulink></para> + <sect2> + <title>vscan</title> -<para> -samba-vscan is a proof-of-concept module for Samba, which -uses the VFS (virtual file system) features of Samba 2.2.x/3.0 -alphaX. Of couse, Samba has to be compiled with VFS support. -samba-vscan supports various virus scanners and is maintained -by Rainer Link. -</para> + <para>URL: <ulink url="http://www.openantivirus.org/">http://www.openantivirus.org/</ulink></para> -</sect2> + <para> + samba-vscan is a proof-of-concept module for Samba, which + uses the VFS (virtual file system) features of Samba 2.2.x/3.0 + alphaX. Of couse, Samba has to be compiled with VFS support. + samba-vscan supports various virus scanners and is maintained + by Rainer Link. + </para> + </sect2> </sect1> +<sect1> +<title>Common Errors</title> + +<para> +There must be some gotchas we should record here! Jelmer??? +</para> + +</sect1> </chapter> diff --git a/docs/docbook/projdoc/WindowsClientConfig.xml b/docs/docbook/projdoc/WindowsClientConfig.xml new file mode 100644 index 0000000000..ea1d4d5aa3 --- /dev/null +++ b/docs/docbook/projdoc/WindowsClientConfig.xml @@ -0,0 +1,17 @@ +<chapter id="ClientConfig"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>MS Windows Network Configuration Guide</title> + +<sect1> +<title>Note</title> + +<para> +This chapter did not make it into this release. +It is planned for the published release of this document. +</para> + +</sect1> +</chapter> diff --git a/docs/docbook/projdoc/locking.xml b/docs/docbook/projdoc/locking.xml index 437f7756d9..8321680936 100644 --- a/docs/docbook/projdoc/locking.xml +++ b/docs/docbook/projdoc/locking.xml @@ -82,33 +82,34 @@ All other locks can not be seen by unix anyway. <para> Strictly a SMB server should check for locks before every read and write call on a file. Unfortunately with the way fcntl() works this can be slow and may overstress -the rpc.lockd. It is also almost always unnecessary as clients are supposed to +the <command>rpc.lockd</command>. It is also almost always unnecessary as clients are supposed to independently make locking calls before reads and writes anyway if locking is important to them. By default Samba only makes locking calls when explicitly asked -to by a client, but if you set <emphasis>strict locking = yes</emphasis> then it +to by a client, but if you set <parameter>strict locking = yes</parameter> then it will make lock checking calls on every read and write. </para> <para> -You can also disable by range locking completely using <emphasis>locking = no</emphasis>. +You can also disable by range locking completely using <parameter>locking = no</parameter>. This is useful for those shares that don't support locking or don't need it (such as cdroms). In this case Samba fakes the return codes of locking calls to tell clients that everything is OK. </para> <para> -The second class of locking is the <emphasis>deny modes</emphasis>. These +The second class of locking is the <parameter>deny modes</parameter>. These are set by an application when it opens a file to determine what types of 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. +<constant>DENY_NONE</constant>, <constant>DENY_READ</constant>, +<constant>DENY_WRITE</constant> or <constant>DENY_ALL</constant>. There are also special compatibility +modes called <constant>DENY_FCB</constant> and <constant>DENY_DOS</constant>. </para> <sect2> <title>Opportunistic Locking Overview</title> <para> -OPPORTUNISTIC LOCKING (Oplocks) is invoked by the Windows file system +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 @@ -129,7 +130,7 @@ locally on the client which allows: </varlistentry> <varlistentry><term>Lock caching:</term> - <listitem><para> + <listitem><para> The client caches application locks locally, eliminating network latency </para></listitem> </varlistentry> @@ -408,7 +409,7 @@ the share. <title>Beware of Force User</title> <para> -Samba includes an smb.conf parameter called "force user" that changes +Samba includes an &smb.conf; parameter called <parameter>force user</parameter> 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 @@ -425,7 +426,7 @@ Avoid the combination of the following: <itemizedlist> <listitem><para> - <emphasis>force user</emphasis> in the &smb.conf; share configuration. + <parameter>force user</parameter> in the &smb.conf; share configuration. </para></listitem> <listitem><para> @@ -447,8 +448,9 @@ 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: <emphasis>oplock break wait time, -oplock contention limit</emphasis>. +likely cause problems. The parameters are: +<parameter>oplock break wait time</parameter>, +<parameter>oplock contention limit</parameter>. </para> <para> @@ -622,7 +624,7 @@ you may want to play it safe and disable oplocks and level2 oplocks. </sect3> <sect3> -<title>Diabling Kernel OpLocks</title> +<title>Disabling Kernel OpLocks</title> <para> Kernel OpLocks is an &smb.conf; parameter that notifies Samba (if @@ -639,12 +641,11 @@ basis in the &smb.conf; file. </para> <para> -<programlisting><title>Example:</title> +<programlisting> [global] - kernel oplocks = yes - -The default is "no". +kernel oplocks = yes </programlisting> +The default is "no". </para> <para> @@ -676,7 +677,7 @@ enabled on a per-share basis, or globally for the entire server, in the 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: +configured globally in the &smb.conf; file: </para> <para> @@ -701,7 +702,7 @@ the entire server, in the &smb.conf; file: [global] oplock break contention limit = 2 (default) - [share_name] +[share_name] oplock break contention limit = 2 (default) </programlisting> </para> @@ -722,7 +723,7 @@ operating system known as <emphasis>Opportunistic Locking</emphasis>. When a wor attempts to access shared data files located on another Windows 2000/XP computer, the Windows 2000/XP operating system will attempt to increase performance by locking the files and caching information locally. When this occurs, the application is unable to -properly function, which results in an <emphasis>Access Denied</emphasis> +properly function, which results in an <errorname>Access Denied</errorname> error message being displayed during network operations. </para> @@ -979,6 +980,26 @@ so far: </para></listitem> </itemizedlist> + <sect2> + <title>locking.tdb error messages</title> + + <para> + <screen> + > We are seeing lots of errors in the samba logs like: + > + > tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic + > 0x4d6f4b61 at offset=36116 + > + > What do these mean? + </screen> + </para> + + <para> + Corrupted tdb. Stop all instancesd of smbd, delete locking.tdb, restart smbd. + </para> + + </sect2> + </sect1> <sect1> diff --git a/docs/docbook/projdoc/msdfs_setup.xml b/docs/docbook/projdoc/msdfs_setup.xml index a86cd74235..c21c9ec6bf 100644 --- a/docs/docbook/projdoc/msdfs_setup.xml +++ b/docs/docbook/projdoc/msdfs_setup.xml @@ -14,49 +14,54 @@ <pubdate>12 Jul 2000</pubdate> </chapterinfo> - <title>Hosting a Microsoft Distributed File System tree on Samba</title> <sect1> - - <title>Instructions</title> - - <para>The Distributed File System (or Dfs) provides a means of - separating the logical view of files and directories that users - see from the actual physical locations of these resources on the - network. It allows for higher availability, smoother storage expansion, - load balancing etc. For more information about Dfs, refer to <ulink - url="http://www.microsoft.com/NTServer/nts/downloads/winfeatures/NTSDistrFile/AdminGuide.asp"> - Microsoft documentation</ulink>. </para> - - <para>This document explains how to host a Dfs tree on a Unix - machine (for Dfs-aware clients to browse) using Samba.</para> - - <para>To enable SMB-based DFS for Samba, configure it with the - <parameter>--with-msdfs</parameter> option. Once built, a - Samba server can be made a Dfs server by setting the global - boolean <ulink url="smb.conf.5.html#HOSTMSDFS"><parameter> - host msdfs</parameter></ulink> parameter in the <filename>smb.conf - </filename> file. You designate a share as a Dfs root using the share - level boolean <ulink url="smb.conf.5.html#MSDFSROOT"><parameter> - msdfs root</parameter></ulink> parameter. A Dfs root directory on - Samba hosts Dfs links in the form of symbolic links that point - to other servers. For example, a symbolic link - <filename>junction->msdfs:storage1\share1</filename> in - the share directory acts as the Dfs junction. When Dfs-aware - clients attempt to access the junction link, they are redirected - to the storage location (in this case, \\storage1\share1).</para> - - <para>Dfs trees on Samba work with all Dfs-aware clients ranging - from Windows 95 to 2000.</para> +<title>Features and Benefits</title> + + <para> + The Distributed File System (or DFS) provides a means of separating the logical + view of files and directories that users see from the actual physical locations + of these resources on the network. It allows for higher availability, smoother + storage expansion, load balancing etc. + </para> + + <para> + For information about DFS, refer to + <ulink url="http://www.microsoft.com/NTServer/nts/downloads/winfeatures/NTSDistrFile/AdminGuide.asp"> + Microsoft documentation at http://www.microsoft.com/NTServer/nts/downloads/winfeatures/NTSDistrFile/AdminGuide.asp</ulink>. + </para> + + <para> + This document explains how to host a DFS tree on a Unix machine (for DFS-aware + clients to browse) using Samba. + </para> + + <para> + To enable SMB-based DFS for Samba, configure it with the <parameter>--with-msdfs</parameter> + option. Once built, a Samba server can be made a DFS server by setting the global + boolean <ulink url="smb.conf.5.html#HOSTMSDFS"><parameter> host msdfs</parameter></ulink> + parameter in the <filename>smb.conf </filename> file. You designate a share as a DFS + root using the share level boolean <ulink url="smb.conf.5.html#MSDFSROOT"><parameter> + msdfs root</parameter></ulink> parameter. A DFS root directory on Samba hosts DFS + links in the form of symbolic links that point to other servers. For example, a symbolic link + <filename>junction->msdfs:storage1\share1</filename> in the share directory acts + as the DFS junction. When DFS-aware clients attempt to access the junction link, + they are redirected to the storage location (in this case, \\storage1\share1). + </para> + + <para> + DFS trees on Samba work with all DFS-aware clients ranging from Windows 95 to 200x. + </para> - <para>Here's an example of setting up a Dfs tree on a Samba - server.</para> + <para> + Here's an example of setting up a DFS tree on a Samba server. + </para> <para><programlisting> # The smb.conf file: [global] - netbios name = SAMBA + netbios name = SMOKEY host msdfs = yes [dfs] @@ -68,49 +73,47 @@ <para>In the /export/dfsroot directory we set up our dfs links to other servers on the network.</para> - <para><prompt>root# </prompt><userinput>cd /export/dfsroot</userinput></para> - <para><prompt>root# </prompt><userinput>chown root /export/dfsroot</userinput></para> - <para><prompt>root# </prompt><userinput>chmod 755 /export/dfsroot</userinput></para> - <para><prompt>root# </prompt><userinput>ln -s msdfs:storageA\\shareA linka</userinput></para> - <para><prompt>root# </prompt><userinput>ln -s msdfs:serverB\\share,serverC\\share linkb</userinput></para> - + <screen> + &rootprompt;<userinput>cd /export/dfsroot</userinput> + &rootprompt;<userinput>chown root /export/dfsroot</userinput> + &rootprompt;<userinput>chmod 755 /export/dfsroot</userinput> + &rootprompt;<userinput>ln -s msdfs:storageA\\shareA linka</userinput> + &rootprompt;<userinput>ln -s msdfs:serverB\\share,serverC\\share linkb</userinput> + </screen> <para>You should set up the permissions and ownership of - the directory acting as the Dfs root such that only designated + the directory acting as the DFS root such that only designated users can create, delete or modify the msdfs links. Also note that symlink names should be all lowercase. This limitation exists to have Samba avoid trying all the case combinations to get at the link name. Finally set up the symbolic links to point to the network shares you want, and start Samba.</para> - <para>Users on Dfs-aware clients can now browse the Dfs tree + <para>Users on DFS-aware clients can now browse the DFS tree on the Samba server at \\samba\dfs. Accessing links linka or linkb (which appear as directories to the client) takes users directly to the appropriate shares on the network.</para> - - <sect2> - <title>Notes</title> - - <itemizedlist> - <listitem><para>Windows clients need to be rebooted - if a previously mounted non-dfs share is made a dfs - root or vice versa. A better way is to introduce a - new share and make it the dfs root.</para> - </listitem> - - <listitem><para>Currently there's a restriction that msdfs - symlink names should all be lowercase.</para> - </listitem> - - <listitem><para>For security purposes, the directory - acting as the root of the Dfs tree should have ownership - and permissions set so that only designated users can - modify the symbolic links in the directory.</para> - </listitem> - </itemizedlist> - </sect2> </sect1> +<sect1> +<title>Common Errors</title> + <itemizedlist> + <listitem><para>Windows clients need to be rebooted + if a previously mounted non-dfs share is made a dfs + root or vice versa. A better way is to introduce a + new share and make it the dfs root.</para> + </listitem> + + <listitem><para>Currently there's a restriction that msdfs + symlink names should all be lowercase.</para> + </listitem> + + <listitem><para>For security purposes, the directory + acting as the root of the DFS tree should have ownership + and permissions set so that only designated users can + modify the symbolic links in the directory.</para> + </listitem> + </itemizedlist> +</sect1> - </chapter> diff --git a/docs/docbook/projdoc/passdb.xml b/docs/docbook/projdoc/passdb.xml index 78aee30448..8173852ffd 100644 --- a/docs/docbook/projdoc/passdb.xml +++ b/docs/docbook/projdoc/passdb.xml @@ -73,6 +73,11 @@ as follows: provide the extended controls that are needed for more comprehensive interoperation with MS Windows NT4 / 200x servers. </para> + + <para> + This backend should be used only for backwards compatibility with older + versions of Samba. It may be deprecated in future releases. + </para> </listitem> </varlistentry> @@ -82,7 +87,8 @@ as follows: 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. + no reason to force migration at this time. Note that this tool will eventually + be deprecated. </para> </listitem> </varlistentry> @@ -94,9 +100,25 @@ Samba-3 introduces the following new password backend capabilities: <variablelist> <title>New Backends</title> + <varlistentry><term>guest:</term> + <listitem> + <para> + This is <emphasis>always</emphasis> required as the last backend specified. + It provides the ability to handle guest account requirements for access to + resources like <parameter>IPC$</parameter> which is used for browsing. + </para> + </listitem> + </varlistentry> + <varlistentry><term>tdbsam:</term> <listitem> <para> + This backend provides a rich database backend for local servers. This + backend is NOT suitable for multiple domain controller (ie: PDC + one + or more BDC) installations. + </para> + + <para> The <emphasis>tdbsam</emphasis> password backend stores the old <emphasis> smbpasswd</emphasis> information PLUS the extended MS Windows NT / 200x SAM information into a binary format TDB (trivial database) file. @@ -118,6 +140,10 @@ Samba-3 introduces the following new password backend capabilities: <varlistentry><term>ldapsam:</term> <listitem> <para> + This provides a rich directory backend for distributed account installation + </para> + + <para> 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 <filename>~samba/examples/LDAP</filename> directory. @@ -125,7 +151,7 @@ Samba-3 introduces the following new password backend capabilities: <para> The new LDAP implmentation significantly expands the control abilities that - were possible with prior versions of Samba. It is not possible to specify + were possible with prior versions of Samba. It is now 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. @@ -147,16 +173,14 @@ Samba-3 introduces the following new password backend capabilities: <listitem> <para> 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). + data file. This backend can not be used for normal operation, it can only + be used in conjunction with <command>pdbedit</command>'s pdb2pdb + functionality. The DTD that is used might be subject to changes in the future. </para> <para> 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 + backends or backups. Use of this tool will allow the data to be edited before migration into another backend format. </para> </listitem> @@ -171,15 +195,6 @@ Samba-3 introduces the following new password backend capabilities: </listitem> </varlistentry> - <varlistentry><term>plugin:</term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> </variablelist> </sect1> @@ -208,9 +223,9 @@ Samba-3 introduces the following new password backend capabilities: 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 + information using a <parameter>passdb backend</parameter>. Commonly available backends are LDAP, plain text file, MySQL and nisplus. For more information, see the man page for &smb.conf; regarding the - <command>passdb backend = </command> parameter. + <parameter>passdb backend</parameter> parameter. </para> <sect2> @@ -248,23 +263,12 @@ Samba-3 introduces the following new password backend capabilities: although they may log onto a domain environment: </para> - <itemizedlist> - <listitem><para> - MS DOS Network client 3.0 with the basic network redirector installed - </para></listitem> - - <listitem><para> - Windows 95 with the network redirector update installed - </para></listitem> - - <listitem><para> - Windows 98 [se] - </para></listitem> - - <listitem><para> - Windows Me</para> - </listitem> - </itemizedlist> + <simplelist> + <member>MS DOS Network client 3.0 with the basic network redirector installed</member> + <member>Windows 95 with the network redirector update installed</member> + <member>Windows 98 [se]</member> + <member>Windows Me</member> + </simplelist> <note> <para> @@ -277,13 +281,13 @@ Samba-3 introduces the following new password backend capabilities: The following versions of MS Windows fully support domain security protocols. </para> - <itemizedlist> - <listitem><para>Windows NT 3.5x</para></listitem> - <listitem><para>Windows NT 4.0</para></listitem> - <listitem><para>Windows 2000 Professional</para></listitem> - <listitem><para>Windows 200x Server/Advanced Server</para></listitem> - <listitem><para>Windows XP Professional</para></listitem> - </itemizedlist> + <simplelist> + <member>Windows NT 3.5x</member> + <member>Windows NT 4.0</member> + <member>Windows 2000 Professional</member> + <member>Windows 200x Server/Advanced Server</member> + <member>Windows XP Professional</member> + </simplelist> <para> All current release of Microsoft SMB/CIFS clients support authentication via the @@ -346,6 +350,32 @@ Samba-3 introduces the following new password backend capabilities: </itemizedlist> </sect3> </sect2> + + <sect2> + <title>Mapping User Identifiers between MS Windows and Unix</title> + + <para> + Every operation in Unix/Linux requires a user identifier (UID), just as in + MS Windows NT4 / 200x this requires a Security Identifier (SID). Samba provides + two means for mapping an MS Windows user to a Unix/Linux UID. + </para> + + <para> + Firstly, all Samba SAM (Security Account Management database) accounts require + a Unix/Linux UID that the account will map to. As users are added to the account + information database samba-3 will call the <parameter>add user script</parameter> + interface to add the account to the Samba host OS. In essence all accounts in + the local SAM require a local user account. + </para> + + <para> + The second way to affect Windows SID to Unix UID mapping is via the + <emphasis>idmap uid, idmap gid</emphasis> parameters in &smb.conf;. + Please refer to the man page for information about these parameters. + These parameters are essential when mapping users from a remote SAM server. + </para> + + </sect2> </sect1> <sect1> @@ -353,7 +383,7 @@ Samba-3 introduces the following new password backend capabilities: <para> Samba-3 provides two (2) tools for management of User and machine accounts. These tools are -called <filename>smbpasswd</filename> and <filename>pdbedit</filename>. A third tool is under +called <filename>smbpasswd</filename> and <command>pdbedit</command>. 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. @@ -383,47 +413,30 @@ be announced in time for samba-3.0.1 release timing. <command>smbpasswd</command> can be used to: </para> - <itemizedlist> - <listitem><para> - <emphasis>add</emphasis> user or machine accounts - </para></listitem> - - <listitem><para> - <emphasis>delete</emphasis> user or machine accounts - </para></listitem> - - <listitem><para> - <emphasis>enable</emphasis> user or machine accounts - </para></listitem> - - <listitem><para> - <emphasis>disable</emphasis> user or machine accounts - </para></listitem> - - <listitem><para> - <emphasis>set to NULL</emphasis> user passwords - </para></listitem> - - <listitem><para> - <emphasis>manage interdomain trust accounts</emphasis> - </para></listitem> - </itemizedlist> + <simplelist> + <member><emphasis>add</emphasis> user or machine accounts</member> + <member><emphasis>delete</emphasis> user or machine accounts</member> + <member><emphasis>enable</emphasis> user or machine accounts</member> + <member><emphasis>disable</emphasis> user or machine accounts</member> + <member><emphasis>set to NULL</emphasis> user passwords</member> + <member><emphasis>manage interdomain trust accounts</emphasis></member> + </simplelist> <para> To run smbpasswd as a normal user just type: </para> <para> - <programlisting> + <screen> <prompt>$ </prompt><userinput>smbpasswd</userinput> - <prompt>Old SMB password: </prompt><userinput><secret></userinput> - </programlisting> - For <emphasis>secret</emphasis> type old value here - or hit return if + <prompt>Old SMB password: </prompt><userinput><replaceable>secret</replaceable></userinput> + </screen> + For <replaceable>secret</replaceable> type old value here - or hit return if there was no old password - <programlisting> - <prompt>New SMB Password: </prompt><userinput><new secret></userinput> - <prompt>Repeat New SMB Password: </prompt><userinput><new secret></userinput> - </programlisting> + <screen> + <prompt>New SMB Password: </prompt><userinput><replaceable>new secret</replaceable></userinput> + <prompt>Repeat New SMB Password: </prompt><userinput><replaceable>new secret</replaceable></userinput> + </screen> </para> <para> @@ -464,19 +477,11 @@ be announced in time for samba-3.0.1 release timing. manage the passdb backend. <command>pdbedit</command> can be used to: </para> - <itemizedlist> - <listitem><para> - add, remove or modify user accounts - </para></listitem> - - <listitem><para> - listing user accounts - </para></listitem> - - <listitem><para> - migrate user accounts - </para></listitem> - </itemizedlist> + <simplelist> + <member>add, remove or modify user accounts</member> + <member>listing user accounts</member> + <member>migrate user accounts</member> + </simplelist> <para> The <command>pdbedit</command> tool is the only one that can manage the account @@ -495,9 +500,8 @@ be announced in time for samba-3.0.1 release timing. a tdbsam password backend. This listing was produced by running: </para> - <para> - pdbedit -Lv met - <programlisting> + <screen> + <prompt>$ </prompt><userinput>pdbedit -Lv met</userinput> Unix username: met NT username: Account Flags: [UX ] @@ -518,8 +522,9 @@ be announced in time for samba-3.0.1 release timing. 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 - </programlisting> - </para> + </screen> + + <!-- FIXME: Add note about migrating user accounts --> </sect2> </sect1> @@ -540,8 +545,8 @@ backends of the same type. For example, to use two different tdbsam databases: <para> <programlisting> -In smb.conf [globals] - passdb backend = tdbsam:/etc/samba/passdb.tdb, \ +[globals] + passdb backend = tdbsam:/etc/samba/passdb.tdb, \ tdbsam:/etc/samba/old-passdb.tdb, guest </programlisting> </para> @@ -687,7 +692,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 <link linkend="bugreport"/>. + Please submit fixes via <link linkend="bugreport">Bug reporting facility</link>. </para> </sect3> @@ -756,9 +761,9 @@ objectclass ( 1.3.6.1.4.1.7165.2.2.3 NAME 'sambaAccount' SUP top AUXILIARY </para> <para> -<programlisting> -<prompt>root# </prompt><userinput>cp samba.schema /etc/openldap/schema/</userinput> -</programlisting> +<screen> +&rootprompt;<userinput>cp samba.schema /etc/openldap/schema/</userinput> +</screen> </para> <para> @@ -792,7 +797,7 @@ include /etc/openldap/schema/nis.schema </para> <para> -<programlisting> +<screen> # Indices to maintain ## required by OpenLDAP index objectclass eq @@ -810,12 +815,11 @@ index displayName pres,sub,eq ##index gidNumber eq ##index memberUid eq -index rid eq index sambaSID eq index sambaPrimaryGroupSID eq index sambaDomainName eq index default sub -</programlisting> +</screen> </para> <para> @@ -823,9 +827,9 @@ index default sub </para> <para> -<programlisting> +<screen> ./sbin/slapindex -f slapd.conf -</programlisting> +</screen> </para> <para> @@ -833,25 +837,97 @@ index default sub </para> <para> -<programlisting> -<prompt>root# </prompt><userinput>/etc/init.d/slapd restart</userinput> -</programlisting> +<screen> +&rootprompt;<userinput>/etc/init.d/slapd restart</userinput> +</screen> +</para> + + </sect3> + + <sect3> + <title>Initialise the LDAP database</title> + + <para> + Before you can add accounts to the LDAP database you must create the account containers + that they will be stored in. The following LDIF file should be modified to match your + needs (ie: Your DNS entries, etc.). + </para> + +<para> +<screen> +# Organization for Samba Base +dn: dc=plainjoe,dc=org +objectclass: dbObject +objectclass: organization +dc: plainjoe +o: Terpstra Org Network +description: The Samba-3 Network LDAP Example + +# Organizational Role for Directory Management +db: cn=Manager,dc=plainjoe,dc=org +objectclass: organizationalRole +cn: Manager +description: Directory Manager + +# Setting up container for users +dn: ou=People,dc=plainjoe,dc=org +objectclass: top +objectclass: organizationalUnit +ou: People + +# Setting up admin handle for People OU +dn: cn=admin,ou=People,dc=plainjoe,dc=org +cn: admin +objectclass: top +objectclass: organizationalRole +objectclass: simpleSecurityObject +userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz +</screen> </para> + <para> + The userPassword shown above should be generated using <command>slappasswd</command>. + </para> + + <para> + The following command will then load the contents of the LDIF file into the LDAP + database. + </para> + +<para> +<screen> +<prompt>$ </prompt><userinput>slapadd -v -l initldap.dif</userinput> +</screen> +</para> + + <para> + Do not forget to secure your LDAP server with an adequate access control list, + as well as an admin password. + </para> + + <note> + <para> + Before Samba can access the LDAP server you need to stoe the LDAP admin password + into the Samba-3 <filename>secrets.tdb</filename> database by: + <screen> +&rootprompt; <userinput>smbpasswd -w <replaceable>secret</replaceable></userinput> + </screen> + </para> + </note> + </sect3> <sect3> <title>Configuring Samba</title> <para> - The following parameters are available in smb.conf only with <parameter>--with-ldapsam</parameter> - was included when compiling Samba. The following parameters are available in smb.conf only if your + 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. </para> <itemizedlist> - <listitem><para><ulink url="smb.conf.5.html#PASSDBBACKEND">passdb backend ldapsam:url</ulink></para></listitem> + <listitem><para><ulink url="smb.conf.5.html#PASSDBBACKEND">passdb backend = ldapsam:url</ulink></para></listitem> <listitem><para><ulink url="smb.conf.5.html#LDAPSSL">ldap ssl</ulink></para></listitem> <listitem><para><ulink url="smb.conf.5.html#LDAPADMINDN">ldap admin dn</ulink></para></listitem> <listitem><para><ulink url="smb.conf.5.html#LDAPSUFFIX">ldap suffix</ulink></para></listitem> @@ -870,51 +946,51 @@ index default sub use with an LDAP directory could appear as </para> - <para> - <programlisting> - ## /usr/local/samba/lib/smb.conf - [global] - security = user - encrypt passwords = yes +<para> +<programlisting> +## /usr/local/samba/lib/smb.conf +[global] + security = user + encrypt passwords = yes - netbios name = TASHTEGO - workgroup = NARNIA + netbios name = TASHTEGO + workgroup = NARNIA - # ldap related parameters + # 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 <replaceable>secretpw</replaceable>' 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 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 <replaceable>secretpw</replaceable>' 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 + # 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://funball.samba.org + # syntax: passdb backend = ldapsam:ldap://server-name[:port] + passdb backend = ldapsam:ldap://funball.samba.org, guest - # smbpasswd -x delete the entire dn-entry - ldap delete dn = no + # 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 + # 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 - # Trust unix account information in LDAP - # (see the smb.conf manpage for details) - ldap trust ids = Yes + # 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" + # specify the base DN to use when searching the directory + ldap suffix = "ou=people,dc=samba,dc=org" - # generally the default ldap search filter is ok - # ldap filter = "(&(uid=%u)(objectclass=sambaAccount))" - </programlisting> - </para> + # generally the default ldap search filter is ok + # ldap filter = "(&(uid=%u)(objectclass=sambaAccount))" +</programlisting> +</para> </sect3> @@ -929,7 +1005,7 @@ index default sub <para> 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 + in a different tree of your 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 @@ -970,12 +1046,12 @@ index default sub <para> To remedy the first security issue, the "ldap ssl" smb.conf parameter defaults - to require an encrypted session (<command>ldap ssl = on</command>) using - the default port of 636 + to require an encrypted session (<parameter>ldap ssl = on</parameter>) using + the default port of <constant>636</constant> 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 - (<command>ldap ssl = off</command>). + (<parameter>ldap ssl = off</parameter>). </para> <para> @@ -990,14 +1066,14 @@ index default sub following ACL in <filename>slapd.conf</filename>: </para> - <para> - <programlisting> - ## 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 - </programlisting> - </para> +<para> +<programlisting> +## 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 +</programlisting> +</para> </sect3> @@ -1008,84 +1084,88 @@ index default sub The sambaAccount objectclass is composed of the following attributes: </para> - <itemizedlist> - <listitem><para><constant>lmPassword</constant>: the LANMAN password 16-byte hash stored as a character - representation of a hexidecimal string.</para></listitem> - - <listitem><para><constant>ntPassword</constant>: the NT password hash 16-byte stored as a character - representation of a hexidecimal string.</para></listitem> - - <listitem><para><constant>pwdLastSet</constant>: The integer time in seconds since 1970 when the + <para> + <table frame="all"> + <title>Attributes in the sambaAccount objectclass (LDAP)</title> + <tgroup cols="2" align="left"> + <tbody> + <row><entry><constant>lmPassword</constant></entry><entry>the LANMAN password 16-byte hash stored as a character + representation of a hexidecimal string.</entry></row> + <row><entry><constant>ntPassword</constant></entry><entry>the NT password hash 16-byte stored as a character + representation of a hexidecimal string.</entry></row> + <row><entry><constant>pwdLastSet</constant></entry><entry>The integer time in seconds since 1970 when the <constant>lmPassword</constant> and <constant>ntPassword</constant> attributes were last set. - </para></listitem> + </entry></row> - <listitem><para><constant>acctFlags</constant>: string of 11 characters surrounded by square brackets [] + <row><entry><constant>acctFlags</constant></entry><entry>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).</para></listitem> + and D(disabled).</entry></row> - <listitem><para><constant>logonTime</constant>: Integer value currently unused</para></listitem> + <row><entry><constant>logonTime</constant></entry><entry>Integer value currently unused</entry></row> - <listitem><para><constant>logoffTime</constant>: Integer value currently unused</para></listitem> + <row><entry><constant>logoffTime</constant></entry><entry>Integer value currently unused</entry></row> - <listitem><para><constant>kickoffTime</constant>: Integer value currently unused</para></listitem> + <row><entry><constant>kickoffTime</constant></entry><entry>Integer value currently unused</entry></row> - <listitem><para><constant>pwdCanChange</constant>: Integer value currently unused</para></listitem> + <row><entry><constant>pwdCanChange</constant></entry><entry>Integer value currently unused</entry></row> - <listitem><para><constant>pwdMustChange</constant>: Integer value currently unused</para></listitem> + <row><entry><constant>pwdMustChange</constant></entry><entry>Integer value currently unused</entry></row> - <listitem><para><constant>homeDrive</constant>: specifies the drive letter to which to map the + <row><entry><constant>homeDrive</constant></entry><entry>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.</para></listitem> + smb.conf(5) man page for more information.</entry></row> - <listitem><para><constant>scriptPath</constant>: The scriptPath property specifies the path of + <row><entry><constant>scriptPath</constant></entry><entry>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.</para></listitem> + smb.conf(5) man page for more information.</entry></row> - <listitem><para><constant>profilePath</constant>: specifies a path to the user's profile. + <row><entry><constant>profilePath</constant></entry><entry>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.</para></listitem> + "logon path" parameter in the smb.conf(5) man page for more information.</entry></row> - <listitem><para><constant>smbHome</constant>: The homeDirectory property specifies the path of + <row><entry><constant>smbHome</constant></entry><entry>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 <filename>\\server\share\directory</filename>. This value can be a null string. Refer to the <command>logon home</command> parameter in the &smb.conf; man page for more information. - </para></listitem> + </entry></row> - <listitem><para><constant>userWorkstation</constant>: character string value currently unused. - </para></listitem> + <row><entry><constant>userWorkstation</constant></entry><entry>character string value currently unused. + </entry></row> - <listitem><para><constant>rid</constant>: the integer representation of the user's relative identifier - (RID).</para></listitem> + <row><entry><constant>rid</constant></entry><entry>the integer representation of the user's relative identifier + (RID).</entry></row> - <listitem><para><constant>primaryGroupID</constant>: the relative identifier (RID) of the primary group - of the user.</para></listitem> + <row><entry><constant>primaryGroupID</constant></entry><entry>the relative identifier (RID) of the primary group + of the user.</entry></row> - <listitem><para><constant>domain</constant>: domain the user is part of.</para></listitem> - </itemizedlist> + <row><entry><constant>domain</constant></entry><entry>domain the user is part of.</entry></row> + </tbody> + </tgroup></table> + </para> <para> The majority of these parameters are only used when Samba is acting as a PDC of - a domain (refer to the <link linkend="pdc">Samba as a primary domain controller</link> chapter for details on + a domain (refer to the <link linkend="samba-pdc">Samba as a primary domain controller</link> 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: </para> - <itemizedlist> - <listitem><para>smbHome</para></listitem> - <listitem><para>scriptPath</para></listitem> - <listitem><para>logonPath</para></listitem> - <listitem><para>homeDrive</para></listitem> - </itemizedlist> + <simplelist> + <member>smbHome</member> + <member>scriptPath</member> + <member>logonPath</member> + <member>homeDrive</member> + </simplelist> <para> 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 <command>logon home = \\%L\%u</command> was defined in - its <filename>smb.conf</filename> file. When a user named "becky" logons to the domain, + configured as a PDC and that <parameter>logon home = \\%L\%u</parameter> was defined in + its &smb.conf; file. When a user named "becky" logons to the domain, the <parameter>logon home</parameter> 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 @@ -1151,7 +1231,7 @@ index default sub pwdCanChange: 0 pwdMustChange: 2147483647 ntPassword: 878D8014606CDA29677A44EFA1353FC7 - </programlisting> +</programlisting> </para> </sect3> @@ -1164,7 +1244,7 @@ index default sub using pam_ldap, this allows changing both unix and windows passwords at once. </para> - <para>The <command>ldap passwd sync</command> options can have the following values:</para> + <para>The <parameter>ldap passwd sync</parameter> options can have the following values:</para> <variablelist> <varlistentry> @@ -1208,7 +1288,12 @@ index default sub <title>MySQL</title> <para> - Stuff goes here! + Every so often someone will come along with a great new idea. Storing of user accounts in an + SQL backend is one of them. Those who want to do this are in the best position to know what the + specific benefits are to them. This may sound like a cop-out, but in truth we can not attempt + to document every nitty little detail why certain things of marginal utility to the bulk of + Samba users might make sense to the rest. In any case, the following instructions should help + the determined SQL user to implement a working system. </para> <sect3> @@ -1219,7 +1304,7 @@ index default sub for the column names) or use the default table. The file <filename>examples/pdb/mysql/mysql.dump</filename> contains the correct queries to create the required tables. Use the command : - <command>mysql -u<replaceable>username</replaceable> -h<replaceable>hostname</replaceable> -p<replaceable>password</replaceable> <replaceable>databasename</replaceable> > <filename>/path/to/samba/examples/pdb/mysql/mysql.dump</filename></command> + <screen><prompt>$ </prompt><userinput>mysql -u<replaceable>username</replaceable> -h<replaceable>hostname</replaceable> -p<replaceable>password</replaceable> <replaceable>databasename</replaceable> > <filename>/path/to/samba/examples/pdb/mysql/mysql.dump</filename></userinput></screen> </para> </sect3> @@ -1228,7 +1313,7 @@ index default sub <para>This plugin lacks some good documentation, but here is some short info:</para> - <para>Add a the following to the <command>passdb backend</command> variable in your <filename>smb.conf</filename>: + <para>Add a the following to the <parameter>passdb backend</parameter> variable in your &smb.conf;: <programlisting> passdb backend = [other-plugins] mysql:identifier [other-plugins] </programlisting> @@ -1236,24 +1321,32 @@ index default sub <para>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 + specify multiple pdb_mysql.so entries in <parameter>passdb backend</parameter>, you also need to use different identifiers! </para> <para> - Additional options can be given thru the &smb.conf; file in the <command>[global]</command> section. + Additional options can be given thru the &smb.conf; file in the <parameter>[global]</parameter> section. </para> - <para> - <programlisting> - 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 - </programlisting> - </para> + <para> + <table frame="all"> + <title>Basic smb.conf options for MySQL passdb backend</title> + <tgroup cols="2" align="left"> + <thead> + <row><entry>Field</entry><entry>Contents</entry></row> + </thead> + <tbody> + <row><entry>identifier:mysql host</entry><entry>host name, defaults to 'localhost'</entry></row> + <row><entry>identifier:mysql password</entry><entry></entry></row> + <row><entry>identifier:mysql user</entry><entry>defaults to 'samba'</entry></row> + <row><entry>identifier:mysql database</entry><entry>defaults to 'samba'</entry></row> + <row><entry>identifier:mysql port</entry><entry>defaults to 3306</entry></row> + <row><entry>identifier:table</entry><entry>Name of the table containing users</entry></row> + </tbody> + </tgroup> + </table> + </para> <warning> <para> @@ -1266,41 +1359,46 @@ index default sub <para>Names of the columns in this table(I've added column types those columns should have first):</para> - <para> - <programlisting> - 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 - </programlisting> - </para> + <para> + <table frame="all"> + <title>MySQL field names for MySQL passdb backend</title> + <tgroup cols="3" align="left"> + <thead> + <row><entry>Field</entry><entry>Type</entry><entry>Contents</entry></row> + </thead> + <tbody> + <row><entry>identifier:logon time column</entry><entry>int(9)</entry><entry></entry></row> + <row><entry>identifier:logoff time column</entry><entry>int(9)</entry><entry></entry></row> + <row><entry>identifier:kickoff time column</entry><entry>int(9)</entry><entry></entry></row> + <row><entry>identifier:pass last set time column</entry><entry>int(9)</entry><entry></entry></row> + <row><entry>identifier:pass can change time column</entry><entry>int(9)</entry><entry></entry></row> + <row><entry>identifier:pass must change time column</entry><entry>int(9)</entry><entry></entry></row> + <row><entry>identifier:username column</entry><entry>varchar(255)</entry><entry>unix username</entry></row> + <row><entry>identifier:domain column</entry><entry>varchar(255)</entry><entry>NT domain user is part of</entry></row> + <row><entry>identifier:nt username column</entry><entry>varchar(255)</entry><entry>NT username</entry></row> + <row><entry>identifier:fullname column</entry><entry>varchar(255)</entry><entry>Full name of user</entry></row> + <row><entry>identifier:home dir column</entry><entry>varchar(255)</entry><entry>Unix homedir path</entry></row> + <row><entry>identifier:dir drive column</entry><entry>varchar(2)</entry><entry>Directory drive path (eg: 'H:')</entry></row> + <row><entry>identifier:logon script column</entry><entry>varchar(255)</entry><entry>Batch file to run on client side when logging on</entry></row> + <row><entry>identifier:profile path column</entry><entry>varchar(255)</entry><entry>Path of profile</entry></row> + <row><entry>identifier:acct desc column</entry><entry>varchar(255)</entry><entry>Some ASCII NT user data</entry></row> + <row><entry>identifier:workstations column</entry><entry>varchar(255)</entry><entry>Workstations user can logon to (or NULL for all)</entry></row> + <row><entry>identifier:unknown string column</entry><entry>varchar(255)</entry><entry>unknown string</entry></row> + <row><entry>identifier:munged dial column</entry><entry>varchar(255)</entry><entry>?</entry></row> + <row><entry>identifier:user sid column</entry><entry>varchar(255)</entry><entry>NT user SID</entry></row> + <row><entry>identifier:group sid column</entry><entry>varchar(255)</entry><entry>NT group ID</entry></row> + <row><entry>identifier:lanman pass column</entry><entry>varchar(255)</entry><entry>encrypted lanman password</entry></row> + <row><entry>identifier:nt pass column</entry><entry>varchar(255)</entry><entry>encrypted nt passwd</entry></row> + <row><entry>identifier:plain pass column</entry><entry>varchar(255)</entry><entry>plaintext password</entry></row> + <row><entry>identifier:acct control column</entry><entry>int(9)</entry><entry>nt user data</entry></row> + <row><entry>identifier:unknown 3 column</entry><entry>int(9)</entry><entry>unknown</entry></row> + <row><entry>identifier:logon divs column</entry><entry>int(9)</entry><entry>?</entry></row> + <row><entry>identifier:hours len column</entry><entry>int(9)</entry><entry>?</entry></row> + <row><entry>identifier:unknown 5 column</entry><entry>int(9)</entry><entry>unknown</entry></row> + <row><entry>identifier:unknown 6 column</entry><entry>int(9)</entry><entry>unknown</entry></row> + </tbody></tgroup> + </table> + </para> <para> Eventually, you can put a colon (:) after the name of each column, which @@ -1362,7 +1460,7 @@ index default sub </para> <para> - <userinput>pdbedit -e xml:filename</userinput> + <prompt>$ </prompt><userinput>pdbedit -e xml:filename</userinput> </para> <para> @@ -1371,22 +1469,7 @@ index default sub <para> To import data, use: - <userinput>pdbedit -i xml:filename -e current-pdb</userinput> - </para> - - <para> - Where filename is the name to read the data from and current-pdb to put it in. - </para> - - <para> - For example: To migrate (copy) the smbpasswd database into a tdbsam database: - </para> - - <para> - <programlisting> - then execute (as root): - pdbedit -i smbpasswd -e tdbsam - </programlisting> + <prompt>$ </prompt><userinput>pdbedit -i xml:filename</userinput> </para> </sect2> </sect1> @@ -1394,11 +1477,64 @@ index default sub <sect1> <title>Common Errors</title> -<para> -Put stuff here -- People forget to put their users in their backend and then complain samba - won't authorize them -</para> + <sect2> + <title>Users can not logon - Users not in Samba SAM</title> + + <para> + People forget to put their users in their backend and then complain samba won't authorize them. + </para> + + </sect2> + + <sect2> + <title>Users are being added to the wrong backend database</title> + + <para> + A few complaints have been recieved from users that just moved to samba-3. The following + &smb.conf; file entries were causing problems, new accounts were being added to the old + smbpasswd file, not to the tdbsam passdb.tdb file: + </para> + + <para> + <programlisting> + [globals] + ... + passdb backend = smbpasswd, tdbsam, guest + ... + </programlisting> + </para> + + <para> + Samba will add new accounts to the first entry in the <emphasis>passdb backend</emphasis> + parameter entry. If you want to update to the tdbsam, then change the entry to: + </para> + + <para> + <programlisting> + [globals] + ... + passdb backend = tdbsam, smbpasswd, guest + ... + </programlisting> + </para> + + </sect2> + + <sect2> + <title>auth methods does not work</title> + + <para> + If you explicitly set an 'auth methods' parameter, guest must be specified as the first + entry on the line. Eg: <parameter>auth methods = guest sam</parameter>. + </para> + + <para> + This is the exact opposite of the requirement for the <parameter>passdb backed</parameter> + option, where it must be the <emphasis>LAST</emphasis> parameter on the line. + </para> + + </sect2> </sect1> + </chapter> diff --git a/docs/docbook/projdoc/printer_driver2.xml b/docs/docbook/projdoc/printer_driver2.xml index da3eb838f2..f730b238bd 100644 --- a/docs/docbook/projdoc/printer_driver2.xml +++ b/docs/docbook/projdoc/printer_driver2.xml @@ -1,1038 +1,3516 @@ <chapter id="printing"> <chapterinfo> - &author.jerry; <author> - <firstname>Patrick</firstname><surname>Powell</surname> + <firstname>Kurt</firstname><surname>Pfeifle</surname> <affiliation> - <address><email>papowell@lprng.org</email></address> + <orgname> Danka Deutschland GmbH </orgname> + <address><email>kpfeifle@danka.de</email></address> </affiliation> </author> - <pubdate> (3 May 2001) </pubdate> + <pubdate>May 32, 2003</pubdate> </chapterinfo> -<title>Printing Support</title> +<title>Classical Printing Support</title> <sect1> -<title>Introduction</title> - -<para>Beginning with the 2.2.0 release, Samba supports -the native Windows NT printing mechanisms implemented via -MS-RPC (i.e. the SPOOLSS named pipe). Previous versions of -Samba only supported LanMan printing calls.</para> - -<para>The additional functionality provided by the new -SPOOLSS support includes:</para> - -<itemizedlist> - <listitem><para>Support for downloading printer driver - files to Windows 95/98/NT/2000 clients upon demand. - </para></listitem> - - <listitem><para>Uploading of printer drivers via the - Windows NT Add Printer Wizard (APW) or the - Imprints tool set (refer to <ulink - url="http://imprints.sourceforge.net">http://imprints.sourceforge.net</ulink>). - </para></listitem> - - <listitem><para>Support for the native MS-RPC printing - calls such as StartDocPrinter, EnumJobs(), etc... (See - the MSDN documentation at <ulink - url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink> - for more information on the Win32 printing API) - </para></listitem> - - <listitem><para>Support for NT Access Control Lists (ACL) - on printer objects</para></listitem> - - <listitem><para>Improved support for printer queue manipulation - through the use of an internal databases for spooled job - information</para></listitem> -</itemizedlist> +<title>Features and Benefits</title> <para> -There has been some initial confusion about what all this means -and whether or not it is a requirement for printer drivers to be -installed on a Samba host in order to support printing from Windows -clients. As a side note, Samba does not use these drivers in any way to process -spooled files. They are utilized entirely by the clients. +Printing is often a mission-critical service for the users. Samba can +provide this service reliably and seamlessly for a client network +consisting of Windows workstations. </para> <para> -The following MS KB article, may be of some help if you are dealing with -Windows 2000 clients: <emphasis>How to Add Printers with No User -Interaction in Windows 2000</emphasis> +A Samba-3.0 print service may be run on a Standalone or a Domain +member server, side by side with file serving functions, or on a +dedicated print server. It can be made as tight or as loosely secured +as needs dictate. Configurations may be simple or complex. Available +authentication schemes are essentially the same as described for file +services in previous chapters. Overall, Samba's printing support is +now able to replace an NT or Windows 2000 print server full-square, +with additional benefits in many cases. Clients may download and +install drivers and printers through their familiar "Point'n'Print" +mechanism. Printer installations executed by "Logon Scripts" are no +problem. Administrators can upload and manage drivers to be used by +clients through the familiar "Add Printer Wizard". As an additional +benefit, driver and printer management may be run from the commandline +or through scripts, making it more efficient in case of large numbers +of printers. If a central accounting of print jobs (tracking every +single page and supplying the raw data for all sorts of statistical +reports) is required, this is best supported by CUPS as the print +subsystem underneath the Samba hood. </para> <para> -<ulink url="http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP">http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP</ulink> +This chapter deals with the foundations of Samba printing, as they +implemented by the more traditional UNIX (BSD- and System V-style) +printing systems. Many things apply to CUPS, the newer Common UNIX +Printing System, too; so if you use CUPS, you might be tempted to jump +to the next chapter -- but you will certainly miss a few things if you +do so. Better read this chapter too. </para> -</sect1> +<note> +<para> +Most of the given examples have been verified on Windows XP +Professional clients. Where this document describes the responses to +commands given, bear in mind that Windows 2000 clients are very +similar, but may differ in details. Windows NT is somewhat different +again. +</para> +</note> +</sect1> <sect1> -<title>Configuration</title> +<title>Technical Introduction</title> + +<para> +Samba's printing support always relies on the installed print +subsystem of the Unix OS it runs on. Samba is a "middleman". It takes +printfiles from Windows (or other SMB) clients and passes them to the +real printing system for further processing. Therefore it needs to +"talk" to two sides: to the Windows print clients and to the Unix +printing system. Hence we must differentiate between the various +client OS types each of which behave differently, as well as the +various UNIX print subsystems, which themselves have different +features and are accessed differently. This part of the Samba HOWTO +Collection deals with the "traditional" way of Unix printing first; +the next chapter covers in great detail the more modern +<emphasis>Common UNIX Printing System</emphasis> +(CUPS). + +<important><para>CUPS users, be warned: don't just jump on to the next +chapter. You might miss important information contained only +here!</para></important> +</para> -<warning> -<title>[print$] vs. [printer$]</title> +<sect2> +<title>What happens if you send a Job from a Client</title> <para> -Previous versions of Samba recommended using a share named [printer$]. -This name was taken from the printer$ service created by Windows 9x -clients when a printer was shared. Windows 9x printer servers always have -a printer$ service which provides read-only access via no -password in order to support printer driver downloads. +To successfully print a job from a Windows client via a Samba +print server to a UNIX printer, there are 6 (potentially 7) +stages: </para> - + +<orderedlist> +<listitem><para>Windows opens a connection to the printershare</para></listitem> + +<listitem><para>Samba must authenticate the user</para></listitem> + +<listitem><para>Windows sends a copy of the printfile over the network +into Samba's spooling area</para></listitem> + +<listitem><para>Windows closes the connection again</para></listitem> + +<listitem><para>Samba invokes the print command to hand the file over +to the UNIX print subsystem's spooling area</para></listitem> + +<listitem><para>The Unix print subsystem processes the print +job</para></listitem> + +<listitem><para>The printfile may need to be explicitely deleted +from the Samba spooling area.</para></listitem> + +</orderedlist> +</sect2> + +<sect2> +<title>Printing Related Configuration Parameters</title> + <para> -However, the initial implementation allowed for a -parameter named <parameter>printer driver location</parameter> -to be used on a per share basis to specify the location of -the driver files associated with that printer. Another -parameter named <parameter>printer driver</parameter> provided -a means of defining the printer driver name to be sent to -the client. +There are a number of configuration parameters in +<filename>smb.conf</filename> controlling Samba's printing +behaviour. Please also refer to the man page for smb.conf to +acquire an overview about these. As with other parameters, there are +Global Level (tagged with a "<emphasis>G</emphasis>" in the listings) and +Service Level ("<emphasis>S</emphasis>") parameters. </para> -</warning> - +<variablelist> +<varlistentry><term>Service Level Parameters</term> +<listitem><para>These <emphasis>may</emphasis> go into the +<parameter>[global]</parameter> section of +<filename>smb.conf</filename>. In this case they define the default +behaviour of all individual or service level shares (provided those +don't have a different setting defined for the same parameter, thus +overriding the global default).</para></listitem> +</varlistentry> + +<varlistentry><term>Global Parameters</term> +<listitem><para>These <emphasis>may not</emphasis> go into individual +shares. If they go in by error, the "testparm" utility can discover +this (if you run it) and tell you so.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + <sect2> -<title>Creating [print$]</title> - -<para> -In order to support the uploading of printer driver -files, you must first configure a file share named [print$]. -The name of this share is hard coded in Samba's internals so -the name is very important (print$ is the service used by -Windows NT print servers to provide support for printer driver -download). -</para> - -<para>You should modify the server's smb.conf file to add the global -parameters and to create the -following file share (of course, some of the parameter values, -such as 'path' are arbitrary and should be replaced with -appropriate values for your site):</para> - -<para><programlisting> -[global] - ; members of the ntadmin group should be able - ; to add drivers and set printer properties - ; root is implicitly a 'printer admin' - printer admin = @ntadmin - -[print$] - path = /usr/local/samba/printers - guest ok = yes - browseable = yes - read only = yes - ; since this share is configured as read only, then we need - ; a 'write list'. Check the file system permissions to make - ; sure this account can copy files to the share. If this - ; is setup to a non-root account, then it should also exist - ; as a 'printer admin' - write list = @ntadmin,root -</programlisting></para> - -<para>The <ulink url="smb.conf.5.html#WRITELIST"><parameter> -write list</parameter></ulink> is used to allow administrative -level user accounts to have write access in order to update files -on the share. See the <ulink url="smb.conf.5.html">smb.conf(5) -man page</ulink> for more information on configuring file shares.</para> - -<para>The requirement for <ulink url="smb.conf.5.html#GUESTOK"><command>guest -ok = yes</command></ulink> depends upon how your -site is configured. If users will be guaranteed to have -an account on the Samba host, then this is a non-issue.</para> - -<note> -<title>Author's Note</title> - -<para> -The non-issue is that if all your Windows NT users are guaranteed to be -authenticated by the Samba server (such as a domain member server and the NT -user has already been validated by the Domain Controller in -order to logon to the Windows NT console), then guest access -is not necessary. Of course, in a workgroup environment where -you just want to be able to print without worrying about -silly accounts and security, then configure the share for -guest access. You'll probably want to add <ulink -url="smb.conf.5.html#MAPTOGUEST"><command>map to guest = Bad User -</command></ulink> in the [global] section as well. Make sure -you understand what this parameter does before using it -though. --jerry +<title>Parameters Recommended for Use</title> + +<para>The following <filename>smb.conf</filename> parameters directly +related to printing are used in Samba-3. See also the +<filename>smb.conf</filename> man page for detailed explanations: </para> -</note> -<para>In order for a Windows NT print server to support -the downloading of driver files by multiple client architectures, -it must create subdirectories within the [print$] service -which correspond to each of the supported client architectures. -Samba follows this model as well.</para> +<formalpara> +<title>LIST OF PRINTING RELATED PARAMETERS IN Samba-3</title> +<para> +<itemizedlist><title>Global level parameters:</title> +<listitem><para><parameter>addprinter command (G)</parameter></para></listitem> +<listitem><para><parameter>deleteprinter command (G)</parameter></para></listitem> +<listitem><para><parameter>disable spoolss (G)</parameter></para></listitem> +<listitem><para><parameter>enumports command (G)</parameter></para></listitem> +<listitem><para><parameter>load printers (G)</parameter></para></listitem> +<listitem><para><parameter>lpq cache time (G)</parameter></para></listitem> +<listitem><para><parameter>os2 driver map (G)</parameter></para></listitem> +<listitem><para><parameter>printcap name (G), printcap (G)</parameter></para></listitem> +<listitem><para><parameter>show add printer wizard (G)</parameter></para></listitem> +<listitem><para><parameter>total print jobs (G)</parameter></para></listitem> +<listitem><para><parameter>use client driver (G)</parameter></para></listitem> +</itemizedlist> + +<itemizedlist><title>Service level parameters:</title> +<listitem><para><parameter>hosts allow (S)</parameter></para></listitem> +<listitem><para><parameter>hosts deny (S)</parameter></para></listitem> +<listitem><para><parameter>lppause command (S)</parameter></para></listitem> +<listitem><para><parameter>lpq command (S)</parameter></para></listitem> +<listitem><para><parameter>lpresume command (S)</parameter></para></listitem> +<listitem><para><parameter>lprm command (S)</parameter></para></listitem> +<listitem><para><parameter>max print jobs (S)</parameter></para></listitem> +<listitem><para><parameter>min print space (S)</parameter></para></listitem> +<listitem><para><parameter>print command (S)</parameter></para></listitem> +<listitem><para><parameter>printable (S), print ok (S)</parameter></para></listitem> +<listitem><para><parameter>printer name (S), printer (S)</parameter></para></listitem> +<listitem><para><parameter>printer admin (S)</parameter></para></listitem> +<listitem><para><parameter>printing = [cups|bsd|lprng...] (S)</parameter></para></listitem> +<listitem><para><parameter>queuepause command (S)</parameter></para></listitem> +<listitem><para><parameter>queueresume command (S)</parameter></para></listitem> +<listitem><para><parameter>total print jobs (S)</parameter></para></listitem> +</itemizedlist> +</para> +</formalpara> -<para>Next create the directory tree below the [print$] share -for each architecture you wish to support.</para> +<para> +Samba's printing support implements the Microsoft Remote Procedure +Calls (MS-RPC) methods for printing. These are used by Windows NT (and +later) print servers. The old "LanMan" protocol is still supported as +a fallback resort, and for older clients to use. More details will +follow further beneath. +</para> +</sect2> -<para><computeroutput> -[print$]----- - |-W32X86 ; "Windows NT x86" - |-WIN40 ; "Windows 95/98" - |-W32ALPHA ; "Windows NT Alpha_AXP" - |-W32MIPS ; "Windows NT R4000" - |-W32PPC ; "Windows NT PowerPC" -</computeroutput></para> +<sect2> +<title>Parameters for Backwards Compatibility</title> -<warning> -<title>ATTENTION! REQUIRED PERMISSIONS</title> - <para> -In order to currently add a new driver to you Samba host, -one of two conditions must hold true: +Two new parameters that were added in Samba 2.2.2, are still present +in Samba-3.0. Both of these options are described in the +<filename>smb.conf</filename>(5) man page and are disabled by +default. <emphasis>Use them with caution!</emphasis> </para> - + +<variablelist> +<varlistentry><term><parameter>disable spoolss(G)</parameter></term> +<listitem><para> This is +provided for better support of Samba 2.0.x backwards capability. It +will disable Samba's support for MS-RPC printing and yield identical +printing behaviour to Samba 2.0.x.</para></listitem> +</varlistentry> + +<varlistentry><term><parameter>use client driver (G)</parameter></term> +<listitem><para> was provided +for using local printer drivers on Windows NT/2000 clients. It does +not apply to Windows 95/98/ME clients.</para></listitem> +</varlistentry> +</variablelist> + +<formalpara> +<title>PARAMETERS "FOR BACKWARD COMPATIBILITY ONLY", USE WITH CAUTION</title> + +<para> <itemizedlist> - <listitem><para>The account used to connect to the Samba host - must have a uid of 0 (i.e. a root account)</para></listitem> - - <listitem><para>The account used to connect to the Samba host - must be a member of the <ulink - url="smb.conf.5.html#PRINTERADMIN"><parameter>printer - admin</parameter></ulink> list.</para></listitem> +<listitem><para><parameter>disable spoolss (G)</parameter></para></listitem> + +<listitem><para><parameter>use client driver (S)</parameter></para></listitem> </itemizedlist> +</para> +</formalpara> + +</sect2> + +<sect2> +<title>Parameters no longer in Use</title> <para> -Of course, the connected account must still possess access -to add files to the subdirectories beneath [print$]. Remember -that all file shares are set to 'read only' by default. +Samba users upgrading from 2.2.x to 3.0 need to be aware that some +previously available settings are no longer supported (as was +announced some time ago). Here is a list of them: </para> -</warning> +<formalpara> +<title>"OLD" PARAMETERS, REMOVED IN Samba-3</title> <para> -Once you have created the required [print$] service and -associated subdirectories, simply log onto the Samba server using -a root (or <parameter>printer admin</parameter>) account -from a Windows NT 4.0/2k client. Open "Network Neighbourhood" or -"My Network Places" and browse for the Samba host. Once you have located -the server, navigate to the "Printers..." folder. -You should see an initial listing of printers -that matches the printer shares defined on your Samba host. +The following <filename>smb.conf</filename> parameters have been +deprecated already in Samba 2.2 and are now completely removed from +Samba-3. You cannot use them in new 3.0 installations: + +<itemizedlist> +<listitem><para><parameter>printer driver file (G)</parameter></para></listitem> +<listitem><para><parameter>total print jobs (G)</parameter></para></listitem> +<listitem><para><parameter>postscript (S)</parameter></para></listitem> +<listitem><para><parameter>printer driver (S)</parameter></para></listitem> +<listitem><para><parameter>printer driver location (S)</parameter></para></listitem> +</itemizedlist> </para> + +</formalpara> + </sect2> +</sect1> + +<sect1> +<title>A simple Configuration to Print with Samba-3</title> + +<para> +Here is a very simple example configuration for print related settings +in the <filename>smb.conf</filename> file. If you compare it with your +own system's <filename>smb.conf</filename>, you probably find some +additional parameters included there (as pre-configured by your OS +vendor). Further below is a discussion and explanation of the +parameters. Note, that this example doesn't use many parameters. +However, in many environments these are enough to provide a valid +<filename>smb.conf</filename> which enables all clients to print. +</para> + +<para><screen> + [global] + printing = bsd + load printers = yes + + [printers] + path = /var/spool/samba + printable = yes + public = yes + writable = no +</screen></para> + +<para> +This is only an example configuration. Many settings, if not +explicitly set to a specific value, are used and set by Samba +implicitly to its own default, because these have been compiled in. +To see all settings, let root use the <command>testparm</command> +utility. <command>testparm</command> also gives warnings if you have +mis-configured certain things. Its complete output is easily 340 lines +and more. You may want to pipe it through a pager program. +</para> + +<para> +The syntax for the configuration file is easy to grasp. You should +know that <filename>smb.conf</filename> is not very picky about its +syntax. It has been explained elsewhere in this document. A short +reminder: It even tolerates some spelling errors (like "browsable" +instead of "browseable"). Most spelling is case-insensitive. Also, you +can use "Yes|No" or "True|False" for boolean settings. Lists of names +may be separated by commas, spaces or tabs. +</para> <sect2> -<title>Setting Drivers for Existing Printers</title> +<title>Verification of "Settings in Use" with <command>testparm</command></title> + +<para> +To see all (or at least most) printing related settings in Samba, +including the implicitly used ones, try the command outlined below +(hit "ENTER" twice!). It greps for all occurrences of "lp", "print", +"spool", "driver", "ports" and "[" in testparm's output and gives you +a nice overview about the running smbd's print configuration. (Note +that this command does not show individually created printer shares, +or the spooling paths in each case). Here is the output of my Samba +setup, with exactly the same settings in <filename>smb.conf</filename> +as shown above: +</para> + +<para><screen> + transmeta: # testparm -v | egrep "(lp|print|spool|driver|ports|\[)" + + Load smb config files from /etc/samba/smb.conf.simpleprinting + Processing section "[homes]" + Processing section "[printers]" + + [global] + smb ports = 445 139 + lpq cache time = 10 + total print jobs = 0 + load printers = Yes + printcap name = /etc/printcap + disable spoolss = No + enumports command = + addprinter command = + deleteprinter command = + show add printer wizard = Yes + os2 driver map = + printer admin = + min print space = 0 + max print jobs = 1000 + printable = No + printing = bsd + print command = lpr -r -P'%p' %s + lpq command = lpq -P'%p' + lprm command = lprm -P'%p' %j + lppause command = + lpresume command = + printer name = + use client driver = No + + [homes] + + [printers] + path = /var/spool/samba + printable = Yes + +</screen></para> + +<para> +You can easily verify which settings were implicitly added by Samba's +default behaviour. <emphasis>Don't forget about this point: it may +be important in your future dealings with Samba.</emphasis> +</para> + +<note><para> testparm in Samba-3.0 behaves differently from 2.2.x: used +without the "-v" switch it only shows you the settings actually +written into <filename>smb.conf</filename>! To see the complete +configuration used, add the "-v" parameter to testparm.</para></note> + +</sect2> + +<sect2> +<title>A little Experiment to warn you</title> + +<para> +Should you need to troubleshoot at any stage, please always come back +to this point first and verify if "testparm" shows the parameters you +expect! To give you an example from personal experience as a warning, +try to just "comment out" the <parameter>load printers</parameter>" +parameter. If your 2.2.x system behaves like mine, you'll see this: +</para> + +<para><screen> + + kde-bitshop:/etc/samba # grep "load printers" smb.conf + # load printers = Yes + # This setting is commented ooouuuuut!! + + kde-bitshop:/etc/samba # testparm -v smb.conf | egrep "(load printers)" + load printers = Yes + +</screen></para> + +<para> +Despite my imagination that the commenting out of this setting should +prevent Samba from publishing my printers, it still did! Oh Boy -- it +cost me quite some time to find out the reason. But I am not fooled +any more... at least not by this ;-) +</para> + +<para><screen> + + kde-bitshop:/etc/samba # grep -A1 "load printers" smb.conf + load printers = No + # This setting is what I mean!! + # load printers = Yes + # This setting is commented ooouuuuut!! -<para>The initial listing of printers in the Samba host's -Printers folder will have no real printer driver assigned -to them. This defaults to a NULL string to allow the use -of the local Add Printer Wizard on NT/2000 clients. -Attempting to view the printer properties for a printer -which has this default driver assigned will result in -the error message:</para> + kde-bitshop:/etc/samba # testparm -v smb.conf.simpleprinting | egrep "(load printers)" + load printers = No + +</screen></para> + +<para> +Only when setting the parameter explicitly to +"<parameter>load printers = No</parameter>" +would Samba recognize my intentions. So my strong advice is: +</para> + +<itemizedlist> +<listitem><para>Never rely on "commented out" parameters!</para></listitem> + +<listitem><para>Always set it up explicitly as you intend it to +behave.</para></listitem> + +<listitem><para>Use <command>testparm</command> to uncover hidden +settings which might not reflect your intentions.</para></listitem> + +</itemizedlist> + +<para> +You can have a working Samba print configuration with this +minimal <filename>smb.conf</filename>: +</para> + +<para><screen> + + kde-bitshop:/etc/samba # cat /etc/samba/smb.conf-minimal + [printers] + +</screen></para> <para> -<emphasis>Device settings cannot be displayed. The driver -for the specified printer is not installed, only spooler -properties will be displayed. Do you want to install the -driver now?</emphasis> +This example should show you that you can use testparm to test any +filename for fitness as a Samba configuration. Actually, we want to +encourage you <emphasis>not</emphasis> to change your +<filename>smb.conf</filename> on a working system (unless you know +exactly what you are doing)! Don't rely on an assumption that changes +will only take effect after you re-start smbd! This is not the +case. Samba re-reads its <filename>smb.conf</filename> every 60 +seconds and on each new client connection. You might have to face +changes for your production clients that you didn't intend to apply at +this time! You will now note a few more interesting things. Let's now +ask <command>testparm</command> what the Samba print configuration +would be, if you used this minimalistic file as your real +<filename>smb.conf</filename>: </para> +<para><screen> + + kde-bitshop:~ # testparm -v /etc/samba/smb.conf-minimal | egrep "(print|lpq|spool|driver|ports|[)" + Processing section "[printers]" + WARNING: [printers] service MUST be printable! + No path in service printers - using /tmp + + lpq cache time = 10 + total print jobs = 0 + load printers = Yes + printcap name = /etc/printcap + disable spoolss = No + enumports command = + addprinter command = + deleteprinter command = + show add printer wizard = Yes + os2 driver map = + printer admin = + min print space = 0 + max print jobs = 1000 + printable = No + printing = bsd + print command = lpr -r -P%p %s + lpq command = lpq -P%p + printer name = + use client driver = No + [printers] + printable = Yes + +</screen></para> + <para> -Click "No" in the error dialog and you will be presented with -the printer properties window. The way to assign a driver to a -printer is to either +testparm issued 2 warnings: </para> - + <itemizedlist> - <listitem><para>Use the "New Driver..." button to install - a new printer driver, or</para></listitem> - - <listitem><para>Select a driver from the popup list of - installed drivers. Initially this list will be empty.</para> - </listitem> +<listitem><para>because we didn't specify the +<parameter>[printers]</parameter> section as printable, +and</para></listitem> + +<listitem><para>because we didn't tell it which spool directory to +use.</para></listitem> + </itemizedlist> - -<para>If you wish to install printer drivers for client -operating systems other than "Windows NT x86", you will need -to use the "Sharing" tab of the printer properties dialog.</para> - -<para>Assuming you have connected with a root account, you -will also be able modify other printer properties such as -ACLs and device settings using this dialog box.</para> - -<para>A few closing comments for this section, it is possible -on a Windows NT print server to have printers -listed in the Printers folder which are not shared. Samba does -not make this distinction. By definition, the only printers of -which Samba is aware are those which are specified as shares in -<filename>smb.conf</filename>.</para> - -<para>Another interesting side note is that Windows NT clients do -not use the SMB printer share, but rather can print directly -to any printer on another Windows NT host using MS-RPC. This -of course assumes that the printing client has the necessary -privileges on the remote host serving the printer. The default -permissions assigned by Windows NT to a printer gives the "Print" -permissions to the "Everyone" well-known group. + +<para> +However, this was not fatal, and Samba-3.0 will default to values that +will work here. But, please!, don't rely on this and don't use this +example! This was only meant to make you careful to design and specify +your setup to be what you really want it to be. The outcome on your +system may vary for some parameters, since you may have a Samba built +with a different compile-time configuration. +<emphasis>Warning:</emphasis> don't put a comment sign <emphasis>at +the end</emphasis> of a valid <filename>smb.conf</filename> line. It +will cause the parameter to be ignored (just as if you had put the +comment sign at the front). At first I regarded this as a bug in my +Samba version(s). But the man page states: <quote>Internal whitespace +in a parameter value is retained verbatim.</quote> This means that a +line consisting of, for example, +</para> + +<para><screen> +printing =lprng #This defines LPRng as the printing system" +</screen></para> + +<para> +will regard the whole of the string after the "=" +sign as the value you want to define. And this is an invalid value +that will be ignored, and a default value used instead.] +</para> +</sect2> +</sect1> + +<sect1> +<title>Extended Sample Configuration to Print with Samba-3</title> + +<para> +Here we show a more verbose example configuration for print related +settings in an <filename>smb.conf</filename>. Below is a discussion +and explanation of the various parameters. We chose to use BSD-style +printing here, because we guess it is still the most commonly used +system on legacy Linux installations (new installs now predominantly +have CUPS, which is discussed entirely in the next chapter of this +document). Note, that this example explicitly names many parameters +which don't need to be stated because they are set by default. You +might be able to do with a leaner <filename>smb.conf</filename>.</para> + +<tip><para> +if you read access it with the Samba Web Administration Tool (SWAT), +and then write it to disk again, it will be optimized in a way such +that it doesn't contain any superfluous parameters and comments. SWAT +organizes the file for best performance. Remember that each smbd +re-reads the Samba configuration once a minute, and that each +connection spawns an smbd process of its own, so it is not a bad idea +to optimize the <filename>smb.conf</filename> in environments with +hundreds or thousands of clients.</para></tip> + +<para><screen> + [global] + printing = bsd + load printers = yes + show add printer wizard = yes + printcap name = /etc/printcap + printer admin = @ntadmin, root + total print jobs = 100 + lpq cache time = 20 + use client driver = no + + [printers] + comment = All Printers + printable = yes + path = /var/spool/samba + browseable = no + guest ok = yes + public = yes + read only = yes + writable = no + + [my_printer_name] + comment = Printer with Restricted Access + path = /var/spool/samba_my_printer + printer admin = kurt + browseable = yes + printable = yes + writeable = no + hosts allow = 0.0.0.0 + hosts deny = turbo_xp, 10.160.50.23, 10.160.51.60 + guest ok = no +</screen></para> + +<para> +This <emphasis>also</emphasis> is only an example configuration. You +may not find all the settings in your own +<filename>smb.conf</filename> (as pre-configured by your OS +vendor). Many configuration parameters, if not explicitly set to a +specific value, are used and set by Samba implicitly to its own +default, because these have been compiled in. To see all settings, let +root use the <command>testparm</command> +utility. <command>testparm</command> also gives warnings if you have +mis-configured certain things.. </para> +</sect1> -</sect2> +<sect1> +<title>Detailed Explanation of the Example's Settings</title> +<para> +Following is a discussion of the settings from above shown example. +</para> <sect2> -<title>Support a large number of printers</title> - -<para>One issue that has arisen during the development -phase of Samba 2.2 is the need to support driver downloads for -100's of printers. Using the Windows NT APW is somewhat -awkward to say the list. If more than one printer are using the -same driver, the <ulink url="rpcclient.1.html"><command>rpcclient's -setdriver command</command></ulink> can be used to set the driver -associated with an installed driver. The following is example -of how this could be accomplished:</para> - -<para> -<prompt>$ </prompt><userinput>rpcclient pogo -U root%secret -c "enumdrivers"</userinput> -<programlisting> -Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3] - -[Windows NT x86] -Printer Driver Info 1: - Driver Name: [HP LaserJet 4000 Series PS] - -Printer Driver Info 1: - Driver Name: [HP LaserJet 2100 Series PS] - -Printer Driver Info 1: - Driver Name: [HP LaserJet 4Si/4SiMX PS] -</programlisting> -<prompt>$ </prompt><userinput>rpcclient pogo -U root%secret -c "enumprinters"</userinput> -<programlisting> -Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3] - flags:[0x800000] - name:[\\POGO\hp-print] - description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,] - comment:[] - -</programlisting> -<prompt>$ </prompt><userinput>rpcclient pogo -U root%secret -c "setdriver hp-print \"HP LaserJet 4000 Series PS\""</userinput> -<programlisting> -Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3] -Successfully set hp-print to driver HP LaserJet 4000 Series PS. -</programlisting></para> +<title>The [global] Section</title> + +<para> +The <parameter>[global]</parameter> section is one of 4 special +sections (along with [<parameter>[homes]</parameter>, +<parameter>[printers]</parameter> and +<parameter>[print$]</parameter>...) It contains all parameters which +apply to the server as a whole. It is the place for parameters which +have only a "global" meaning (G). It may also contain service level +parameters (S) which then define default settings for all other +sections and shares. This way you can simplify the configuration and +avoid setting the same value repeatedly. (Within each individual +section or share you may however override these globally set "share +level" settings and specify other values). +</para> + +<variablelist> +<varlistentry><term><parameter>printing = bsd</parameter></term> +<listitem><para> this causes Samba to use default print commands +applicable for the BSD (a.k.a. RFC 1179 style or LPR/LPD) printing +system. In general, the "printing" parameter informs Samba about the +print subsystem it should expect. Samba supports CUPS, LPD, LPRNG, +SYSV, HPUX, AIX, QNX and PLP. Each of these systems defaults to a +different "print command" (and other queue control +commands). <emphasis>Caution:</emphasis> The "printing" parameter is +normally a service level parameter. Since it is included here in the +<parameter>[global]</parameter> section, it will take effect for all +printer shares that are not defined differently. Samba-3.0 no longer +supports the SOFTQ printing system.</para></listitem></varlistentry> + +<varlistentry><term><parameter>load printers = yes</parameter></term> +<listitem><para> this tells Samba to create automatically all +available printer shares. "Available" printer shares are discovered by +scanning the printcap file. All created printer shares are also loaded +for browsing. If you use this parameter, you do not need to specify +separate shares for each printer. Each automatically created printer +share will clone the configuration options found in the +<parameter>[printers]</parameter> section. (A <parameter>load printers += no</parameter> setting will allow you to specify each UNIX printer +you want to share separately, leaving out some you don't want to be +publicly visible and available). </para></listitem></varlistentry> + +<varlistentry><term><parameter>show add printer wizard = +yes</parameter></term> <listitem><para> this setting is normally +enabled by default (even if the parameter is not written into the +<filename>smb.conf</filename>). It makes the "Add Printer Wizard" icon +show up in the "Printers" folder of the Samba host's share listing (as +shown in "Network Neighbourhood" or by the "net view" command). To +disable it, you need to explicitly set it to "no" (commenting it out +will not suffice!). The Add Printer Wizard lets you upload printer +drivers to the <parameter>[print$]</parameter> share and associate it +with a printer (if the respective queue exists there before the +action), or exchange a printer's driver against any other previously +uploaded driver. </para></listitem></varlistentry> + +<varlistentry><term><parameter>total print jobs = 100</parameter></term> +<listitem><para> this setting sets the upper limit to 100 print jobs +being active on the Samba server at any one time. Should a client +submit a job which exceeds this number, a <quote>no more space +available on server</quote> type of error message will be returned by +Samba to the client. A setting of "0" (the default) means there is +<emphasis>no</emphasis> limit at all! +</para></listitem></varlistentry> + +<varlistentry><term><parameter>printcap name = /etc/printcap</parameter></term> + +<listitem><para> this tells Samba where to look for a list of +available printer names. (If you use CUPS, make sure that a printcap +file is written: this is controlled by the "Printcap" directive of +<filename>cupsd.conf</filename>). +</para></listitem></varlistentry> + +<varlistentry><term><parameter>printer admin = @ntadmin</parameter></term> +<listitem><para> members of the ntadmin group should be able to add +drivers and set printer properties ("ntadmin" is only an example name, +it needs to be a valid UNIX group name); root is implicitly always a +'printer admin'. The "@" sign precedes group names in +<filename>smb.conf</filename>. A printer admin can do anything to +printers via the remote administration interfaces offered by MS-RPC +(see below). Note that the <parameter>printer admin</parameter> +parameter is normally a share level parameter, so you may associate +different groups to different printer shares in larger installations, +if you use the <parameter>printer admin</parameter> parameter on the +share levels). +</para></listitem></varlistentry> + +<varlistentry><term><parameter>lpq cache time = 20</parameter></term> +<listitem><para> this controls the cache time for the results of the +lpq command. It prevents the lpq command being called too often and +reduces load on a heavily used print server. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>use client driver = no</parameter></term> +<listitem><para> if set to "yes", this setting only takes effect for +Win NT/2k/XP clients (and not for Win 95/98/ME). Its default value is +"No" (or "False"). It must <emphasis>not</emphasis> be enabled on +print shares (with a "yes" or "true" setting) which have valid drivers +installed on the Samba server! For more detailed explanations see the +man page of <filename>smb.conf</filename>. +</para></listitem></varlistentry> +</variablelist> + </sect2> +<sect2> +<title>The [printers] Section</title> + +<para> +This is the second special section. If a section with this name +appears in the <filename>smb.conf</filename>, users are able to +connect to any printer specified in the Samba host's printcap file, +because Samba on startup then creates a printer share for every +printername it finds in the printcap file. You could regard this +section as a general convenience shortcut to share all printers with +minimal configuration. It is also a container for settings which +should apply as default to all printers. (For more details see the +<filename>smb.conf</filename> man page.) Settings inside this +container must be share level parameters (S). +</para> + +<variablelist> +<varlistentry><term><parameter>comment = All printers</parameter></term> +<listitem><para> the <parameter>comment</parameter> is shown next to +the share if a client queries the server, either via "Network +Neighbourhood" or with the <command>net view</command> command to list +available shares. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>printable = yes</parameter></term> +<listitem><para> please note well, that the +<parameter>[printers]</parameter> service <emphasis>must</emphasis> be +declared as printable. If you specify otherwise, smbd will refuse to +load <filename>smb.conf</filename> at startup. This parameter allows +connected clients to open, write to and submit spool files into the +directory specified with the <parameter>path</parameter> parameter for +this service. It is used by Samba to differentiate printer shares from +file shares. </para></listitem></varlistentry> + +<varlistentry><term><parameter>path = /var/spool/samba</parameter></term> +<listitem><para>this must point to a directory used by Samba to spool +incoming print files. <emphasis>It must not be the same as the spool +directory specified in the configuration of your UNIX print +subsystem!</emphasis> The path would typically point to a directory +which is world writeable, with the "sticky" bit set to it. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>browseable = no</parameter></term> +<listitem><para> this is always set to "no" if <parameter>printable = +yes</parameter>. It makes the [printer] share itself invisible in the +list of available shares in a <command>net view</command> command or +in the Explorer browse list. (Note that you will of course see the +individual printers). +</para></listitem></varlistentry> + +<varlistentry><term><parameter>guest ok = yes</parameter></term> + +<listitem><para> +if set to "yes", then no password is required to +connect to the printers service. Access will be granted with the +privileges of the "guest account". On many systems the guest +account will map to a user named "nobody". This user is in the UNIX +passwd file with an empty password, but with no valid UNIX login. +(Note: on some systems the guest account might not have the +privilege to be able to print. Test this by logging in as your +guest user using "su - guest" and run a system print command like +</para> + +<para><screen> +lpr -P printername /etc/motd +</screen></para> + +</listitem></varlistentry> + +<varlistentry><term><parameter>public = yes</parameter></term> +<listitem><para> this is a synonym for <parameter>guest ok = +yes</parameter>. Since we have <parameter>guest ok = yes</parameter>, +it really doesn't need to be here! (This leads to the interesting +question: <quote>What, if I by accident have to contradictory settings +for the same share?</quote> The answer is: the last one encountered by +Sambe wins. The "winner" is shown by testparm. Testparm doesn't +complain about different settings of the same parameter for the same +share! You can test this by setting up multiple lines for the "guest +account" parameter with different usernames, and then run testparm to +see which one is actually used by Samba.) +</para></listitem></varlistentry> + +<varlistentry><term><parameter>read only = yes</parameter></term> +<listitem><para>this normally (for other types of shares) prevents +users creating or modifying files in the service's directory. However, +in a "printable" service, it is <emphasis>always</emphasis> allowed to +write to the directory (if user privileges allow the connection), but +only via print spooling operations. "Normal" write operations are not +allowed. </para></listitem></varlistentry> + +<varlistentry><term><parameter>writeable = no</parameter></term> +<listitem><para> +synonym for <parameter>read only = yes</parameter> +</para></listitem></varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>Any [my_printer_name] Section</title> + +<para> +If a section appears in the <filename>smb.conf</filename>, which is +tagged as <parameter>printable = yes</parameter>, Samba presents it as +a printer share to its clients. Note, that Win95/98/ME clients may +have problems with connecting or loading printer drivers if the share +name has more than 8 characters! Also be very careful if you give a +printer the same name as an existing user or file share name: upon a +client's connection request to a certain sharename, Samba always tries +to find file shares with that name first; if it finds one, it will +connect to this and will never ultimately connect to a printer with +the same name! +</para> + +<variablelist> +<varlistentry><term><parameter>comment = Printer with Restricted Access</parameter></term> +<listitem><para> the comment says it all. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>path = /var/spool/samba_my_printer</parameter></term> +<listitem><para> here we set the spooling area for this printer to +another directory than the default. It is not a requirement to set it +differently, but the option is available. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>printer admin = kurt</parameter></term> +<listitem><para> the printer admin definition is different for this +explicitly defined printer share from the general +<parameter>[printers]</parameter> share. It is not a requirement; we +did it to show that it is possible if you want it. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>browseable = yes</parameter></term> +<listitem><para> we also made this printer browseable (so that the +clients may conveniently find it when browsing the Network +Neighbourhood). +</para></listitem></varlistentry> + +<varlistentry><term><parameter>printable = yes</parameter></term> +<listitem><para>see explanation in last subsection. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>writeable = no</parameter></term> +<listitem><para>see explanation in last subsection. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>hosts allow = 10.160.50.,10.160.51.</parameter></term> +<listitem><para>here we exercise a certain degree of access control +by using the "hosts allow" and "hosts deny" parameters. Note, that +this is not by any means a safe bet. It is not a way to secure your +printers. This line accepts all clients from a certain subnet in a +first evaluation of access control +</para></listitem></varlistentry> + +<varlistentry><term><parameter>hosts deny = turbo_xp,10.160.50.23,10.160.51.60 +</parameter></term> +<listitem><para>all listed hosts are not allowed here (even if they +belong to the "allowed subnets"). As you can see, you could name IP +addresses as well as NetBIOS hostnames +here. +</para></listitem></varlistentry> + +<varlistentry><term><parameter>guest ok = no</parameter></term> +<listitem><para>this printer is not open for the guest account! +</para></listitem></varlistentry> + +</variablelist> +</sect2> +<sect2> +<title>Print Commands</title> + +<para> +In each section defining a printer (or in the +<parameter>[printers]</parameter> section), a <parameter>print +command</parameter> parameter may be defined. It sets a command to +process the files which have been placed into the Samba print spool +directory for that printer. (That spool directory was, if you +remember, set up with the <parameter>path</parameter> +parameter). Typically, this command will submit the spool file to the +Samba host's print subsystem, using the suitable system print +command. But there is no requirement that this needs to be the +case. For debugging purposes or some other reason you may want to do +something completely different than "print" the file. An example is a +command that just copies the print file to a temporary location for +further investigation when you need to debug printing. If you craft +your own print commands (or even develop print command shell scripts), +make sure you pay attention to the need to remove the files from the +Samba spool directory. Otherwise your hard disk may soon suffer from +shortage of free space. +</para> +</sect2> <sect2> -<title>Adding New Printers via the Windows NT APW</title> - +<title>Default Print Commands for various Unix Print Subsystems</title> + <para> -By default, Samba offers all printer shares defined in <filename>smb.conf</filename> -in the "Printers..." folder. Also existing in this folder is the Windows NT -Add Printer Wizard icon. The APW will be show only if +You learned earlier on, that Samba in most cases uses its built-in +settings for many parameters if it can not find an explicitly stated +one in its configuration file. The same is true for the +<parameter>print command</parameter>. The default print command varies +depending on the <parameter>printing =...</parameter> parameter +setting. In the commands listed below, you will notice some parameters +of the form <emphasis>%X</emphasis> where <emphasis>X</emphasis> is +<emphasis>p, s, J</emphasis> etc. These letters stand for +"printername", "spoolfile" and "job ID" respectively. They are +explained in more detail further below. Here is an overview (excluding +the special case of CUPS, which is discussed in the next chapter): +</para> + +<informaltable frame='all'> +<tgroup cols='2' align='left' colsep='1' rowsep='1'> +<thead> +<row> +<entry>If this setting is active...</entry> +<entry>...this is used in lieu of an explicit command:</entry> +</row> +</thead> +<tbody> +<row> +<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry> +<entry>print command is <command>lpr -r -P%p %s</command></entry> +</row> +<row> +<entry><parameter>printing = sysv|hpux</parameter></entry> +<entry>print command is <command>lp -c -P%p %s; rm %s</command></entry> +</row> +<row> +<entry> <parameter>printing = qnx</parameter></entry> +<entry>print command is <command>lp -r -P%p -s %s</command></entry> +</row> +<row> +<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry> +<entry>lpq command is <command>lpq -P%p</command></entry> +</row> +<row> +<entry><parameter>printing = sysv|hpux</parameter></entry> +<entry>lpq command is <command>lpstat -o%p</command></entry> +</row> +<row> +<entry><parameter>printing = qnx</parameter></entry> +<entry>lpq command is <command>lpq -P%p</command></entry> +</row> +<row> +<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry> +<entry>lprm command is <command>lprm -P%p %j</command></entry> +</row> +<row> +<entry><parameter>printing = sysv|hpux</parameter></entry> +<entry>lprm command is <command>cancel %p-%j</command></entry> +</row> +<row> +<entry><parameter>printing = qnx</parameter></entry> +<entry>lprm command is <command>cancel %p-%j</command></entry> +</row> +<row> +<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry> +<entry>lppause command is <command>lp -i %p-%j -H hold</command></entry> +</row> +<row> +<entry><parameter>printing = sysv|hpux</parameter></entry> +<entry>lppause command (...is empty)</entry> +</row> +<row> +<entry><parameter>printing = qnx</parameter></entry> +<entry>lppause command (...is empty)</entry> +</row> +<row> +<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry> +<entry>lpresume command is <command>lp -i %p-%j -H resume</command></entry> +</row> +<row> +<entry><parameter>printing = sysv|hpux</parameter></entry> +<entry>lpresume command (...is empty)</entry> +</row> +<row> +<entry><parameter>printing = qnx</parameter></entry> +<entry>lpresume command (...is empty)</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +We excluded the special CUPS case here, because it is discussed in the +next chapter. Just a short summary. For <parameter>printing = +CUPS</parameter>: If SAMBA is compiled against libcups, it uses the +CUPS API to submit jobs, etc. (It is a good idea also to set +"<parameter>printcap = cups</parameter>" in case your +<filename>cupsd.conf</filename> is set to write its autogenerated +printcap file to an unusual place). Otherwise Samba maps to the System +V printing commands with the -oraw option for printing, i.e. it uses +<command>lp -c -d%p -oraw; rm %s</command> With <parameter>printing = +cups</parameter> , and if SAMBA is compiled against libcups, any +manually set print command will be ignored! +</para> + +<para> +Having listed the above mappings here, you should note that there used +to be a <emphasis>bug</emphasis> in recent 2.2.x versions which +prevented the mapping from taking effect. It lead to the +"bsd|aix|lprng|plp" settings taking effect for all other systems, for +the most important commands (the <command>print</command> command, the +<command>lpq</command> command and the <command>lprm</command> +command). The <command>lppause</command> command and the +<command>lpresume</command> command remained empty. Of course, these +commands worked on bsd|aix|lprng|plp but they didn't work on +sysv|hpux|qnx systems. To work around this bug, you need to +explicitly set the commands. Use <command>testparm -v</command> to +check which command takes effect. Then check that this command is +adequate and actually works for your installed print subsystem. It is +always a good idea to explicitly set up your configuration files the +way you want them to work and not rely on any built-in defaults. +</para> +</sect2> + +<sect2> +<title>Setting up your own Print Commands</title> + +<para> +After a print job has finished spooling to a service, the +<parameter>print command</parameter> will be used by Samba via a +<emphasis>system()</emphasis> call to process the spool file. Usually +the command specified will submit the spool file to the host's +printing subsystem. But there is no requirement at all that this must +be the case. The print subsystem will probably not remove the spool +file on its own. So whatever command you specify on your own you +should ensure that the spool file is deleted after it has been +processed. +</para> + +<para> +There is no difficulty with using your own customized print commands +with the traditional printing systems. However, if you don't wish to +"roll your own", you should be well informed about the default +built-in commands that Samba uses for each printing subsystem (see the +table above). In all the commands listed in the last paragraphs you +see parameters of the form <emphasis>%X</emphasis> These are +<emphasis>macros</emphasis>, or shortcuts, used as place holders for +the names of real objects. At the time of running a command with such +a placeholder, Samba will insert the appropriate value +automatically. Print commands can handle all Samba macro +substitutions. In regard to printing, the following ones do have +special relevance: </para> <itemizedlist> - <listitem><para>The connected user is able to successfully - execute an OpenPrinterEx(\\server) with administrative - privileges (i.e. root or <parameter>printer admin</parameter>). - </para></listitem> - - <listitem><para><ulink url="smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show - add printer wizard = yes</parameter></ulink> (the default). - </para></listitem> +<listitem><para><parameter>%s, %f</parameter> - the path to the spool +file name</para></listitem> + +<listitem><para><parameter>%p</parameter> - the appropriate printer +name</para></listitem> + +<listitem><para><parameter>%J</parameter> - the job name as +transmitted by the client.</para></listitem> + +<listitem><para><parameter>%c</parameter> - the number of printed +pages of the spooled job (if known).</para></listitem> + +<listitem><para><parameter>%z</parameter> - the size of the spooled +print job (in bytes)</para></listitem> + </itemizedlist> <para> -In order to be able to use the APW to successfully add a printer to a Samba -server, the <ulink url="smb.conf.5.html#ADDPRINTERCOMMAND"><parameter>add -printer command</parameter></ulink> must have a defined value. The program -hook must successfully add the printer to the system (i.e. -<filename>/etc/printcap</filename> or appropriate files) and -<filename>smb.conf</filename> if necessary. +The print command MUST contain at least one occurrence of +<parameter>%s</parameter> or <parameter>%f</parameter>. -- The +<parameter>%p</parameter> is optional. If no printer name is supplied, +the <parameter>%p</parameter> will be silently removed from the print +command. In this case the job is sent to the default printer. </para> <para> -When using the APW from a client, if the named printer share does -not exist, <command>smbd</command> will execute the <parameter>add printer -command</parameter> and reparse to the <filename>smb.conf</filename> -to attempt to locate the new printer share. If the share is still not defined, -an error of "Access Denied" is returned to the client. Note that the -<parameter>add printer program</parameter> is executed under the context -of the connected user, not necessarily a root account. -</para> - -<para> -There is a complementary <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>delete -printer command</parameter></ulink> for removing entries from the "Printers..." -folder. -</para> - -<para> -The following is an example <ulink url="smb.conf.5.html#ADDPRINTERCOMMAN"><parameter>add printer command</parameter></ulink> script. It adds the appropriate entries to <filename>/etc/printcap.local</filename> (change that to what you need) and returns a line of 'Done' which is needed for the whole process to work. -</para> - -<programlisting> -#!/bin/sh - -# Script to insert a new printer entry into printcap.local -# -# $1, printer name, used as the descriptive name -# $2, share name, used as the printer name for Linux -# $3, port name -# $4, driver name -# $5, location, used for the device file of the printer -# $6, win9x location - -# -# Make sure we use the location that RedHat uses for local printer defs -PRINTCAP=/etc/printcap.local -DATE=`date +%Y%m%d-%H%M%S` -LP=lp -RESTART="service lpd restart" - -# Keep a copy -cp $PRINTCAP $PRINTCAP.$DATE -# Add the printer to $PRINTCAP -echo "" >> $PRINTCAP -echo "$2|$1:\\" >> $PRINTCAP -echo " :sd=/var/spool/lpd/$2:\\" >> $PRINTCAP -echo " :mx=0:ml=0:sh:\\" >> $PRINTCAP -echo " :lp=/usr/local/samba/var/print/$5.prn:" >> $PRINTCAP - -touch "/usr/local/samba/var/print/$5.prn" >> /tmp/printadd.$$ 2>&1 -chown $LP "/usr/local/samba/var/print/$5.prn" >> /tmp/printadd.$$ 2>&1 - -mkdir /var/spool/lpd/$2 -chmod 700 /var/spool/lpd/$2 -chown $LP /var/spool/lpd/$2 -#echo $1 >> "/usr/local/samba/var/print/$5.prn" -#echo $2 >> "/usr/local/samba/var/print/$5.prn" -#echo $3 >> "/usr/local/samba/var/print/$5.prn" -#echo $4 >> "/usr/local/samba/var/print/$5.prn" -#echo $5 >> "/usr/local/samba/var/print/$5.prn" -#echo $6 >> "/usr/local/samba/var/print/$5.prn" -$RESTART >> "/usr/local/samba/var/print/$5.prn" -# Not sure if this is needed -touch /usr/local/samba/lib/smb.conf -# -# You need to return a value, but I am not sure what it means. -# -echo "Done" -exit 0 -</programlisting> +If specified in the <parameter>[global]</parameter> section, the print +command given will be used for any printable service that does not +have its own print command specified. If there is neither a specified +print command for a printable service nor a global print command, +spool files will be created but not processed! And (most importantly): +print files will not be removed, so they will start filling your Samba +hard disk. +</para> +<para> +Note that printing may fail on some UNIXes from the "nobody" +account. If this happens, create an alternative guest account and +supply it with the privilege to print. Set up this guest account in +the <parameter>[global]</parameter> section with the <parameter>guest +account</parameter> parameter. +</para> + +<para> +You can form quite complex print commands. You need to realize that +print commands are just passed to a UNIX shell. The shell is able to +expand the included environment variables as usual. (The syntax to +include a UNIX environment variable <parameter>$variable</parameter> +in <filename>smb.conf</filename> or in the Samba print command is +<parameter>%$variable</parameter>.) To give you a working +<parameter>print command</parameter> example, the following will log a +print job to <filename>/tmp/print.log</filename>, print the file, then +remove it. Note that ';' is the usual separator for commands in shell +scripts: +</para> + +<para><screen> +<![CDATA[ + print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s +]]> +</screen></para> + +<para> +You may have to vary your own command considerably from this example +depending on how you normally print files on your system. The default +for the <parameter>print command</parameter> parameter varies depending on the setting of +the <parameter>printing</parameter> parameter. Another example is: +</para> + +<para><screen> + print command = /usr/local/samba/bin/myprintscript %p %s +</screen></para> </sect2> +</sect1> + +<sect1> +<title>Innovations in Samba Printing since 2.2</title> + +<para> +Before version 2.2.0, Samba's print server support for Windows clients +was limited to the level of <emphasis>LanMan</emphasis> printing +calls. This is the same protocol level as Windows 9x PCs offer when +they share printers. Beginning with the 2.2.0 release, Samba started +to support the native Windows NT printing mechanisms. These are +implemented via <emphasis>MS-RPC</emphasis> (RPC = <emphasis>Remote +Procedure Calls</emphasis> ). MS-RPCs use the +<emphasis>SPOOLSS</emphasis> named pipe for all printing. +</para> + +<para> +The additional functionality provided by the new SPOOLSS support includes: +</para> + +<itemizedlist> +<listitem><para>Support for downloading printer driver files to Windows +95/98/NT/2000 clients upon demand (<emphasis>Point'n'Print</emphasis>); +</para></listitem> + +<listitem><para>Uploading of printer drivers via the Windows NT +<emphasis>Add Printer Wizard</emphasis> (APW) or the +<emphasis>Imprints</emphasis> tool set (refer to <ulink +url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net</ulink>); +</para></listitem> +<listitem><para>Support for the native MS-RPC printing calls such as +StartDocPrinter, EnumJobs(), etc... (See the MSDN documentation +at <ulink +url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink> +for more information on the Win32 printing API);</para></listitem> + +<listitem><para>Support for NT <emphasis>Access Control +Lists</emphasis> (ACL) on printer objects;</para></listitem> + +<listitem><para>Improved support for printer queue manipulation +through the use of internal databases for spooled job information +(implemented by various <filename>*.tdb</filename> +files).</para></listitem> + +</itemizedlist> + +<para> +One other benefit of an update is this: Samba-3 is able to publish +all its printers in Active Directory (or LDAP)! +</para> + +<para> +One slight difference is here: it is possible on a Windows NT print +server to have printers listed in the Printers folder which are +<emphasis>not</emphasis> shared. Samba does not make this +distinction. By definition, the only printers of which Samba is aware +are those which are specified as shares in +<filename>smb.conf</filename>. The reason is that Windows NT/2k/XPprof +clients do not normally need to use the standard SMB printer share; +rather they can print directly to any printer on another Windows NT +host using MS-RPC. This of course assumes that the printing client has +the necessary privileges on the remote host serving the printer. The +default permissions assigned by Windows NT to a printer gives the +"Print" permissions to the well-known <emphasis>Everyone</emphasis> +group. (The older clients of type Win9x can only print to "shared" +printers). +</para> <sect2> -<title>Samba and Printer Ports</title> +<title>Client Drivers on Samba Server for <emphasis>Point'n'Print</emphasis></title> <para> -Windows NT/2000 print servers associate a port with each printer. These normally -take the form of LPT1:, COM1:, FILE:, etc... Samba must also support the -concept of ports associated with a printer. By default, only one printer port, -named "Samba Printer Port", exists on a system. Samba does not really a port in -order to print, rather it is a requirement of Windows clients. +There is still confusion about what all this means: <emphasis>Is it or +is it not a requirement for printer drivers to be installed on a Samba +host in order to support printing from Windows clients?</emphasis> The +answer to this is: No, it is not a +<emphasis>requirement</emphasis>. Windows NT/2000 clients can, of +course, also run their APW to install drivers +<emphasis>locally</emphasis> (which then connect to a Samba served +print queue). This is the same method as used by Windows 9x +clients. (However, a <emphasis>bug</emphasis> existed in Samba 2.2.0 +which made Windows NT/2000 clients require that the Samba server +possess a valid driver for the printer. This was fixed in Samba +2.2.1). </para> <para> -Note that Samba does not support the concept of "Printer Pooling" internally -either. This is when a logical printer is assigned to multiple ports as -a form of load balancing or fail over. +But it is a new <emphasis>option</emphasis> to install the printer +drivers into the <parameter>[print$]</parameter> share of the Samba +server, and a big convenience too. Then <emphasis>all</emphasis> +clients (including 95/98/ME) get the driver installed when they first +connect to this printer share. The <emphasis>uploading</emphasis> or +<emphasis>depositing</emphasis> of the driver into this +<parameter>[print$]</parameter> share, and the following binding of +this driver to an existing Samba printer share can be achieved by +different means: </para> +<itemizedlist> +<listitem><para>running the <emphasis>APW</emphasis> on an +NT/2k/XPprof client (this doesn't work from 95/98/ME +clients);</para></listitem> + +<listitem><para>using the <emphasis>Imprints</emphasis> +toolset;</para></listitem> + +<listitem><para>using the <emphasis>smbclient</emphasis> and +<emphasis>rpcclient</emphasis> commandline tools;</para></listitem> + +<listitem><para>using <emphasis>cupsaddsmb</emphasis>(only works for +the CUPS printing system, not for LPR/LPD, LPRng +etc.).</para></listitem> + +</itemizedlist> + <para> -If you require that multiple ports be defined for some reason, -<filename>smb.conf</filename> possesses a <ulink -url="smb.conf.5.html#ENUMPORTSCOMMAND"><parameter>enumports -command</parameter></ulink> which can be used to define an external program -that generates a listing of ports on a system. +Please take additional note of the following fact: <emphasis>Samba +does not use these uploaded drivers in any way to process spooled +files</emphasis>. Drivers are utilized entirely by the clients, who +download and install them via the "Point 'n'Print" mechanism supported +by Samba. The clients use these drivers to generate print files in the +format the printer (or the Unix print system) requires. Print files +received by Samba are handed over to the Unix printing system, which +is responsible for all further processing, if needed. </para> +</sect2> + +<sect2> +<title>The [printer$] Section is removed from Samba-3</title> +<formalpara><title> +<parameter>[print$]</parameter> vs. <parameter>[printer$]</parameter> +</title> + +<para> +Versions of Samba prior to 2.2 made it possible to use a share +named <emphasis>[printer$]</emphasis>. This name was taken from the +same named service created by Windows 9x clients when a printer was +shared by them. Windows 9x printer servers always have a +<parameter>[printer$]</parameter> service which provides read-only +access (with no password required) in order to support printer driver +downloads. However, Samba's initial implementation allowed for a +parameter named <parameter>printer driver location</parameter> to be +used on a per share basis. This specified the location of the driver +files associated with that printer. Another parameter named +<parameter>printer driver</parameter> provided a means of defining the +printer driver name to be sent to the client. These parameters, +including the <parameter>printer driver file</parameter> parameter, +are now removed and can not be used in installations of Samba-3.0. +Now the share name <parameter>[print$]</parameter> is used for the +location of downloadable printer drivers. It is taken from the +<parameter>[print$]</parameter> service created by Windows NT PCs when +a printer is shared by them. Windows NT print servers always have a +<parameter>[print$]</parameter> service which provides read-write +access (in the context of its ACLs) in order to support printer driver +down- and uploads. Don't fear -- this does not mean Windows 9x +clients are thrown aside now. They can use Samba's +<parameter>[print$]</parameter> share support just fine. +</para></formalpara> </sect2> -</sect1> +<sect2> +<title>Creating the [print$] Share</title> +<para> +In order to support the up- and downloading of printer driver files, +you must first configure a file share named +<parameter>[print$]</parameter>. The "public" name of this share is +hard coded in Samba's internals (because it is hardcoded in the MS +Windows clients too). It cannot be renamed since Windows clients are +programmed to search for a service of exactly this name if they want +to retrieve printer driver files. +</para> -<sect1> - <title>The Imprints Toolset</title> - - <para>The Imprints tool set provides a UNIX equivalent of the - Windows NT Add Printer Wizard. For complete information, please - refer to the Imprints web site at <ulink url="http://imprints.sourceforge.net/"> - http://imprints.sourceforge.net/</ulink> as well as the documentation - included with the imprints source distribution. This section will - only provide a brief introduction to the features of Imprints.</para> - - - <sect2> - <title>What is Imprints?</title> - - <para>Imprints is a collection of tools for supporting the goals - of</para> - - <itemizedlist> - <listitem><para>Providing a central repository information - regarding Windows NT and 95/98 printer driver packages</para> - </listitem> - - <listitem><para>Providing the tools necessary for creating - the Imprints printer driver packages.</para></listitem> - - <listitem><para>Providing an installation client which - will obtain and install printer drivers on remote Samba - and Windows NT 4 print servers.</para></listitem> - </itemizedlist> - - </sect2> - - - <sect2> - <title>Creating Printer Driver Packages</title> - - <para>The process of creating printer driver packages is beyond - the scope of this document (refer to Imprints.txt also included - with the Samba distribution for more information). In short, - an Imprints driver package is a gzipped tarball containing the - driver files, related INF files, and a control file needed by the - installation client.</para> - </sect2> - - - <sect2> - <title>The Imprints server</title> - - <para>The Imprints server is really a database server that - may be queried via standard HTTP mechanisms. Each printer - entry in the database has an associated URL for the actual - downloading of the package. Each package is digitally signed - via GnuPG which can be used to verify that package downloaded - is actually the one referred in the Imprints database. It is - <emphasis>not</emphasis> recommended that this security check - be disabled.</para> - </sect2> - - <sect2> - <title>The Installation Client</title> - - <para>More information regarding the Imprints installation client - is available in the <filename>Imprints-Client-HOWTO.ps</filename> - file included with the imprints source package.</para> - - <para>The Imprints installation client comes in two forms.</para> - - <itemizedlist> - <listitem><para>a set of command line Perl scripts</para> - </listitem> - - <listitem><para>a GTK+ based graphical interface to - the command line perl scripts</para></listitem> - </itemizedlist> - - <para>The installation client (in both forms) provides a means - of querying the Imprints database server for a matching - list of known printer model names as well as a means to - download and install the drivers on remote Samba and Windows - NT print servers.</para> - - <para>The basic installation process is in four steps and - perl code is wrapped around <command>smbclient</command> - and <command>rpcclient</command>.</para> - -<para><programlisting> -foreach (supported architecture for a given driver) -{ - 1. rpcclient: Get the appropriate upload directory - on the remote server - 2. smbclient: Upload the driver files - 3. rpcclient: Issues an AddPrinterDriver() MS-RPC -} - -4. rpcclient: Issue an AddPrinterEx() MS-RPC to actually - create the printer -</programlisting></para> - - <para>One of the problems encountered when implementing - the Imprints tool set was the name space issues between - various supported client architectures. For example, Windows - NT includes a driver named "Apple LaserWriter II NTX v51.8" - and Windows 95 calls its version of this driver "Apple - LaserWriter II NTX"</para> - - <para>The problem is how to know what client drivers have - been uploaded for a printer. As astute reader will remember - that the Windows NT Printer Properties dialog only includes - space for one printer driver name. A quick look in the - Windows NT 4.0 system registry at</para> - - <para><filename>HKLM\System\CurrentControlSet\Control\Print\Environment - </filename></para> - - <para>will reveal that Windows NT always uses the NT driver - name. This is ok as Windows NT always requires that at least - the Windows NT version of the printer driver is present. - However, Samba does not have the requirement internally. - Therefore, how can you use the NT driver name if is has not - already been installed?</para> - - <para>The way of sidestepping this limitation is to require - that all Imprints printer driver packages include both the Intel - Windows NT and 95/98 printer drivers and that NT driver is - installed first.</para> - </sect2> - -</sect1> +<para> +You should modify the server's <filename>smb.conf</filename> file to +add the global parameters and create the +<parameter>[print$]</parameter> file share (of course, some of the +parameter values, such as 'path' are arbitrary and should be replaced +with appropriate values for your site): +</para> -<!-- - - This comment from rpc_server/srv_spoolss_nt.c:_spoolss_open_printer_ex() - needs to be added into a section probably. This is to remind me it needs - to be done. -jerry - - /* - * If the openprinterex rpc call contains a devmode, - * it's a per-user one. This per-user devmode is derivated - * from the global devmode. Openprinterex() contains a per-user - * devmode for when you do EMF printing and spooling. - * In the EMF case, the NT workstation is only doing half the job - * of rendering the page. The other half is done by running the printer - * driver on the server. - * The EMF file doesn't contain the page description (paper size, orientation, ...). - * The EMF file only contains what is to be printed on the page. - * So in order for the server to know how to print, the NT client sends - * a devicemode attached to the openprinterex call. - * But this devicemode is short lived, it's only valid for the current print job. - * - * If Samba would have supported EMF spooling, this devicemode would - * have been attached to the handle, to sent it to the driver to correctly - * rasterize the EMF file. - * - * As Samba only supports RAW spooling, we only receive a ready-to-print file, - * we just act as a pass-thru between windows and the printer. - * - * In order to know that Samba supports only RAW spooling, NT has to call - * getprinter() at level 2 (attribute field) or NT has to call startdoc() - * and until NT sends a RAW job, we refuse it. - * - * But to call getprinter() or startdoc(), you first need a valid handle, - * and to get an handle you have to call openprintex(). Hence why you have - * a devicemode in the openprinterex() call. - * - * - * Differences between NT4 and NT 2000. - * NT4: - * - * On NT4, you only have a global devicemode. This global devicemode can be changed - * by the administrator (or by a user with enough privs). Every time a user - * wants to print, the devicemode is reset to the default. In Word, every time - * you print, the printer's characteristics are always reset to the global devicemode. - * - * NT 2000: - * - * In W2K, there is the notion of per-user devicemode. The first time you use - * a printer, a per-user devicemode is build from the global devicemode. - * If you change your per-user devicemode, it is saved in the registry, under the - * H_KEY_CURRENT_KEY sub_tree. So that every time you print, you have your default - * printer preferences available. - * - * To change the per-user devicemode: it's the "Printing Preferences ..." button - * on the General Tab of the printer properties windows. - * - * To change the global devicemode: it's the "Printing Defaults..." button - * on the Advanced Tab of the printer properties window. ---> +<para><screen> + [global] + ; members of the ntadmin group should be able to add drivers and set + ; printer properties. root is implicitly always a 'printer admin'. + printer admin = @ntadmin + [....] + + [printers] + [....] + + [print$] + comment = Printer Driver Download Area + path = /etc/samba/drivers + browseable = yes + guest ok = yes + read only = yes + write list = @ntadmin, root +</screen></para> -<sect1> -<title>Diagnosis</title> +<para> +Of course, you also need to ensure that the directory named by the +<parameter>path</parameter> parameter exists on the Unix file system. +</para> + +</sect2> <sect2> -<title>Introduction</title> +<title>Parameters in the <parameter>[print$]</parameter> Section</title> <para> -This is a short description of how to debug printing problems with -Samba. This describes how to debug problems with printing from a SMB -client to a Samba server, not the other way around. For the reverse -see the examples/printing directory. +<parameter>[print$]</parameter> is a special section in +<filename>smb.conf</filename>. It contains settings relevant to +potential printer driver download and local installation by clients. </para> +<variablelist> +<varlistentry><term><parameter>comment = Printer Driver +Download Area</parameter></term> +<listitem><para> the comment appears next to the share name if it is +listed in a share list (usually Windows clients won't see it often but +it will also appear up in a <command>smbclient -L sambaserver +</command> output). </para></listitem></varlistentry> + +<varlistentry><term><parameter>path = /etc/samba/printers</parameter></term> +<listitem><para> this is the path to the location of the Windows +driver file deposit from the UNIX point of +view.</para></listitem></varlistentry> + +<varlistentry><term><parameter>browseable = no</parameter></term> +<listitem><para> this makes the <parameter>[print$]</parameter> share +"invisible" in Network Neighbourhood to clients. However, you can +still "mount" it from any client using the <command>net use +g:\\sambaserver\print$</command> command in a "DOS box" or the +"Connect network drive" menu from Windows +Explorer.</para></listitem></varlistentry> + +<varlistentry><term><parameter>guest ok = yes</parameter></term> +<listitem><para>this gives read only access to this share for all +guest users. Access may be used to download and install printer +drivers on clients. The requirement for <parameter>guest ok = +yes</parameter> depends upon how your site is configured. If users +will be guaranteed to have an account on the Samba host, then this is +a non-issue.</para> + +<note><para> +The non-issue is this: if all your Windows NT users are guaranteed to +be authenticated by the Samba server (for example if Samba +authenticates via an NT domain server and the NT user has already been +validated by the Domain Controller in order to logon to the Windows NT +session), then guest access is not necessary. Of course, in a +workgroup environment where you just want to be able to print without +worrying about silly accounts and security, then configure the share +for guest access. You'll probably want to add <parameter>map to guest += Bad User</parameter> in the <parameter>[global]</parameter> section +as well. Make sure you understand what this parameter does before +using it. +</para></note> </listitem></varlistentry> + +<varlistentry><term><parameter>read only = yes</parameter></term> +<listitem><para>as we don't want everybody to upload driver files (or +even change driver settings) we tagged this share as not +writeable.</para></listitem></varlistentry> + +<varlistentry><term><parameter>write list = @ntadmin,root</parameter></term> +<listitem><para>since the <parameter>[print$]</parameter> was made +read only by the previous setting, we need to create a "write list" +also. UNIX groups (denoted with a leading "@" character) and users +listed here are allowed write access (as an exception to the general +public's "read-only" access), which they need to update files on the +share. Normally you will want to only name administrative level user +accounts in this setting. Check the file system permissions to make +sure these accounts can copy files to the share. If this is a non-root +account, then the account should also be mentioned in the global +<parameter>printer admin </parameter> parameter. See the +<filename>smb.conf</filename> man page for more information on +configuring file shares. </para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2> +<title>Subdirectory Structure in <parameter>[print$]</parameter></title> + <para> -Ok, so you want to print to a Samba server from your PC. The first -thing you need to understand is that Samba does not actually do any -printing itself, it just acts as a middleman between your PC client -and your Unix printing subsystem. Samba receives the file from the PC -then passes the file to a external "print command". What print command -you use is up to you. +In order for a Windows NT print server to support the downloading of +driver files by multiple client architectures, you must create several +subdirectories within the <parameter>[print$]</parameter> service +(i.e. the Unix directory named by the <parameter>path</parameter> +parameter). These correspond to each of the supported client +architectures. Samba follows this model as well. Just like the name of +the <parameter>[print$]</parameter> share itself, the subdirectories +*must* be exactly the names listed below (you may leave out the +subdirectories of architectures you don't want to support). </para> <para> -The whole things is controlled using options in smb.conf. The most -relevant options (which you should look up in the smb.conf man page) -are: +Therefore, create a directory tree below the +<parameter>[print$]</parameter> share for each architecture you wish +to support. </para> -<para><programlisting> - [global] - print command - send a file to a spooler - lpq command - get spool queue status - lprm command - remove a job - [printers] - path = /var/spool/lpd/samba -</programlisting></para> +<para><screen> + +[print$]--+-- + |--W32X86 # serves drivers to "Windows NT x86" + |--WIN40 # serves drivers to "Windows 95/98" + |--W32ALPHA # serves drivers to "Windows NT Alpha_AXP" + |--W32MIPS # serves drivers to "Windows NT R4000" + |--W32PPC # serves drivers to "Windows NT PowerPC" + +</screen></para> + +<important><title>REQUIRED PERMISSIONS</title> <para> -The following are nice to know about: +In order to add a new driver to your Samba host, one of two conditions +must hold true: </para> -<para><programlisting> - queuepause command - stop a printer or print queue - queueresume command - start a printer or print queue -</programlisting></para> +<itemizedlist> +<listitem><para>The account used to connect to the Samba host must +have a UID of 0 (i.e. a root account)</para></listitem> + +<listitem><para>The account used to connect to the Samba host must be +named in the <emphasis>printer admin</emphasis>list.</para></listitem> + +</itemizedlist> + +<para> +Of course, the connected account must still possess access to add +files to the subdirectories beneath +<parameter>[print$]</parameter>. Remember that all file shares are set +to 'read only' by default. +</para> +</important> + +<para> +Once you have created the required <parameter>[print$]</parameter> +service and associated subdirectories, go to a Windows NT 4.0/2k/XP +client workstation. Open "Network Neighbourhood" or "My Network +Places" and browse for the Samba host. Once you have located the +server, navigate to its "Printers and Faxes" folder. You should see +an initial listing of printers that matches the printer shares defined +on your Samba host. +</para> +</sect2> +</sect1> + +<sect1> +<title>Installing Drivers into [print$]</title> + +<para> +You have successfully created the <parameter>[print$]</parameter> +share in <filename>smb.conf</filename>? And Samba has re-read its +configuration? Good. But you are not yet ready to take off. The +<emphasis>driver files</emphasis> need to be present in this share, +too! So far it is still an empty share. Unfortunatly, it is not enough +to just copy the driver files over. They need to be <emphasis>set +up</emphasis> too. And that is a bit tricky, to say the least. We +will now discuss two alternative ways to install the drivers into +<parameter>[print$]</parameter>: +</para> + +<itemizedlist> + +<listitem><para>using the Samba commandline utility +<command>rpcclient</command> with its various subcommands (here: +<command>adddriver</command> and <command>setdriver</command>) from +any UNIX workstation;</para></listitem> + +<listitem><para>running a GUI (<emphasis>Printer +Properties</emphasis> and <emphasis>Add Printer Wizard</emphasis>) +from any Windows NT/2k/XP client workstation.</para></listitem> + +</itemizedlist> <para> -Example: +The latter option is probably the easier one (even if the only +entrance to this realm seems a little bit weird at first). </para> -<para><programlisting> - print command = /usr/bin/lpr -r -P%p %s - lpq command = /usr/bin/lpq -P%p %s - lprm command = /usr/bin/lprm -P%p %j - queuepause command = /usr/sbin/lpc -P%p stop - queuepause command = /usr/sbin/lpc -P%p start -</programlisting></para> +<sect2> +<title>Setting Drivers for existing Printers with a Client GUI</title> + +<para> +The initial listing of printers in the Samba host's +<emphasis>Printers</emphasis> folder accessed from a client's Explorer +will have no real printer driver assigned to them. By default, in +Samba-3 (as in 2.2.1 and later) this driver name is set to a NULL +string. This must be changed now. The local <emphasis>Add Printer +Wizard</emphasis>, run from NT/2000/XP clients, will help us in this +task. +</para> <para> -Samba should set reasonable defaults for these depending on your -system type, but it isn't clairvoyant. It is not uncommon that you -have to tweak these for local conditions. The commands should -always have fully specified pathnames, as the smdb may not have -the correct PATH values. +However, the job to set a valid driver for the printer is not a +straightforward one: You must attempt to view the printer properties +for the printer to which you want the driver assigned. Open the +Windows Explorer, open Network Neighbourhood, browse to the Samba +host, open Samba's <guiicon>Printers</guiicon> folder, right-click the printer icon and +select <guimenu>Properties...</guimenu>. You are now trying to view printer and driver +properties for a queue which has this default <constant>NULL</constant> driver +assigned. This will result in an error message (this is normal here): </para> +<para><computeroutput> Device settings cannot be displayed. The driver +for the specified printer is not installed, only spooler properties +will be displayed. Do you want to install the driver +now?</computeroutput></para> + <para> -When you send a job to Samba to be printed, it will make a temporary -copy of it in the directory specified in the [printers] section. -and it should be periodically cleaned out. The lpr -r option -requests that the temporary copy be removed after printing; If -printing fails then you might find leftover files in this directory, -and it should be periodically cleaned out. Samba used the lpq -command to determine the "job number" assigned to your print job -by the spooler. +<emphasis>Important:</emphasis>Don't click "Yes"! Instead, +<emphasis>click "No"</emphasis> in the error dialog. Only now you will +be presented with the printer properties window. From here, the way to +assign a driver to a printer is open to us. You have now the choice +either: </para> +<itemizedlist> +<listitem><para>select a driver from the popup list of installed +drivers. <emphasis>Initially this list will be empty.</emphasis> +Or</para></listitem> + +<listitem><para>use the <emphasis>"New Driver..."</emphasis> button to +install a new printer driver (which will in fact start up the +APW).</para></listitem> +</itemizedlist> + <para> -The %>letter< are "macros" that get dynamically replaced with appropriate -values when they are used. The %s gets replaced with the name of the spool -file that Samba creates and the %p gets replaced with the name of the -printer. The %j gets replaced with the "job number" which comes from -the lpq output. +Once the APW is started, the procedure is exactly the same as the one +you are familiar with in Wiindows (we assume here that you are +familiar with the printer driver installations procedure on Windows +NT). Make sure your connection is in fact setup as a user with +<emphasis>printer admin</emphasis> privileges (if in doubt, use +<command>smbstatus</command> to check for this). If you wish to +install printer drivers for client operating systems other than +"Windows NT x86", you will need to use the +<emphasis>Sharing</emphasis> tab of the printer properties dialog. </para> +<para> +Assuming you have connected with an administrative (or root) account +(as named by the <parameter>printer admin</parameter> parameter), +you will also be able to modify other printer properties such as ACLs +and default device settings using this dialog. For the default device +settings, please consider the advice given further below. +</para> </sect2> <sect2> -<title>Debugging printer problems</title> +<title>Setting Drivers for existing Printers with +<command>rpcclient</command></title> + +<para> +The second way to install printer drivers into +<parameter>[print$]</parameter> and set them up in a valid way can be +done from the UNIX command line. This involves four distinct steps: +</para> + +<orderedlist> +<listitem><para> gathering the info about the required driver files +and collecting the files together;</para></listitem> + +<listitem><para> deposit the driver files into the +<parameter>[print$]</parameter> share's correct subdirectories +(possibly by using <command>smbclient</command>);</para></listitem> + +<listitem><para>2. -- running the <command>rpcclient</command> +commandline utility once with the <command>addriver</command> +subcommand,</para></listitem> + +<listitem><para>3. -- running <command>rpcclient</command> a second +time with the <command>setdriver</command> +subcommand.</para></listitem> +</orderedlist> + +<para> +We will provide detailed hints for each of these steps in the next few +paragraphs. +</para> + +<sect3> +<title>Identifying the Driver Files</title> + +<para> +To find out about the driver files, you have two options: you could +investigate the driver CD which comes with your printer. Study the +<filename>*.inf</filename> file on the CD, if it is contained. This +may not be the possible, since the *.inf file might be +missing. Unfortunately, many vendors have now started to use their own +installation programs. These installations packages are often some +sort of Windows platform archive format, plus, the files may get +re-named during the installation process. This makes it extremely +difficult to identify the driver files you need. +</para> + +<para> +Then you only have the second option: install the driver first on a +Windows client *locally* and investigate which file names and paths it +uses after they are installed. (Note, that you need to repeat this +procedure for every client platform you want to support. We are going +to show it here for the "<emphasis>W32X86</emphasis>" platform only, a +name used by Microsoft for all WinNT/2k/XP clients...) +</para> + +<para> +A good method to recognize the driver files this is to print the test +page from the driver's <emphasis>Properties</emphasis> Dialog +(<emphasis>General</emphasis> tab). Then look at the list of driver +files named on the printout. You'll need to recognize what Windows +(and Samba) are calling the <parameter>Driver File</parameter> , the +<parameter>Data File</parameter>, the <parameter>Config File</parameter>, +the <parameter>Help File</parameter> and (optionally) the +<parameter>Dependent Driver Files</parameter> (this may vary slightly +for Windows NT). You need to remember all names (or better take a +note) for the next steps. +</para> + +<para> +Another method to quickly test the driver filenames and related paths +is provided by the <command>rpcclient</command> utility. Run it with +<command>enumdrivers</command> or with the +<command>getdriver</command> subcommand, each in the +<emphasis>3</emphasis> level. In the following example, +<emphasis>TURBO_XP</emphasis> is the name of the Windows PC (in this +case it was a Windows XP Professional laptop, BTW). I had installed +the driver locally to TURBO_XP while <emphasis>kde-bitshop</emphasis> is +the name of the Linux host from which I am working. We could run an +<emphasis>interactive</emphasis> <command>rpcclient</command> session; +then we'd get an <emphasis>rpcclient /></emphasis> prompt and would +type the subcommands at this prompt. This is left as a good exercise +to the reader. For now we use <command>rpcclient</command> with the +<parameter>-c</parameter> parameter to execute a single subcommand +line and exit again. This is the method you would use if you want to +create scripts to automate the procedure for a large number of +printers and drivers. Note the different quotes used to overcome the +different spaces in between words: +</para> + +<para><screen> + + kde-bitshop:~# rpcclient -U'Danka%xxxx' -c 'getdriver "Heidelberg Digimaster 9110 (PS)" 3' TURBO_XP + cmd = getdriver "Heidelberg Digimaster 9110 (PS)" 3 + + [Windows NT x86] + Printer Driver Info 3: + Version: [2] + Driver Name: [Heidelberg Digimaster 9110 (PS)] + Architecture: [Windows NT x86] + Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01_de.DLL] + Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.ppd] + Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01U_de.DLL] + Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01U_de.HLP] + + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.DLL] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.INI] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1KMMin.DLL] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.dat] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.cat] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.def] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.hre] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.vnd] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.hlp] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de_reg.HLP] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01Aux.dll] + Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01_de.NTF] + + Monitorname: [] + Defaultdatatype: [] + +</screen></para> + +<para> +You may notice, that this driver has quite a big number of +"Dependentfiles" (I know worse cases however). Also, strangely, the +"<filename>Driver File</filename>" is here tagged as "<filename>Driver +Path</filename>".... oh, well. Here we don't have yet support for the +so-called "WIN40" architecture installed. This name is used by +Microsoft for the Win95/98/ME platforms. If we want to support these, +we need to install the Win95/98/ME driver files in addition to those +for W32X86 (i.e. the WinNT72000/XP clients) onto a Windows PC. This PC +can also host the Win9x drivers, even if itself runs on Windows NT, +2000 or XP. +</para> + +<para> +Since the <parameter>print$</parameter> share is usually accessible +through the Network Neighbourhood, you can also use the UNC notation +from Windows Explorer to poke at it. The Win9x driver files will end +up in subdirectory "0" of the "WIN40" directory. The full path to +access them will be +<filename>\\WINDOWSHOST\print$\WIN40\0\</filename>. +</para> + +<note><para> more recent drivers on Windows 2000 and Wndows XP are +installed into the "3" subdirectory instead of the "2". The version 2 +of drivers, as used in Windows NT, were running in Kernel Mode. +Windows 2000 changed this. While it still can use the Kernel Mode +drivers (if this is enabled by the Admin), its native mode for printer +drivers is User Mode execution. This requires drivers designed for +this. These type of drivers install into the "3" subdirectory. +</para></note> +</sect3> + +<sect3> +<title>Collecting the Driver Files from a Windows Host's +<parameter>[print$]</parameter> Share</title> + +<para> +Now we need to collect all the driver files we identified. in our +previous step. Where do we get them from? Well, why not retrieve them +from the very PC and the same <parameter>[print$]</parameter> share +which we investigated in our last step to identify the files? We can +use <command>smbclient</command> to do this. We will use the paths and +names which were leaked to us by <command>getdriver</command>. The +listing is edited to include linebreaks for readability: +</para> + +<para><screen> + + kde-bitshop:~# smbclient //TURBO_XP/print\$ -U'Danka%xxxx' \ + -c 'cd W32X86/2;mget HD*_de.* \ + hd*ppd Hd*_de.* Hddm*dll HDN*Aux.DLL' + added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 + Got a positive name query response from 10.160.50.8 ( 10.160.50.8 ) + Domain=[DEVELOPMENT] OS=[Windows 5.1] Server=[Windows 2000 LAN Manager] + Get file Hddm91c1_de.ABD? n + Get file Hddm91c1_de.def? y + getting file \W32X86\2\Hddm91c1_de.def of size 428 as Hddm91c1_de.def (22.0 kb/s) \ + (average 22.0 kb/s) + Get file Hddm91c1_de.DLL? y + getting file \W32X86\2\Hddm91c1_de.DLL of size 876544 as Hddm91c1_de.DLL (737.3 kb/s) \ + (average 737.3 kb/s) + [...,] + +</screen></para> + +<para> +After this command is complete, the files are in our current local +directory. You probably have noticed that this time we passed several +commands to the "-c" parameter, separated by semi-colons. This +effects that all commands are executed in sequence on the remote +Windows server before smbclient exits again. +</para> + +<para> +Don't forget to repeat the procedure for the "WIN40" architecture +should you need to support Win95/98/XP clients. Remember, the files +for these architectures are in the WIN40/0/ subdir. Once we are +complete, we can run <command>smbclient ... put</command> to store +the collected files on the Samba server's +<parameter>[print$]</parameter> share. +</para> +</sect3> + +<sect3> +<title>Depositing the Driver Files into <parameter>[print$]</parameter></title> + +<para> +So, now we are going to put the driver files into the +<parameter>[print$]</parameter> share. Remember, the UNIX path to this +share has been defined previously in your +<filename>smb.conf</filename>. You also have created subdirectories +for the different Windows client types you want to support. Supposing +your <parameter>[print$]</parameter> share maps to the UNIX path +<filename>/etc/samba/drivers/</filename>, your driver files should now +go here: +</para> + +<itemizedlist> +<listitem><para>for all Windows NT, 2000 and XP clients into +<filename>/etc/samba/drivers/W32X86/</filename> <emphasis>but +*not*(yet) into the "2" subdir</emphasis>!</para></listitem> + +<listitem><para>for all Windows 95, 98 and ME clients into +<filename>/etc/samba/drivers/WIN40/</filename> -- <emphasis>but *not* +(yet) into the "0" subdir</emphasis>!</para></listitem> +</itemizedlist> + +<para> +We again use smbclient to transfer the driver files across the +network. We specify the same files and paths as were leaked to us by +running "<command>getdriver</command>" against the original +<emphasis>Windows</emphasis> install. However, now we are going to +store the files into a <emphasis>Samba/UNIX</emphasis> print server's +<parameter>[print$]</parameter> share... +</para> + +<para><screen> + + kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -U'root%xxxx' -c 'cd W32X86; put HDNIS01_de.DLL; \ + put Hddm91c1_de.ppd; put HDNIS01U_de.DLL; \ + put HDNIS01U_de.HLP; put Hddm91c1_de.DLL; \ + put Hddm91c1_de.INI; put Hddm91c1KMMin.DLL; \ + put Hddm91c1_de.dat; put Hddm91c1_de.dat; \ + put Hddm91c1_de.def; put Hddm91c1_de.hre; \ + put Hddm91c1_de.vnd; put Hddm91c1_de.hlp; \ + put Hddm91c1_de_reg.HLP; put HDNIS01Aux.dll; \ + put HDNIS01_de.NTF' + added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 + Got a positive name query response from 10.160.51.162 ( 10.160.51.162 ) + Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a] + putting file HDNIS01_de.DLL as \W32X86\HDNIS01_de.DLL (4465.5 kb/s) (average 4465.5 kb/s) + putting file Hddm91c1_de.ppd as \W32X86\Hddm91c1_de.ppd (12876.8 kb/s) (average 4638.9 kb/s) + putting file HDNIS01U_de.DLL as \W32X86\HDNIS01U_de.DLL (20249.8 kb/s) (average 5828.3 kb/s) + putting file HDNIS01U_de.HLP as \W32X86\HDNIS01U_de.HLP (9652.8 kb/s) (average 5899.8 kb/s) + putting file Hddm91c1_de.DLL as \W32X86\Hddm91c1_de.DLL (23777.7 kb/s) (average 10400.6 kb/s) + putting file Hddm91c1_de.INI as \W32X86\Hddm91c1_de.INI (98.6 kb/s) (average 10329.0 kb/s) + putting file Hddm91c1KMMin.DLL as \W32X86\Hddm91c1KMMin.DLL (22931.5 kb/s) (average 10501.7 kb/s) + putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat (2462.8 kb/s) (average 10393.0 kb/s) + putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat (4925.3 kb/s) (average 10356.3 kb/s) + putting file Hddm91c1_de.def as \W32X86\Hddm91c1_de.def (417.9 kb/s) (average 10290.1 kb/s) + putting file Hddm91c1_de.hre as \W32X86\Hddm91c1_de.hre (22571.3 kb/s) (average 11338.5 kb/s) + putting file Hddm91c1_de.vnd as \W32X86\Hddm91c1_de.vnd (3384.6 kb/s) (average 10754.3 kb/s) + putting file Hddm91c1_de.hlp as \W32X86\Hddm91c1_de.hlp (18406.8 kb/s) (average 10839.8 kb/s) + putting file Hddm91c1_de_reg.HLP as \W32X86\Hddm91c1_de_reg.HLP (20278.3 kb/s) (average 11386.3 kb/s) + putting file HDNIS01Aux.dll as \W32X86\HDNIS01Aux.dll (14994.6 kb/s) (average 11405.2 kb/s) + putting file HDNIS01_de.NTF as \W32X86\HDNIS01_de.NTF (23390.2 kb/s) (average 13170.8 kb/s) + +</screen></para> + +<para> +Phewww -- that was a lot of typing! Most drivers are a lot smaller -- +many only having 3 generic PostScript driver files plus 1 PPD. Note, +that while we did retrieve the files from the "2" subdirectory of the +"W32X86" directory from the Windows box, we <emphasis>don't</emphasis> +put them (for now) in this same subdirectory of the Samba box! This +re-location will automatically be done by the +<command>adddriver</command> command which we will run shortly (and +don't forget to also put the files for the Win95/98/ME architecture +into the <emphasis>WIN40/</emphasis> subdirectory should you need +them). +</para> +</sect3> + +<sect3> +<title>Check if the Driver Files are there (with smbclient)</title> + +<para> +For now we verify that our files are there. This can be done with +<command>smbclient</command> too (but of course you can log in via SSH +also and do this through a standard UNIX shell access too): +</para> + +<para><screen> + + kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -U 'root%xxxx' -c 'cd W32X86; pwd; dir; cd 2; pwd; dir' + added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 + Got a positive name query response from 10.160.51.162 ( 10.160.51.162 ) + Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a] + + Current directory is \\SAMBA-CUPS\print$\W32X86\ + . D 0 Sun May 4 03:56:35 2003 + .. D 0 Thu Apr 10 23:47:40 2003 + 2 D 0 Sun May 4 03:56:18 2003 + HDNIS01Aux.dll A 15356 Sun May 4 03:58:59 2003 + Hddm91c1KMMin.DLL A 46966 Sun May 4 03:58:59 2003 + HDNIS01_de.DLL A 434400 Sun May 4 03:58:59 2003 + HDNIS01_de.NTF A 790404 Sun May 4 03:56:35 2003 + Hddm91c1_de.DLL A 876544 Sun May 4 03:58:59 2003 + Hddm91c1_de.INI A 101 Sun May 4 03:58:59 2003 + Hddm91c1_de.dat A 5044 Sun May 4 03:58:59 2003 + Hddm91c1_de.def A 428 Sun May 4 03:58:59 2003 + Hddm91c1_de.hlp A 37699 Sun May 4 03:58:59 2003 + Hddm91c1_de.hre A 323584 Sun May 4 03:58:59 2003 + Hddm91c1_de.ppd A 26373 Sun May 4 03:58:59 2003 + Hddm91c1_de.vnd A 45056 Sun May 4 03:58:59 2003 + HDNIS01U_de.DLL A 165888 Sun May 4 03:58:59 2003 + HDNIS01U_de.HLP A 19770 Sun May 4 03:58:59 2003 + Hddm91c1_de_reg.HLP A 228417 Sun May 4 03:58:59 2003 + 40976 blocks of size 262144. 709 blocks available + + Current directory is \\SAMBA-CUPS\print$\W32X86\2\ + . D 0 Sun May 4 03:56:18 2003 + .. D 0 Sun May 4 03:56:35 2003 + ADOBEPS5.DLL A 434400 Sat May 3 23:18:45 2003 + laserjet4.ppd A 9639 Thu Apr 24 01:05:32 2003 + ADOBEPSU.DLL A 109568 Sat May 3 23:18:45 2003 + ADOBEPSU.HLP A 18082 Sat May 3 23:18:45 2003 + PDFcreator2.PPD A 15746 Sun Apr 20 22:24:07 2003 + 40976 blocks of size 262144. 709 blocks available + +</screen></para> + +<para> +Notice that there are already driver files present in the +<filename>2</filename> subdir (probably from a previous +installation). Once the files for the new driver are there too, you +are still a few steps away from being able to use them on the +clients. The only thing you could do *now* is to retrieve them from a +client just like you retrieve ordinary files from a file share, by +opening print$ in Windows Explorer. But that wouldn't install them per +Point'n'Print. The reason is: Samba doesn't know yet that these files +are something special, namely <emphasis>printer driver +files</emphasis> and it doesn't know yet to which print queue(s) these +driver files belong. +</para> +</sect3> + +<sect3> +<title>Running <command>rpcclient</command> with +<command>adddriver</command></title> + +<para> +So, next you must tell Samba about the special category of the files +you just uploaded into the <parameter>[print$]</parameter> share. This +is done by the "<command>adddriver</command>" command. It will +prompt Samba to register the driver files into its internal TDB +database files. The following command and its output has been edited, +again, for readability: +</para> + +<para><screen> + + kde-bitshop:~# rpcclient -Uroot%xxxx -c 'adddriver "Windows NT x86" "dm9110:HDNIS01_de.DLL: \ + Hddm91c1_de.ppd:HDNIS01U_de.DLL:HDNIS01U_de.HLP: \ + NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \ + Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \ + Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \ + HDNIS01Aux.dll,HDNIS01_de.NTF, \ + Hddm91c1_de_reg.HLP' SAMBA-CUPS + + cmd = adddriver "Windows NT x86" "dm9110:HDNIS01_de.DLL:Hddm91c1_de.ppd:HDNIS01U_de.DLL: \ + HDNIS01U_de.HLP:NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \ + Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \ + Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \ + HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP" + + Printer Driver dm9110 successfully installed. + +</screen></para> + +<para> +After this step the driver should be recognized by Samba on the print +server. You need to be very carefull when typing the command. Don't +exchange the order of the fields. Some changes would lead to a +<computeroutput>NT_STATUS_UNSUCCESSFUL</computeroutput> error +message. These become obvious. Other changes might install the driver +files successfully, but render the driver unworkable. So take care! +Hints about the syntax of the adddriver command are in the man +page. The CUPS printing chapter of this HOWTO collection provides a +more detailed description, if you should need it. +</para> +</sect3> + +<sect3> +<title>Check how Driver Files have been moved after +<command>adddriver</command> finished</title> + +<para> +One indication for Samba's recognition of the files as driver files is +the <computeroutput>successfully installed</computeroutput> message. +Another one is the fact, that our files have been moved by the +<command>adddriver</command> command into the "<filename>2</filename>" +subdirectory. You can check this again with +<command>smbclient</command>: +</para> + +<para><screen> + + kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -Uroot%xxxx -c 'cd W32X86;dir;pwd;cd 2;dir;pwd' + added interface ip=10.160.51.162 bcast=10.160.51.255 nmask=255.255.252.0 + Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a] + + Current directory is \\SAMBA-CUPS\print$\W32X86\ + . D 0 Sun May 4 04:32:48 2003 + .. D 0 Thu Apr 10 23:47:40 2003 + 2 D 0 Sun May 4 04:32:48 2003 + 40976 blocks of size 262144. 731 blocks available + + Current directory is \\SAMBA-CUPS\print$\W32X86\2\ + . D 0 Sun May 4 04:32:48 2003 + .. D 0 Sun May 4 04:32:48 2003 + DigiMaster.PPD A 148336 Thu Apr 24 01:07:00 2003 + ADOBEPS5.DLL A 434400 Sat May 3 23:18:45 2003 + laserjet4.ppd A 9639 Thu Apr 24 01:05:32 2003 + ADOBEPSU.DLL A 109568 Sat May 3 23:18:45 2003 + ADOBEPSU.HLP A 18082 Sat May 3 23:18:45 2003 + PDFcreator2.PPD A 15746 Sun Apr 20 22:24:07 2003 + HDNIS01Aux.dll A 15356 Sun May 4 04:32:18 2003 + Hddm91c1KMMin.DLL A 46966 Sun May 4 04:32:18 2003 + HDNIS01_de.DLL A 434400 Sun May 4 04:32:18 2003 + HDNIS01_de.NTF A 790404 Sun May 4 04:32:18 2003 + Hddm91c1_de.DLL A 876544 Sun May 4 04:32:18 2003 + Hddm91c1_de.INI A 101 Sun May 4 04:32:18 2003 + Hddm91c1_de.dat A 5044 Sun May 4 04:32:18 2003 + Hddm91c1_de.def A 428 Sun May 4 04:32:18 2003 + Hddm91c1_de.hlp A 37699 Sun May 4 04:32:18 2003 + Hddm91c1_de.hre A 323584 Sun May 4 04:32:18 2003 + Hddm91c1_de.ppd A 26373 Sun May 4 04:32:18 2003 + Hddm91c1_de.vnd A 45056 Sun May 4 04:32:18 2003 + HDNIS01U_de.DLL A 165888 Sun May 4 04:32:18 2003 + HDNIS01U_de.HLP A 19770 Sun May 4 04:32:18 2003 + Hddm91c1_de_reg.HLP A 228417 Sun May 4 04:32:18 2003 + 40976 blocks of size 262144. 731 blocks available + +</screen></para> + +<para> +Another verification is that the timestamp of the printing TDB files +is now updated (and possibly their filesize has increased). +</para> +</sect3> + +<sect3> +<title>Check if the Driver is recognized by Samba</title> + +<para> +Now the driver should be registered with Samba. We can easily verify +this, and will do so in a moment. However, this driver is +<emphasis>not yet</emphasis> associated with a particular +<emphasis>printer</emphasis>. We may check the driver status of the +files by at least three methods: +</para> + +<itemizedlist> +<listitem><para>from any Windows client browse Network Neighbourhood, +finde the Samba host and open the Samba "<emphasis>Printers and +Faxes</emphasis>" folder. Select any printer icon, right-click and +select the printer " <emphasis>Properties</emphasis>". Click on the +"<emphasis>Advanced</emphasis>" tab. Here is a field indicating the +driver for that printer. A drop down menu allows you to change that +driver (be carefull to not do this unwittingly.). You can use this +list to view all drivers know to Samba. Your new one should be amongst +them. (Each type of client will only see his own architecture's +list. If you don't have every driver installed for each platform, the +list will differ if you look at it from Windows95/98/ME or +WindowsNT/2000/XP.)</para></listitem> + +<listitem><para>from a Windows 2000 or XP client (not WinNT) browse +<emphasis>Network Neighbourhood</emphasis>, search for the Samba +server and open the server's <emphasis>Printers</emphasis> folder, +right-click the white background (with no printer highlighted). Select +"<emphasis>Server Properties</emphasis>". On the +"<emphasis>Drivers</emphasis> " tab you will see the new driver listed +now. This view enables you to also inspect the list of files belonging +to that driver<emphasis> (this doesn't work on Windows NT, but only on +Windows 2000 and Windows XP. WinNT doesn't provide the "Drivers" +tab).</emphasis>. An alternative, much quicker method for Windows +2000/XP to start this dialog is by typing into a DOS box (you must of +course adapt the name to your Samba server instead of SAMBA-CUPS): +</para> + +<para><screen> + rundll32 printui.dll,PrintUIEntry /s /t2 /n\\SAMBA-CUPS +</screen></para> +</listitem> + +<listitem><para>from a UNIX prompt run this command (or a variant +thereof), where "SAMBA-CUPS" is the name of the Samba host and "xxxx" +represents the actual Samba password assigned to root: +</para> + +<para><screen> + rpcclient -U'root%xxxx' -c 'enumdrivers' SAMBA-CUPS +</screen></para> + +<para> +You will see a listing of all drivers Samba knows about. Your new one +should be amongst them. But it is only listed under the [Windows NT +x86] heading, not under [Windows 4.0], since we didn't install that +part. Or did *you*? -- You will see a listing of all drivers Samba +knows about. Your new one should be amongst them. In our example it is +named <emphasis>dm9110</emphasis>. Note that the 3rd column shows the +other installed drivers twice, for each supported architecture one +time. Our new driver only shows up for "Windows NT 4.0 or 2000". To +have it present for "Windows 95, 98 and ME" you'll have to repeat the +whole procedure with the WIN40 architecture and subdirectory. +</para></listitem> +</itemizedlist> +</sect3> + +<sect3> +<title>A sidenote: you are not bound to specific driver names</title> <para> -One way to debug printing problems is to start by replacing these -command with shell scripts that record the arguments and the contents -of the print file. A simple example of this kind of things might -be: +You can name the driver as you like. If you repeat the +<command>adddriver</command> step, with the same files as before, but +with a different driver name, it will work the same: </para> -<para><programlisting> - print command = /tmp/saveprint %p %s +<para><screen> - #!/bin/saveprint - # we make sure that we are the right user - /usr/bin/id -p >/tmp/tmp.print - # we run the command and save the error messages - # replace the command with the one appropriate for your system - /usr/bin/lpr -r -P$1 $2 2>>&/tmp/tmp.print -</programlisting></para> + kde-bitshop:~# rpcclient -Uroot%xxxx \ + -c 'adddriver "Windows NT x86" \ + "myphantasydrivername:HDNIS01_de.DLL: \ + Hddm91c1_de.ppd:HDNIS01U_de.DLL:HDNIS01U_de.HLP: \ + NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \ + Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \ + Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \ + HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP' SAMBA-CUPS + + cmd = adddriver "Windows NT x86" + "myphantasydrivername:HDNIS01_de.DLL:Hddm91c1_de.ppd:HDNIS01U_de.DLL:\ + HDNIS01U_de.HLP:NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \ + Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \ + Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \ + HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP" + + Printer Driver myphantasydrivername successfully installed. + +</screen></para> + +<para> +You will also be able to bind that driver to any print queue (however, +you are responsible yourself that you associate drivers to queues +which make sense to the target printer). Note, that you can't run the +<command>rpcclient</command> <command>adddriver</command> command +repeatedly. Each run "consumes" the files you had put into the +<parameter>[print$]</parameter> share by moving them into the +respective subdirectories. So you <emphasis>must</emphasis> precede an +"<command>smbclient ... put"</command> command before each +"<command>rpcclient ... addriver</command>" command. +</para> +</sect3> + +<sect3> +<title>La Grande Finale: Running <command>rpcclient</command> with +<command>setdriver</command></title> <para> -Then you print a file and try removing it. You may find that the -print queue needs to be stopped in order to see the queue status -and remove the job: +Samba still needs to know <emphasis>which</emphasis> printer's driver +this is. It needs to create a mapping of the driver to a printer, and +store this info in its "memory", the TDB files. The <command>rpcclient +setdriver</command> command achieves exactly this: </para> -<para><programlisting> +<para><screen> + kde-bitshop:~# rpcclient -U'root%xxxx' -c 'setdriver dm9110 myphantasydrivername' SAMBA-CUPS + cmd = setdriver dm9110 myphantasydrivername + Successfully set dm9110 to driver myphantasydrivername. +</screen></para> + +<para> +Ahhhhh -- no, I didn't want to do that. Repeat, this time with the +name I intended: +</para> -h4: {42} % echo hi >/tmp/hi -h4: {43} % smbclient //localhost/lw4 -added interface ip=10.0.0.4 bcast=10.0.0.255 nmask=255.255.255.0 -Password: -Domain=[ASTART] OS=[Unix] Server=[Samba 2.0.7] -smb: \> print /tmp/hi -putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s) -smb: \> queue -1049 3 hi-17534 -smb: \> cancel 1049 -Error cancelling job 1049 : code 0 -smb: \> cancel 1049 -Job 1049 cancelled -smb: \> queue -smb: \> exit -</programlisting></para> +<para><screen> + kde-bitshop:~# rpcclient -U'root%xxxx' -c 'setdriver dm9110 dm9110' SAMBA-CUPS + cmd = setdriver dm9110 dm9110 + Succesfully set dm9110 to driver dm9110. +</screen></para> <para> -The 'code 0' indicates that the job was removed. The comment -by the smbclient is a bit misleading on this. -You can observe the command output and then and look at the -/tmp/tmp.print file to see what the results are. You can quickly -find out if the problem is with your printing system. Often people -have problems with their /etc/printcap file or permissions on -various print queues. +The syntax of the command is <command>rpcclient -U'root%sambapassword' +-c 'setdriver "printername" "drivername' SAMBA-Hostname</command> . -- +Now we have done *most* of the work. But not yet all.... </para> + +<note><para> +the "setdriver" command will only succeed if the printer is known to +Samba already. A bug in 2.2.x prevented Samba from recognizing freshly +installed printers. You had to restart Samba, or at least send a HUP +signal to all running smbd processes to work around this: +<command>kill -HUP `pidof smbd`</command>. </para></note> +</sect3> </sect2> +</sect1> + +<sect1> +<title>"The Proof of the Pudding lies in the Eating" (Client Driver Insta +Procedure)</title> + +<para> +A famous philosopher said once: <quote>The Proof of the Pudding lies +in the Eating</quote>. The proof for our setup lies in the printing. +So let's install the printer driver onto the client PCs. This is not +as straightforward as it may seem. Read on. +</para> <sect2> -<title>What printers do I have?</title> +<title>The first Client Driver Installation</title> <para> -You can use the 'testprns' program to check to see if the printer -name you are using is recognized by Samba. For example, you can -use: +Especially important is the installation onto the first client PC (for +each architectural platform separately). Once this is done correctly, +all further clients are easy to setup and shouldn't need further +attention. What follows is a description for the recommended first +procedure. You work now from a client workstation. First you should +guarantee that your connection is not unwittingly mapped to +<parameter>bad user</parameter> "nobody". In a DOS box type: </para> -<para><programlisting> - testprns printer /etc/printcap -</programlisting></para> +<para><screen> +net use \\SAMBA-SERVER\print$ /user:root +</screen></para> <para> -Samba can get its printcap information from a file or from a program. -You can try the following to see the format of the extracted -information: +Replace root, if needed, by another valid 'printer admin' user as +given in the <filename>smb.conf</filename> definition. Should you +already be connected as a different user, you'll get an error +message. There is no easy way to get rid of that connection, because +Windows doesn't seem to know a concept of "logging off" from a share +connection (don't confuse this with logging off from the local +workstation; that is a different matter). You can try to close +<emphasis>all</emphasis> Windows file explorer and Internet Explorer +windows. As a last resort, you may have to reboot. Make sure there is +no automatic re-connection set up. It may be easier to go to a +different workstation and try from there. After you have made sure you +are connected as a printer admin user (you can check this with the +<command>smbstatus</command> command on Samba) do this from the +Windows workstation: </para> -<para><programlisting> - testprns -a printer /etc/printcap +<itemizedlist> +<listitem><para>Open <emphasis>Network +Neighbourhood</emphasis></para></listitem> + +<listitem><para>Browse to Samba server</para></listitem> + +<listitem><para>Open its <emphasis>Printers and +Faxes</emphasis> folder</para></listitem> + +<listitem><para>Highlight and right-click the printer</para></listitem> - testprns -a printer '|/bin/cat printcap' -</programlisting></para> +<listitem><para>Select <emphasis>Connect...</emphasis> (for WinNT4/2K +it is possibly <emphasis>Install...</emphasis>)</para></listitem> +</itemizedlist> +<para> +A new printer (named <replaceable>printername</replaceable> on +samba-server) should now have appeared in your +<emphasis>local</emphasis> Printer folder (check <emphasis>Start -- +Settings -- Control Panel -- Printers and Faxes</emphasis>). +</para> + +<para> +Most likely you are now tempted to try and print a test page. After +all, you now can open the printer properties and on the "General" tab, +there is a button offering to do just that. But chances are that you +get an error message saying <computeroutput>Unable to print Test +Page</computeroutput>. The reason might be that there is not yet a +valid Device Mode set for the driver, or that the "Printer Driver +Data" set is still incomplete. +</para> + +<para> +You must now make sure that a valid "Device Mode" is set for the +driver. Don't fear -- we will explain now what that means. +</para> </sect2> <sect2> -<title>Setting up printcap and print servers</title> +<title>IMPORTANT! Setting Device Modes on new Printers</title> <para> -You may need to set up some printcaps for your Samba system to use. -It is strongly recommended that you use the facilities provided by -the print spooler to set up queues and printcap information. +In order for a printer to be truly usable by a Windows NT/2K/XP +client, it must possess: </para> +<itemizedlist> +<listitem><para>a valid <emphasis>Device Mode</emphasis> generated by +the driver for the printer (defining things like paper size, +orientation and duplex settings), and</para></listitem> + +<listitem><para>a complete set of +<emphasis>Printer Driver Data</emphasis> generated by the +driver.</para></listitem> +</itemizedlist> + <para> -Samba requires either a printcap or program to deliver printcap -information. This printcap information has the format: +If either one of these is incomplete, the clients can produce less +than optimal output at best. In the worst cases, unreadable garbage or +nothing at all comes from the printer or they produce a harvest of +error messages when attempting to print. Samba stores the named values +and all printing related info in its internal TDB database files +<filename>(ntprinters.tdb</filename>, +<filename>ntdrivers.tdb</filename>, <filename>printing.tdb</filename> +and <filename>ntforms.tdb</filename>). </para> -<para><programlisting> - name|alias1|alias2...:option=value:... -</programlisting></para> +<para> +What do these two words stand for? Basically, the Device Mode and the +set of Printer Driver Data is a collection of settings for all print +queue properties, initialized in a sensible way. Device Modes and +Printer Driver Data should initially be set on the print server (that is +here: the Samba host) to healthy values so that the clients can start +to use them immediately. How do we set these initial healthy values? +This can be achieved by accessing the drivers remotely from an NT (or +2k/XP) client, as is discussed in the next paragraphs. +</para> <para> -For almost all printing systems, the printer 'name' must be composed -only of alphanumeric or underscore '_' characters. Some systems also -allow hyphens ('-') as well. An alias is an alternative name for the -printer, and an alias with a space in it is used as a 'comment' -about the printer. The printcap format optionally uses a \ at the end of lines -to extend the printcap to multiple lines. +Be aware, that a valid Device Mode can only be initiated by a +"<emphasis>printer admin</emphasis>", or root (the reason should be +obvious). Device Modes can only correctly be set by executing the +printer driver program itself. Since Samba can not execute this Win32 +platform driver code, it sets this field initially to NULL (which is +not a valid setting for clients to use). Fortunately, most drivers +generate themselves the Printer Driver Data that is needed, when they +are uploaded to the <parameter>[print$]</parameter> share with the +help of the APW or rpcclient. </para> <para> -Here are some examples of printcap files: +The generation and setting of a first valid Device Mode however +requires some "tickling" from a client, to set it on the Samba +server. The easiest means of doing so is to simply change the page +orientation on the server's printer. This "executes" enough of the +printer driver program on the client for the desired effect to happen, +and feeds back the new Device Mode to our Samba server. You can use the +native Windows NT/2K/XP printer properties page from a Window client +for this: </para> +<itemizedlist> +<listitem><para>Browse the "Network Neighbourhood"</para></listitem> + +<listitem><para>Find the Samba server</para></listitem> + +<listitem><para>Open the Samba server's <emphasis>Printers and +Faxes</emphasis> folder</para></listitem> + +<listitem><para>Highlight the shared printer in question</para></listitem> + +<listitem><para>Right-click the printer (you may already be here, if you +followed the last section's description)</para></listitem> + +<listitem><para>At the bottom of the context menu select +"Properties...." (if the menu still offers the "Connect..." entry +further above, you need to click that one first to achieve the driver +installation as shown in the last section)</para></listitem> + +<listitem><para>Go to the "Advanced" tab; click on "Printing +Defaults..."</para></listitem> + +<listitem><para>Change the "Portrait" page setting to "Landscape" (and +back)</para></listitem> + +<listitem><para>(Oh, and make sure to <emphasis>apply</emphasis> +changes between swapping the page orientation to cause the change to +actually take effect...).</para></listitem> + +<listitem><para>While you're at it, you may optionally also want to +set the desired printing defaults here, which then apply to all future +client driver installations on the remaining from now +on.</para></listitem> +</itemizedlist> + <para> -<orderedlist> -<listitem><para> -pr just printer name -</para></listitem> -<listitem><para> -pr|alias printer name and alias -</para></listitem> -<listitem><para> -pr|My Printer printer name, alias used as comment -</para></listitem> -<listitem><para> -pr:sh:\ Same as pr:sh:cm= testing - :cm= \ - testing -</para></listitem> -<listitem><para> -pr:sh Same as pr:sh:cm= testing - :cm= testing -</para></listitem> -</orderedlist> +This procedure has executed the printer driver program on the client +platform and fed back the correct Device Mode to Samba, which now +stored it in its TDB files. Once the driver is installed on the +client, you can follow the analogous steps by accessing the +<emphasis>local</emphasis> "Printers" folder too if you are a Samba +printer admin user. From now on printing should work as expected. </para> <para> -Samba reads the printcap information when first started. If you make -changes in the printcap information, then you must do the following: +Samba also includes a service level parameter name <parameter>default +devmode</parameter> for generating a default Device Mode for a +printer. Some drivers will function well with Samba's default set of +properties. Others may crash the client's spooler service. So use this +parameter with caution. It is always better to have the client +generate a valid device mode for the printer and store it on the +server for you. </para> +</sect2> -<orderedlist> +<sect2> +<title>Further Client Driver Install Procedures</title> -<listitem><para> -make sure that the print spooler is aware of these changes. -The LPRng system uses the 'lpc reread' command to do this. -</para></listitem> +<para> +Every further driver may be done by any user, along the lines +described above: Browse network, open printers folder on Samba server, +right-click printer and choose "Connect...". Once this completes +(should be not more than a few seconds, but could also take a minute, +depending on network conditions), you should find the new printer in +your client workstation local <emphasis>Printers and +Faxes</emphasis> folder. +</para> -<listitem><para> -make sure that the spool queues, etc., exist and have the -correct permissions. The LPRng system uses the 'checkpc -f' -command to do this. -</para></listitem> +<para> +You can also open your local "Printers and Faxes" folder by using this +command on Windows 2000 and Windows XP Professional workstations: +</para> -<listitem><para> -You now should send a SIGHUP signal to the smbd server to have -it reread the printcap information. -</para></listitem> +<para><screen> +rundll32 shell32.dll,SHHelpShortcuts_RunDLL PrintersFolder +</screen></para> + +<para> +or this command on Windows NT 4.0 workstations: +</para> + +<para><screen> +rundll32 shell32.dll,Control_RunDLL MAIN.CPL @2 +</screen></para> + +<para> +You can enter the commands either inside a "DOS box" window or in the +"Run command..." field from the "Start" menu. +</para> +</sect2> + +<sect2> +<title>Always make first Client Connection as root or "printer admin"</title> + +<para> +After you installed the driver on the Samba server (in its +<parameter>[print$]</parameter> share, you should always make sure +that your first client installation completes correctly. Make it a habit for +yourself to build that the very first connection from a client as +"printer admin". This is to make sure that: +</para> + +<itemizedlist> + +<listitem><para> a first valid <emphasis>Device Mode</emphasis> is +really initialized (see above for more explanation details), and +that</para></listitem> + +<listitem><para> the default print settings of your printer for all +further client installations are as you want them</para></listitem> +</itemizedlist> + +<para> +Do this by changing the orientation to landscape, click +<emphasis>Apply</emphasis>, and then change it back again. Then modify +the other settings (for example, you don't want the default media size +set to <emphasis>Letter</emphasis>, when you are all using +<emphasis>A4</emphasis>, right? You may want to set the printer for +<emphasis>duplex</emphasis> as the default; etc.). +</para> + +<para> +To connect as root to a Samba printer, try this command from a Windows +2K/XP DOS box command prompt: +</para> + +<para><screen> +runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry /p /t3 /n \\SAMBA-SERVER\printername" +</screen></para> + +<para> +You will be prompted for root's Samba-password; type it, wait a few +seconds, click on "<emphasis>Printing Defaults...</emphasis>" and +proceed to set the job options as should be used as defaults by all +clients. Alternatively, instead of root you can name one other member +of the<emphasis>printer admins</emphasis> from the +<filename>smb.conf</filename> setting. +</para> + +<para> +Now all the other users downloading and installing the driver +the same way (called <emphasis>Point'n'Print</emphasis>) will +have the same defaults set for them. If you miss this step you'll +get a lot of helpdesk calls from your users. But maybe you like to +talk to people.... ;-) +</para> +</sect2> +</sect1> + +<sect1> +<title>Other Gotchas</title> + +<para> +Your driver is installed. It is ready for +<emphasis>Point'n'Print</emphasis> installation by the clients +now. You <emphasis>may</emphasis> have tried to download and use it +onto your first client machine now. But wait... let's make you +acquainted first with a few tips and tricks you may find useful. For +example, suppose you didn't manage to "set the defaults" on the +printer, as advised in the preceeding paragraphs? And your users +complain about various issues (such as <quote>We need to set the paper +size for each job from Letter to A4 and it won't store it!</quote>) +</para> + +<sect2> +<title>Setting Default Print Options for the Client Drivers</title> + +<para> +The last sentence might be viewed with mixed feelings by some users and +admins. They have struggled for hours and hours and couldn't arrive at +a point were their settings seemed to be saved. It is not their +fault. The confusing thing is this: in the multi-tabbed dialog that pops +up when you right-click the printer name and select +<emphasis>Properties...</emphasis>, you can arrive at two identically +looking dialogs, each claiming that they help you to set printer options, +in three different ways. Here is the definite answer to the "Samba +Default Driver Setting FAQ": +</para> + +<formalpara><title><quote>I can't set and save default print options +for all users on Win2K/XP! Why not?</quote></title> + +<para> +How are you doing it? I bet the wrong way.... (it is not very +easy to find out, though). There are 3 different ways to bring you to +a dialog that <emphasis>seems</emphasis> to set everything. All three +dialogs <emphasis>look</emphasis> the same. Only one of them +<emphasis>does</emphasis> what you intend. +<emphasis>Important:</emphasis> you need to be Administrator or Print +Administrator to do this for all users. Here is how I reproduce it in +on XP Professional: + +<orderedlist numeration="upperalpha"> + +<listitem><para>The first "wrong" way: + +<orderedlist numeration="arabic"> +<listitem><para>Open the <emphasis>Printers</emphasis> +folder.</para></listitem> + +<listitem><para>Right-click on the printer +(<emphasis>remoteprinter on cupshost</emphasis>) and +select in context menu <emphasis>Printing +Preferences...</emphasis></para></listitem> + +<listitem><para>Look at this dialog closely and remember what it looks +like.</para></listitem> </orderedlist> +</para> +</listitem> + +<listitem><para>The second "wrong" way: + +<orderedlist numeration="arabic"> +<listitem><para>Open the "<emphasis>Printers</emphasis>" +folder.</para></listitem> + +<listitem><para>Right-click on the printer (<emphasis>remoteprinter on +cupshost</emphasis>) and select in the context menu +<emphasis>Properties</emphasis></para></listitem> + +<listitem><para>Click on the <emphasis>General</emphasis> +tab</para></listitem> + +<listitem><para>Click on the button <emphasis>Printing +Preferences...</emphasis></para></listitem> + +<listitem><para>A new dialog opens. Keep this dialog open and go back +to the parent dialog.</para></listitem> +</orderedlist> +</para> +</listitem> + +<listitem><para>The third, the "correct" way: (should you do +this from the beginning, just carry out steps 1. and 2. from second +"way" above) + +<orderedlist numeration="arabic"> +<listitem><para>Click on the <emphasis>Advanced</emphasis> +tab. (Hmmm... if everything is "Grayed Out", then you are not logged +in as a user with enough privileges).</para></listitem> + +<listitem><para>Click on the "<emphasis>Printing +Defaults...</emphasis>" button.</para></listitem> + +<listitem><para>On any of the two new tabs, click on the +<emphasis>Advanced...</emphasis> +button.</para></listitem> + +<listitem><para>A new dialog opens. Compare this one to the other, +identical looking one from "B.5" or A.3".</para></listitem> +</orderedlist> +</para> +</listitem> +</orderedlist> + +Do you see any difference in the two settings dialogs? I don't +either. However, only the last one, which you arrived at with steps +C.1.-6. will permanently save any settings which will then become the +defaults for new users. If you want all clients to have the same +defaults, you need to conduct these steps as administrator +(<emphasis>printer admin</emphasis> in <filename>smb.conf</filename>) +<emphasis>before</emphasis> a client downloads the driver (the clients +can later set their own <emphasis>per-user defaults</emphasis> by +following the procedures<emphasis>A.</emphasis> +or<emphasis>B.</emphasis> above...). (This is new: Windows 2000 and +Windows XP allow <emphasis>per-user</emphasis> default settings and +the ones the administrator gives them, before they set up their own). +The "parents" of the identically looking dialogs have a slight +difference in their window names: one is called +<computeroutput>Default Print Values for Printer Foo on Server +Bar"</computeroutput> (which is the one you need) and the other is +called "<computeroutput>Print Settings for Printer Foo on Server +Bar</computeroutput>". The last one is the one you arrive at when you +right-click on the printer and select <emphasis>Print +Settings...</emphasis>. This is the one what you were +taught to use back in the days of Windows NT! So it is only natural to +try the same way with Win2k or WinXP. You wouldn't dream +that there is now a different "clicking path" to arrive at an +identically looking, but functionally different dialog to set defaults +for all users! +</para></formalpara> + +<tip><para>Try (on Win2000 and WinXP) to run this command (as a user +with the right privileges): +</para> + +<para><screen> +rundll32 printui.dll,PrintUIEntry /p /t3 /n\\SAMBA-SERVER\printersharename +</screen></para> + +<para> +to see the tab with the <emphasis>Printing Defaults...</emphasis> +button (the one you need). Also run this command: +</para> + +<para><screen> +rundll32 printui.dll,PrintUIEntry /p /t0 /n\\SAMBA-SERVER\printersharename +</screen></para> + +<para> +to see the tab with the <emphasis>Printing Preferences...</emphasis> +button (the one which doesn't set system-wide defaults). You can +start the commands from inside a DOS box" or from the <emphasis>Start +-- Run...</emphasis> menu. +</para> +</tip> + +</sect2> + +<sect2> +<title>Supporting large Numbers of Printers</title> + +<para> +One issue that has arisen during the recent development phase of Samba +is the need to support driver downloads for 100's of printers. Using +Windows NT APW here is somewhat awkward (to say the least). If you +don't want to acquire RSS pains from such the printer installation +clicking orgy alone, you need to think about a non-interactive script. +</para> + +<para> +If more than one printer is using the same driver, the +<command>rpcclient setdriver</command> command can be used to set the +driver associated with an installed queue. If the driver is uploaded +to <parameter>[print$]</parameter> once and registered with the +printing TDBs, it can be used by multiple print queues. In this case +you just need to repeat the <command>setprinter</command> subcommand +of <command>rpcclient</command> for every queue (without the need to +conduct the <command>adddriver</command> again and again). The +following is an example of how this could be accomplished: +</para> + +<para><screen> + + ---------------------------------------------------------------------------------- + $ rpcclient SAMBA-CUPS -U root%secret -c 'enumdrivers' + cmd = enumdrivers + + [Windows NT x86] + Printer Driver Info 1: + Driver Name: [infotec IS 2075 PCL 6] + + Printer Driver Info 1: + Driver Name: [DANKA InfoStream] + + Printer Driver Info 1: + Driver Name: [Heidelberg Digimaster 9110 (PS)] + + Printer Driver Info 1: + Driver Name: [dm9110] + + Printer Driver Info 1: + Driver Name: [myphantasydrivername] + + [....] + ---------------------------------------------------------------------------------- + +---------------------------------------------------------------------------------- + $ rpcclient SAMBA-CUPS -U root%secret -c 'enumprinters' + cmd = enumprinters + flags:[0x800000] + name:[\\SAMBA-CUPS\dm9110] + description:[\\SAMBA-CUPS\dm9110,,110ppm HiVolume DANKA Stuttgart] + comment:[110 ppm HiVolume DANKA Stuttgart] + [....] + ---------------------------------------------------------------------------------- + +---------------------------------------------------------------------------------- + $ rpcclient SaMbA-cUpS -U root%secret -c 'setdriver dm9110 "Heidelberg Digimaster 9110 (PS)"' + cmd = setdriver dm9110 Heidelberg Digimaster 9110 (PPD) + Successfully set dm9110 to driver Heidelberg Digimaster 9110 (PS). + ---------------------------------------------------------------------------------- + +---------------------------------------------------------------------------------- + $ rpcclient samba-cups -U root%secret -c 'enumprinters' + cmd = enumprinters + flags:[0x800000] + name:[\\SAMBA-CUPS\dm9110] + description:[\\SAMBA-CUPS\dm9110,Heidelberg Digimaster 9110 (PS),110ppm HiVolume DANKA Stuttgart] + comment:[110ppm HiVolume DANKA Stuttgart] + [....] + ---------------------------------------------------------------------------------- + +---------------------------------------------------------------------------------- + $ rpcclient SaMbA-cUpS -U root%secret -c 'setdriver dm9110 myphantasydrivername' + cmd = setdriver dm9110 myphantasydrivername + Successfully set dm9110 to myphantasydrivername. + ---------------------------------------------------------------------------------- + +---------------------------------------------------------------------------------- + $ rpcclient samba-cups -U root%secret -c 'enumprinters' + cmd = enumprinters + flags:[0x800000] + name:[\\SAMBA-CUPS\dm9110] + description:[\\SAMBA-CUPS\dm9110,myphantasydrivername,110ppm HiVolume DANKA Stuttgart] + comment:[110ppm HiVolume DANKA Stuttgart] + [....] + ---------------------------------------------------------------------------------- + +</screen></para> +<para> +It may be not easy to recognize: but the first call to +<command>enumprinters</command> showed the "dm9110" printer with an +empty string where the driver should have been listed (between the 2 +commas in the "description" field). After the +<command>setdriver</command> command succeeded, all is well. (The +CUPS Printing chapter has more info about the installation of printer +drivers with the help of <command>rpccclient</command>). +</para> </sect2> <sect2> -<title>Job sent, no output</title> +<title>Adding new Printers with the Windows NT APW</title> <para> -This is the most frustrating part of printing. You may have sent the -job, verified that the job was forwarded, set up a wrapper around -the command to send the file, but there was no output from the printer. +By default, Samba exhibits all printer shares defined in +<emphasis><filename>smb.conf</filename></emphasis> in the +<emphasis>Printers...</emphasis> folder. Also located in this folder +is the Windows NT Add Printer Wizard icon. The APW will be shown only +if: +</para> + +<itemizedlist> +<listitem><para>...the connected user is able to successfully execute +an <command>OpenPrinterEx(\\server)</command> with administrative +privileges (i.e. root or <emphasis>printer admin</emphasis>). </para> +<tip><para> Try this from a Windows 2K/XP DOS box command prompt: +</para> + +<para><screen> +runas /netonly /user:root rundll32 printui.dll,PrintUIEntry /p /t0 /n \\SAMBA-SERVER\printersharename +</screen></para> + +<para> +and click on <emphasis>Printing Preferences...</emphasis> +</para></tip></listitem> + +<listitem><para>...<filename>smb.conf</filename> contains the setting +<emphasis>show add printer wizard = yes</emphasis> (the +default).</para></listitem> +</itemizedlist> + <para> -First, check to make sure that the job REALLY is getting to the -right print queue. If you are using a BSD or LPRng print spooler, -you can temporarily stop the printing of jobs. Jobs can still be -submitted, but they will not be printed. Use: +The APW can do various things: </para> -<para><programlisting> - lpc -Pprinter stop -</programlisting></para> +<itemizedlist> +<listitem><para>upload a new driver to the Samba +<parameter>[print$]</parameter> share;</para></listitem> + +<listitem><para>associate an uploaded driver with an existing (but +still "driverless") print queue;</para></listitem> + +<listitem><para>exchange the currently used driver for an existing +print queue with one that has been uploaded before;</para></listitem> + +<listitem><para>add an entirely new printer to the Samba host (only in +conjunction with a working <parameter>add printer command</parameter>; +a corresponding <parameter>delete printer command</parameter> for +removing entries from the <emphasis>Printers...</emphasis> folder +may be provided too)</para></listitem> +</itemizedlist> <para> -Now submit a print job and then use 'lpq -Pprinter' to see if the -job is in the print queue. If it is not in the print queue then -you will have to find out why it is not being accepted for printing. +The last one (add a new printer) requires more effort than the +previous ones. In order to use the APW to successfully add a printer +to a Samba server, the <parameter>add printer command</parameter> must +have a defined value. The program hook must successfully add the +printer to the Unix print system (i.e. to +<filename>/etc/printcap</filename>, +<filename>/etc/cups/printers.conf</filename> or other appropriate +files) and to <filename>smb.conf</filename> if necessary. </para> <para> -Next, you may want to check to see what the format of the job really -was. With the assistance of the system administrator you can view -the submitted jobs files. You may be surprised to find that these -are not in what you would expect to call a printable format. -You can use the UNIX 'file' utitily to determine what the job -format actually is: +When using the APW from a client, if the named printer share does not +exist, smbd will execute the <parameter>add printer +command</parameter> and reparse to the <filename>smb.conf</filename> +to attempt to locate the new printer share. If the share is still not +defined, an error of <computeroutput>Access Denied</computeroutput> is +returned to the client. Note that the <parameter>add printer +command</parameter> is executed under the context of the connected +user, not necessarily a root account. A <parameter>map to guest = bad +user</parameter> may have connected you unwittingly under the wrong +privilege; you should check it by using the +<command>smbstatus</command> command. </para> +</sect2> -<para><programlisting> - cd /var/spool/lpd/printer # spool directory of print jobs - ls # find job files - file dfA001myhost -</programlisting></para> +<sect2> +<title>Weird Error Message <errorname>Cannot connect under a +different Name</errorname></title> <para> -You should make sure that your printer supports this format OR that -your system administrator has installed a 'print filter' that will -convert the file to a format appropriate for your printer. +Once you are connected with the wrong credentials, there is no means +to reverse the situation other than to close all Explorer windows, and +perhaps reboot. </para> +<itemizedlist> +<listitem><para>The <command>net use \\SAMBA-SERVER\sharename +/user:root</command> gives you an error message: <computeroutput>Multiple +connections to a server or a shared resource by the same user +utilizing the several user names are not allowed. Disconnect all +previous connections to the server, resp. the shared resource, and try +again.</computeroutput></para></listitem> + +<listitem><para>Every attempt to "connect a network drive" to +<filename>\\SAMBASERVER\\print$</filename> to z: is countered by the +pertinacious message. <computeroutput>This network folder is currently +connected under different credentials (username and password). +Disconnect first any existing connection to this network share in +order to connect again under a different username and +password</computeroutput>.</para></listitem> +</itemizedlist> + +<para> +So you close all connections. You try again. You get the same +message. You check from the Samba side, using +<command>smbstatus</command>. Yes, there are some more +connections. You kill them all. The client still gives you the same +error message. You watch the smbd.log file on a very high debug level +and try re-connect. Same error message, but not a single line in the +log. You start to wonder if there was a connection attempt at all. You +run ethereal and tcpdump while you try to connect. Result: not a +single byte goes on the wire. Windows still gives the error +message. You close all Explorer Windows and start it again. You try to +connect - and this times it works! Windows seems to cache connection +info somewhere and doesn't keep it up to date (if you are unlucky you +might need to reboot to get rid of the error message). +</para> </sect2> <sect2> -<title>Job sent, strange output</title> +<title>Be careful when assembling Driver Files</title> <para> -Once you have the job printing, you can then start worrying about -making it print nicely. +You need to be very careful when you take notes about the files and +belonging to a particular driver. Don't confuse the files for driver +version "0" (for Win95/98/ME, going into +<filename>[print$]/WIN/0/</filename>), driver version "2" (Kernel Mode +driver for WinNT, going into <filename>[print$]/W32X86/2/</filename> +<emphasis>may</emphasis> be used on Win2K/XP too), and driver version +"3" (non-Kernel Mode driver going into +<filename>[print$]/W32X86/3/</filename> <emphasis>can not</emphasis> +be used on WinNT). Very often these different driver versions contain +files carrying the same name; but still the files are very different! +Also, if you look at them from the Windows Explorer (they reside in +"<filename>%WINDOWS%\system32\spool\drivers\W32X86\</filename>") you +will probably see names in capital letters, while an "enumdrivers" +command from Samba would show mixed or lower case letters. So it is +easy to confuse them. If you install them manually using +<command>rpcclient</command> and subcommands, you may even succeed +without an error message. Only later, when you try install on a +client, you will encounter error messages like <computeroutput>This +server has no appropriate driver for the printer</computeroutput>. </para> <para> -The most common problem is extra pages of output: banner pages -OR blank pages at the end. +Here is an example. You are invited to look very closely at the +various files, compare their names and their spelling, and discover +the differences in the composition of the version-2 and -3 sets +Note: the version-0 set contained 40 (!) +<parameter>Dependentfiles</parameter>, so I left it out for space +reasons: </para> +<para><screen> + + kde4@kde-bitshop:# rpcclient -U 'Administrator%xxxx' -c 'enumdrivers 3' 10.160.50.8 + + Printer Driver Info 3: + Version: [3] + Driver Name: [Canon iR8500 PS3] + Architecture: [Windows NT x86] + Driver Path: [\\10.160.50.8\print$\W32X86\3\cns3g.dll] + Datafile: [\\10.160.50.8\print$\W32X86\3\iR8500sg.xpd] + Configfile: [\\10.160.50.8\print$\W32X86\3\cns3gui.dll] + Helpfile: [\\10.160.50.8\print$\W32X86\3\cns3g.hlp] + + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aucplmNT.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\ucs32p.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\tnl32.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aussdrv.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cnspdc.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aussapi.dat] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cns3407.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\CnS3G.cnt] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\NBAPI.DLL] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\NBIPC.DLL] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcview.exe] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcdspl.exe] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcedit.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcqm.exe] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcspl.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cfine32.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcr407.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\Cpcqm407.hlp] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcqm407.cnt] + Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cns3ggr.dll] + + Monitorname: [] + Defaultdatatype: [] + + Printer Driver Info 3: + Version: [2] + Driver Name: [Canon iR5000-6000 PS3] + Architecture: [Windows NT x86] + Driver Path: [\\10.160.50.8\print$\W32X86\2\cns3g.dll] + Datafile: [\\10.160.50.8\print$\W32X86\2\IR5000sg.xpd] + Configfile: [\\10.160.50.8\print$\W32X86\2\cns3gui.dll] + Helpfile: [\\10.160.50.8\print$\W32X86\2\cns3g.hlp] + + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\AUCPLMNT.DLL] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\aussdrv.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cnspdc.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\aussapi.dat] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cns3407.dll] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\CnS3G.cnt] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\NBAPI.DLL] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\NBIPC.DLL] + Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cns3gum.dll] + + Monitorname: [CPCA Language Monitor2] + Defaultdatatype: [] + +</screen></para> + <para> -If you are getting banner pages, check and make sure that the -printcap option or printer option is configured for no banners. -If you have a printcap, this is the :sh (suppress header or banner -page) option. You should have the following in your printer. +If we write the "version 2" files and the "version 3" files +into different text files and compare the result, we see this +picture: </para> -<para><programlisting> - printer: ... :sh -</programlisting></para> +<para><screen> +<![CDATA[ + kde4@kde-bitshop:# sdiff 2-files 3-files + + cns3g.dll cns3g.dll + iR8500sg.xpd iR8500sg.xpd + cns3gui.dll cns3gui.dll + cns3g.hlp cns3g.hlp + AUCPLMNT.DLL | aucplmNT.dll + > ucs32p.dll + > tnl32.dll + aussdrv.dll aussdrv.dll + cnspdc.dll cnspdc.dll + aussapi.dat aussapi.dat + cns3407.dll cns3407.dll + CnS3G.cnt CnS3G.cnt + NBAPI.DLL NBAPI.DLL + NBIPC.DLL NBIPC.DLL + cns3gum.dll | cpcview.exe + > cpcdspl.exe + > cpcqm.exe + > cpcspl.dll + > cfine32.dll + > cpcr407.dll + > Cpcqm407.hlp + > cpcqm407.cnt + > cns3ggr.dll +]]> + + +</screen></para> <para> -If you have this option and are still getting banner pages, there -is a strong chance that your printer is generating them for you -automatically. You should make sure that banner printing is disabled -for the printer. This usually requires using the printer setup software -or procedures supplied by the printer manufacturer. +Don't be fooled though! Driver files for each version with identical +names may be different in their content, as you can see from this size +comparison: </para> +<para><screen> + + kde4@kde-bitshop:# for i in cns3g.hlp cns3gui.dll cns3g.dll; do \ + smbclient //10.160.50.8/print\$ -U 'Administrator%xxxx' \ + -c "cd W32X86/3; dir $i; cd .. ; cd 2; dir $i"; \ + done + + CNS3G.HLP A 122981 Thu May 30 02:31:00 2002 + CNS3G.HLP A 99948 Thu May 30 02:31:00 2002 + + CNS3GUI.DLL A 1805824 Thu May 30 02:31:00 2002 + CNS3GUI.DLL A 1785344 Thu May 30 02:31:00 2002 + + CNS3G.DLL A 1145088 Thu May 30 02:31:00 2002 + CNS3G.DLL A 15872 Thu May 30 02:31:00 2002 + +</screen></para> + <para> -If you get an extra page of output, this could be due to problems -with your job format, or if you are generating PostScript jobs, -incorrect setting on your printer driver on the MicroSoft client. -For example, under Win95 there is a option: +In my example were even more differences than shown here. Conclusion: +you must be very careful to select the correct driver files for each +driver version. Don't rely on the names alone. Don't interchange files +belonging to different driver versions. </para> +</sect2> + +<sect2> +<title>Samba and Printer Ports</title> -<para><programlisting> - Printers|Printer Name|(Right Click)Properties|Postscript|Advanced| -</programlisting></para> +<para> +Windows NT/2000 print servers associate a port with each +printer. These normally take the form of <filename>LPT1:</filename>, +<filename>COM1:</filename>, <filename>FILE:</filename>, etc. Samba +must also support the concept of ports associated with a printer. By +default, only one printer port, named "Samba Printer Port", exists on +a system. Samba does not really need such a "port" in order to print; +it rather is a requirement of Windows clients. They insist on being +told about an available port when they request this info, otherwise +they throw an error message at you. So Samba fakes the port +information to keep the Windows clients happy. +</para> <para> -that allows you to choose if a Ctrl-D is appended to all jobs. -This is a very bad thing to do, as most spooling systems will -automatically add a ^D to the end of the job if it is detected as -PostScript. The multiple ^D may cause an additional page of output. +Note that Samba does not support the concept of "Printer Pooling" +internally either. Printer Pooling assigns a logical printer to +multiple ports as a form of load balancing or fail over. </para> +<para> +If you require that multiple ports be defined for some reason or +another (<quote>My users and my Boss should not know that they are +working with Samba</quote>), <filename>smb.conf</filename> possesses a +<parameter>enumports command</parameter> which can be used to define +an external program that generates a listing of ports on a system. +</para> </sect2> <sect2> -<title>Raw PostScript printed</title> +<title>Avoiding the most common Misconfigurations of the Client Driver</title> <para> -This is a problem that is usually caused by either the print spooling -system putting information at the start of the print job that makes -the printer think the job is a text file, or your printer simply -does not support PostScript. You may need to enable 'Automatic -Format Detection' on your printer. +So - printing works, but there are still problems. Most jobs print +well, some don't print at all. Some jobs have problems with fonts, +which don't look good at all. Some jobs print fast, and some are +dead-slow. We can't cover it all; but we want to encourage you to read +the little paragraph about "Avoiding the wrong PostScript Driver +Settings" in the CUPS Printing part of this document. </para> +</sect2> +</sect1> + +<sect1> +<title>The Imprints Toolset</title> + +<para> +The Imprints tool set provides a UNIX equivalent of the +Windows NT Add Printer Wizard. For complete information, please +refer to the Imprints web site +at<ulink url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink> +as well as the documentation included with the imprints source +distribution. This section will only provide a brief introduction +to the features of Imprints. +</para> + +<formalpara><title>ATTENTION! MAINTAINER REQUIRED</title> + +<para> +Unfortunately, the Imprints toolset is no longer maintained. As of +December, 2000, the project is in need of a new maintainer. The most +important skill to have is decent perl coding and an interest in +MS-RPC based printing using Samba. If you wish to volunteer, please +coordinate your efforts on the samba-technical mailing list. The +toolset is still in usable form; but only for a series of older +printer models, where there are prepared packages to use. Packages for +more up to date print devices are needed if Imprints should have a +future.</para></formalpara> + +<sect2> +<title>What is Imprints?</title> +<para> +Imprints is a collection of tools for supporting these goals: +</para> + +<itemizedlist> +<listitem><para>Providing a central repository information regarding +Windows NT and 95/98 printer driver packages</para></listitem> + +<listitem><para>Providing the tools necessary for creating the +Imprints printer driver packages.</para></listitem> + +<listitem><para>Providing an installation client which will obtain +printer drivers from a central internet (or intranet) Imprints Server +repository and install them on remote Samba and Windows NT4 print +servers.</para></listitem> +</itemizedlist> </sect2> <sect2> -<title>Advanced Printing</title> +<title>Creating Printer Driver Packages</title> + +<para> +The process of creating printer driver packages is beyond the scope of +this document (refer to Imprints.txt also included with the Samba +distribution for more information). In short, an Imprints driver +package is a gzipped tarball containing the driver files, related INF +files, and a control file needed by the installation client. +</para> +</sect2> + +<sect2> +<title>The Imprints Server</title> + +<para> +The Imprints server is really a database server that may be queried +via standard HTTP mechanisms. Each printer entry in the database has +an associated URL for the actual downloading of the package. Each +package is digitally signed via GnuPG which can be used to verify that +package downloaded is actually the one referred in the Imprints +database. It is strongly recommended that this security check +<emphasis>not</emphasis> be disabled. +</para> +</sect2> + +<sect2> +<title>The Installation Client</title> + +<para> +More information regarding the Imprints installation client is +available in the <filename>Imprints-Client-HOWTO.ps</filename> file +included with the imprints source package. +</para> + +<para> +The Imprints installation client comes in two forms. +</para> +<itemizedlist> +<listitem><para>a set of command line Perl scripts</para></listitem> + +<listitem><para>a GTK+ based graphical interface to the command line Perl +scripts</para></listitem> +</itemizedlist> + +<para> +The installation client (in both forms) provides a means of querying +the Imprints database server for a matching list of known printer +model names as well as a means to download and install the drivers on +remote Samba and Windows NT print servers. +</para> + +<para> +The basic installation process is in four steps and perl code is +wrapped around smbclient and rpcclient +</para> + +<para><screen> + + foreach (supported architecture for a given driver) + { + 1. rpcclient: Get the appropriate upload directory + on the remote server + 2. smbclient: Upload the driver files + 3. rpcclient: Issues an AddPrinterDriver() MS-RPC + } + + 4. rpcclient: Issue an AddPrinterEx() MS-RPC to actually + create the printer + +</screen></para> + +<para> +One of the problems encountered when implementing the Imprints tool +set was the name space issues between various supported client +architectures. For example, Windows NT includes a driver named "Apple +LaserWriter II NTX v51.8" and Windows 95 calls its version of this +driver "Apple LaserWriter II NTX" +</para> + +<para> +The problem is how to know what client drivers have been uploaded for +a printer. An astute reader will remember that the Windows NT Printer +Properties dialog only includes space for one printer driver name. A +quick look in the Windows NT 4.0 system registry at +</para> + +<para><screen> + HKLM\System\CurrentControlSet\Control\Print\Environment +</screen></para> <para> -Note that you can do some pretty magic things by using your -imagination with the "print command" option and some shell scripts. -Doing print accounting is easy by passing the %U option to a print -command shell script. You could even make the print command detect -the type of output and its size and send it to an appropriate -printer. +will reveal that Windows NT always uses the NT driver name. This is +ok as Windows NT always requires that at least the Windows NT version +of the printer driver is present. However, Samba does not have the +requirement internally. Therefore, how can you use the NT driver name +if is has not already been installed? </para> +<para> +The way of sidestepping this limitation is to require that all +Imprints printer driver packages include both the Intel Windows NT and +95/98 printer drivers and that NT driver is installed first. +</para> </sect2> +</sect1> + +<sect1> +<title>Add Network Printers at Logon without User Interaction</title> + +<para> +The following MS Knowledge Base article may be of some help if you +need to handle Windows 2000 clients: <emphasis>How to Add Printers +with No User Interaction in Windows 2000.</emphasis> ( <ulink +url="http://support.microsoft.com/default.aspx?scid=kb;en-us;189105">http://support.microsoft.com/default.aspx?scid=kb;en-us;189105</ulink> +). It also applies to Windows XP Professional clients. +</para> + +<para> +The ideas sketched out below are inspired by this article. It +describes a commandline method which can be applied to install +network and local printers and their drivers. This is most useful +if integrated in Logon Scripts. You can see what options are +available by typing in a command prompt ("DOS box") this: +</para> + +<para><screen> + rundll32 printui.dll,PrintUIEntry /? +</screen></para> + +<para> +A window pops up which shows you all of the commandline switches +available. An extensive list of examples is also provided. This is +only for Win 2k/XP. It doesn't work on WinNT. WinNT has probably some +other tools in the respective Resource Kit. Here is a suggestion about +what a client logon script might contain, with a short explanation of +what the lines actually do (it works if 2k/XP Windows clients access +printers via Samba, but works for Windows-based print servers too): +</para> + +<para><screen> + rundll32 printui.dll,PrintUIEntry /dn /n "\\sambacupsserver\infotec2105-IPDS" /q + rundll32 printui.dll,PrintUIEntry /in /n "\\sambacupsserver\infotec2105-PS" + rundll32 printui.dll,PrintUIEntry /y /n "\\sambacupsserver\infotec2105-PS" +</screen></para> + +<para> +Here is a list of the used commandline parameters: +</para> + +<variablelist> +<varlistentry><term>/dn</term> +<listitem><para>deletes a network printer</para></listitem> +</varlistentry> +<varlistentry><term>/q</term> +<listitem><para>quiet modus</para></listitem> +</varlistentry> +<varlistentry><term>/n</term> +<listitem><para>names a printer</para></listitem> +</varlistentry> +<varlistentry><term>/in</term> +<listitem><para>adds a network printer connection</para></listitem> +</varlistentry> +<varlistentry><term>/y</term> +<listitem><para>sets printer as default printer</para></listitem> +</varlistentry> +</variablelist> + +<para> +I have tested this with a Samba 2.2.7a and a Samba-3alpha24 +installation and Windows XP Professional clients. Note that this +specific command set works with network print queues (installing +local print queues requires different parameters, but this is of no +interest here). +</para> + +<itemizedlist> +<listitem><para>Line 1 deletes a possibly existing previous network +printer <emphasis>infotec2105-IPDS</emphasis> (which had used native +Windows drivers with LPRng that were removed from the server which was +converted to CUPS). The <command>/q</command> at the end eliminates +"Confirm" or error dialog boxes popping up. They should not be +presented to the user logging on.</para></listitem> + +<listitem><para>Line 2 adds the new printer +<emphasis>infotec2105-PS</emphasis> (which actually is same physical +device but is now run by the new CUPS printing system and associated +with the CUPS/Adobe PS drivers). The printer and its driver +<emphasis>must</emphasis> have been added to Samba prior to the user +logging in (e.g. by a procedure as discussed earlier in this chapter, +or by running <command>cupsaddsmb</command>). The driver is now +auto-downloaded to the client PC where the user is about to log +in.</para></listitem> + +<listitem><para>Line 3 sets the default printer to this new network +printer (there might be several other printers installed with this +same method and some may be local as well -- so we deside for a +default printer). The default printer selection may of course be +different for different users.</para></listitem> +</itemizedlist> + +<para> +Note that the second line only works if the printer +<emphasis>infotec2105-PS</emphasis> has an already working printqueue +on "sambacupsserver", and if the printer drivers have sucessfully been +uploaded (via <command>APW</command> , +<command>smbclient/rpcclient</command> or +<command>cupsaddsmb</command>) into the +<parameter>[print$]</parameter> driver repository of Samba. Also, some +Samba versions prior to version 3.0 required a re-start of smbd after +the printer install and the driver upload, otherwise the script (or +any other client driver download) would fail. +</para> + +<para> +Since there no easy way to test for the existence of an installed +network printer from the logon script, the suggestion is: don't bother +checking and just allow the deinstallation/reinstallation to occur +every time a user logs in; it's really quick anyway (1 to 2 seconds). +</para> + +<para> +The additional benefits for this are: +</para> + +<itemizedlist> +<listitem><para>It puts in place any printer default setup changes +automatically at every user logon.</para></listitem> + +<listitem><para>It allows for "roaming" users' login into the domain from +different workstations.</para></listitem> +</itemizedlist> + +<para> +Since network printers are installed per user this much simplifies the +process of keeping the installation up-to-date. The extra few seconds +at logon time will not really be noticeable. Printers can be centrally +added, changed, and deleted at will on the server with no user +intervention required on the clients (you just need to keep the logon +scripts up to date). +</para> +</sect1> + +<sect1> +<title>The <command>addprinter</command> command</title> + +<para> +The <command>addprinter</command> command can be configured to be a +shell script or program executed by Samba. It is triggered by running +the APW from a client against the Samba print server. The APW asks the +user to fill in several fields (such as printer name, driver to be +used, comment, port monitor, etc.). These parameters are passed on to +Samba by the APW. If the addprinter command is designed in a way that +it can create a new printer (through writing correct printcap entries +on legacy systems, or execute the <command>lpadmin</command> command +on more modern systems) and create the associated share in +<filename>smb.conf</filename>, then the APW will in effect really +create a new printer on Samba and the UNIX print subsystem! +</para> +</sect1> + +<sect1> +<title>Migration of "Classical" printing to Samba-3</title> + +<para> +The basic "NT-style" printer driver management has not changed +considerably in 3.0 over the 2.2.x releases (apart from many small +improvements). Here migration should be quite easy, especially if you +followed previous advice to stop using deprecated parameters in your +setup. For migrations from an existing 2.0.x setup, or if you +continued "Win9x-style" printing in your Samba 2.2 installations, it +is more of an effort. Please read the appropriate release notes and +the HOWTO Collection for 2.2. You can follow several paths. Here are +possible scenarios for migration: +</para> + +<itemizedlist> +<listitem><para>You need to study and apply the new Windows NT printer +and driver support. Previously used parameters "<parameter>printer +driver file</parameter>", " <parameter>printer driver</parameter>" and +"<parameter>printer driver location</parameter>" are no longer +supported.</para></listitem> + +<listitem><para>If you want to take advantage of WinNT printer driver +support you also need to migrate theWin9x/ME drivers to the new +setup.</para></listitem> + +<listitem><para>An existing <filename>printers.def</filename> file +(the one specified in the now removed parameter <parameter>printer +driver file = ...</parameter>) will work no longer with Samba-3.0. In +3.0, smbd attempts to locate a Win9x/ME driver files for the printer +in <parameter>[print$]</parameter> and additional settings in the TDB +and only there; if it fails it will <emphasis>not</emphasis> (as 2.2.x +used to do) drop down to using a <filename>printers.def</filename> +(and all associated parameters). The make_printerdef tool is removed +and there is no backwards compatibility for this.</para></listitem> + +<listitem><para>You need to install a Windows 9x driver into the +<parameter>[print$]</parameter> share for a printer on your Samba +host. The driver files will be stored in the "WIN40/0" subdirectory of +<parameter>[print$]</parameter>, and some other settings and info go +into the printing-related TDBs.</para></listitem> + +<listitem><para>If you want to migrate an existing +<filename>printers.def</filename> file into the new setup, the current +only solution is to use the Windows NT APW to install the NT drivers +and the 9x drivers. This can be scripted using smbclient and +rpcclient. See the Imprints installation client at: +</para> + +<para> +<ulink url="http://imprints.sourceforge.net/"><emphasis>http://imprints.sourceforge.net/</emphasis></ulink> +</para> + +<para> +for an example. See also the discussion of rpcclient usage in the +"CUPS Printing" section.</para></listitem> +</itemizedlist> +</sect1> + +<sect1> +<title>Publishing Printer Information in Active Directory or LDAP</title> + +<para> +We will publish an update to this section shortly. +</para> +</sect1> + +<sect1> +<title>Common Errors and Problems</title> + +<para> +Here are a few typical errors and problems people have +encountered. You can avoid them. Read on. +</para> <sect2> -<title>Real debugging</title> +<title>I give my root password but I don't get access</title> <para> -If the above debug tips don't help, then maybe you need to bring in -the bug guns, system tracing. See Tracing.txt in this directory. +Don't confuse the root password which is valid for the Unix system +(and in most cases stored in the form of a one-way hash in a file +named <filename>/etc/shadow</filename>) with the password used to +authenticate against Samba!. Samba doesn't know the UNIX password; for +root to access Samba resources via Samba-type access, a Samba account +for root must be created first. This is often done with the +<command>smbpasswd</command> command. </para> </sect2> + +<sect2> +<title>My printjobs get spooled into the spooling directory, but then get lost</title> + +<para> +Don't use the existing Unix print system spool directory for the Samba +spool directory. It may seem convenient and a saving of space, but it +only leads to problems. The two <emphasis>must</emphasis> be separate. +</para> + +</sect2> </sect1> </chapter> diff --git a/docs/docbook/projdoc/samba-doc.xml b/docs/docbook/projdoc/samba-doc.xml index a4394d263f..d6748844b9 100644 --- a/docs/docbook/projdoc/samba-doc.xml +++ b/docs/docbook/projdoc/samba-doc.xml @@ -67,6 +67,7 @@ PLEASE read this.</para> </partintro> &IntroSMB; &UNIX-INSTALL; +&FastStart; </part> <part id="type"> @@ -84,6 +85,7 @@ section carefully. &Samba-BDC-HOWTO; &DOMAIN-MEMBER; &StandAloneServer; +&ClientConfig; </part> <part id="optional"> @@ -112,6 +114,15 @@ Samba has several features that you might want or might not want to use. The cha &Samba-PAM; &IntegratingWithWindows; &unicode; +&Backup; +&HighAvailability; +</part> + +<part id="migration"> +<title>Migration and Updating</title> +&upgrading; +&NT4Migration; +&SWAT; </part> <part id="troubleshooting"> @@ -124,12 +135,13 @@ Samba has several features that you might want or might not want to use. The cha <part id="Appendixes"> <title>Appendixes</title> &Compiling; -&NT4Migration; &Portability; &Other-Clients; -&SWAT; &SPEED; +&DNS-DHCP-Configuration; &Further-Resources; </part> +<index/> + </book> diff --git a/docs/docbook/projdoc/securing-samba.xml b/docs/docbook/projdoc/securing-samba.xml index 204fceeb4a..b137a05ec9 100644 --- a/docs/docbook/projdoc/securing-samba.xml +++ b/docs/docbook/projdoc/securing-samba.xml @@ -3,7 +3,7 @@ <chapterinfo> &author.tridge; &author.jht; - <pubdate>17 March 2003</pubdate> + <pubdate>May 26, 2003</pubdate> </chapterinfo> <title>Securing Samba</title> @@ -16,209 +16,354 @@ important security fix. The information contained here applies to Samba installations in general. </para> -</sect1> - -<sect1> -<title>Using host based protection</title> - <para> -In many installations of Samba the greatest threat comes for outside -your immediate network. By default Samba will accept connections from -any host, which means that if you run an insecure version of Samba on -a host that is directly connected to the Internet you can be -especially vulnerable. +A new apprentice reported for duty to the Chief Engineer of a boiler house. He said, "Here I am, +if you will show me the boiler I'll start working on it." Then engineer replied, "You're leaning +on it!" </para> <para> -One of the simplest fixes in this case is to use the <command>hosts allow</command> and -<command>hosts deny</command> options in the Samba &smb.conf; configuration file to only -allow access to your server from a specific range of hosts. An example -might be: -</para> - -<para><programlisting> - hosts allow = 127.0.0.1 192.168.2.0/24 192.168.3.0/24 - hosts deny = 0.0.0.0/0 -</programlisting></para> - -<para> -The above will only allow SMB connections from 'localhost' (your own -computer) and from the two private networks 192.168.2 and -192.168.3. All other connections will be refused as soon -as the client sends its first packet. The refusal will be marked as a -'not listening on called name' error. +Security concerns are just like that: You need to know a little about the subject to appreciate +how obvious most of it really is. The challenge for most of us is to discover that first morsel +of knowledge with which we may unlock the secrets of the masters. </para> </sect1> <sect1> -<title>User based protection</title> +<title>Features and Benefits</title> <para> -If you want to restrict access to your server to valid users only then the following -method may be of use. In the smb.conf [globals] section put: +There are three level at which security principals must be observed in order to render a site +at least moderately secure. These are: the perimeter firewall, the configuration of the host +server that is running Samba, and Samba itself. </para> -<para><programlisting> - valid users = @smbusers, jacko -</programlisting></para> - <para> -What this does is, it restricts all server access to either the user <emphasis>jacko</emphasis> -or to members of the system group <emphasis>smbusers</emphasis>. +Samba permits a most flexible approach to network security. As far as possible Samba implements +the latest protocols to permit more secure MS Windows file and print operations. </para> -</sect1> - -<sect1> - -<title>Using interface protection</title> - <para> -By default Samba will accept connections on any network interface that -it finds on your system. That means if you have a ISDN line or a PPP -connection to the Internet then Samba will accept connections on those -links. This may not be what you want. +Samba may be secured from connections that originate from outside the local network. This may be +done using <emphasis>host based protection</emphasis> (using samba's implementation of a technology +known as "tcpwrappers", or it may be done be using <emphasis>interface based exclusion</emphasis> +so that &smbd; will bind only to specifically permitted interfaces. It is also +possible to set specific share or resource based exclusions, eg: on the <parameter>IPC$</parameter> +auto-share. The <parameter>IPC$</parameter> share is used for browsing purposes as well as to establish +TCP/IP connections. </para> <para> -You can change this behaviour using options like the following: -</para> - -<para><programlisting> - interfaces = eth* lo - bind interfaces only = yes -</programlisting></para> - -<para> -This tells Samba to only listen for connections on interfaces with a -name starting with 'eth' such as eth0, eth1, plus on the loopback -interface called 'lo'. The name you will need to use depends on what -OS you are using, in the above I used the common name for Ethernet -adapters on Linux. -</para> - -<para> -If you use the above and someone tries to make a SMB connection to -your host over a PPP interface called 'ppp0' then they will get a TCP -connection refused reply. In that case no Samba code is run at all as -the operating system has been told not to pass connections from that -interface to any samba process. +Another method by which Samba may be secured is by way of setting Access Control Entries in an Access +Control List on the shares themselves. This is discussed in the chapter on File, Directory and Share Access +Control. </para> </sect1> <sect1> -<title>Using a firewall</title> - -<para> -Many people use a firewall to deny access to services that they don't -want exposed outside their network. This can be a very good idea, -although I would recommend using it in conjunction with the above -methods so that you are protected even if your firewall is not active -for some reason. -</para> +<title>Technical Discussion of Protective Measures and Issues</title> <para> -If you are setting up a firewall then you need to know what TCP and -UDP ports to allow and block. Samba uses the following: -</para> - -<para><programlisting> - UDP/137 - used by nmbd - UDP/138 - used by nmbd - TCP/139 - used by smbd - TCP/445 - used by smbd -</programlisting></para> - -<para> -The last one is important as many older firewall setups may not be -aware of it, given that this port was only added to the protocol in -recent years. +The key challenge of security is the fact that protective measures suffice at best +only to close the door on known exploits and breach techniques. Never assume that +because you have followed these few measures that the Samba server is now an impenetrable +fortress! Given the history of information systems so far, it is only a matter of time +before someone will find yet another vulnerability. </para> + <sect2> + <title>Using host based protection</title> + + <para> + In many installations of Samba the greatest threat comes for outside + your immediate network. By default Samba will accept connections from + any host, which means that if you run an insecure version of Samba on + a host that is directly connected to the Internet you can be + especially vulnerable. + </para> + + <para> + One of the simplest fixes in this case is to use the <parameter>hosts allow</parameter> and + <parameter>hosts deny</parameter> options in the Samba &smb.conf; configuration file to only + allow access to your server from a specific range of hosts. An example + might be: + </para> + + <para><programlisting> + hosts allow = 127.0.0.1 192.168.2.0/24 192.168.3.0/24 + hosts deny = 0.0.0.0/0 + </programlisting></para> + + <para> + The above will only allow SMB connections from 'localhost' (your own + computer) and from the two private networks 192.168.2 and + 192.168.3. All other connections will be refused as soon + as the client sends its first packet. The refusal will be marked as a + <errorname>not listening on called name</errorname> error. + </para> + + </sect2> + + <sect2> + <title>User based protection</title> + + <para> + If you want to restrict access to your server to valid users only then the following + method may be of use. In the &smb.conf; <parameter>[globals]</parameter> section put: + </para> + + <para><programlisting> + valid users = @smbusers, jacko + </programlisting></para> + + <para> + What this does is, it restricts all server access to either the user <emphasis>jacko</emphasis> + or to members of the system group <emphasis>smbusers</emphasis>. + </para> + + </sect2> + + <sect2> + + <title>Using interface protection</title> + + <para> + By default Samba will accept connections on any network interface that + it finds on your system. That means if you have a ISDN line or a PPP + connection to the Internet then Samba will accept connections on those + links. This may not be what you want. + </para> + + <para> + You can change this behaviour using options like the following: + </para> + + <para><programlisting> + interfaces = eth* lo + bind interfaces only = yes + </programlisting></para> + + <para> + This tells Samba to only listen for connections on interfaces with a + name starting with 'eth' such as eth0, eth1, plus on the loopback + interface called 'lo'. The name you will need to use depends on what + OS you are using, in the above I used the common name for Ethernet + adapters on Linux. + </para> + + <para> + If you use the above and someone tries to make a SMB connection to + your host over a PPP interface called 'ppp0' then they will get a TCP + connection refused reply. In that case no Samba code is run at all as + the operating system has been told not to pass connections from that + interface to any samba process. + </para> + + </sect2> + + <sect2> + <title>Using a firewall</title> + + <para> + Many people use a firewall to deny access to services that they don't + want exposed outside their network. This can be a very good idea, + although I would recommend using it in conjunction with the above + methods so that you are protected even if your firewall is not active + for some reason. + </para> + + <para> + If you are setting up a firewall then you need to know what TCP and + UDP ports to allow and block. Samba uses the following: + </para> + + <simplelist> + <member>UDP/137 - used by nmbd</member> + <member>UDP/138 - used by nmbd</member> + <member>TCP/139 - used by smbd</member> + <member>TCP/445 - used by smbd</member> + </simplelist> + + <para> + The last one is important as many older firewall setups may not be + aware of it, given that this port was only added to the protocol in + recent years. + </para> + + </sect2> + + <sect2> + <title>Using a IPC$ share deny</title> + + <para> + If the above methods are not suitable, then you could also place a + more specific deny on the IPC$ share that is used in the recently + discovered security hole. This allows you to offer access to other + shares while denying access to IPC$ from potentially untrustworthy + hosts. + </para> + + <para> + To do that you could use: + </para> + + <para><programlisting> +[ipc$] + hosts allow = 192.168.115.0/24 127.0.0.1 + hosts deny = 0.0.0.0/0 + </programlisting></para> + + <para> + this would tell Samba that IPC$ connections are not allowed from + anywhere but the two listed places (localhost and a local + subnet). Connections to other shares would still be allowed. As the + IPC$ share is the only share that is always accessible anonymously + this provides some level of protection against attackers that do not + know a username/password for your host. + </para> + + <para> + If you use this method then clients will be given a <errorname>access denied</errorname> + reply when they try to access the IPC$ share. That means that those + clients will not be able to browse shares, and may also be unable to + access some other resources. + </para> + + <para> + This is not recommended unless you cannot use one of the other + methods listed above for some reason. + </para> + + </sect2> + + <sect2> + <title>NTLMv2 Security</title> + + <para> + To configure NTLMv2 authentication the following registry keys are worth knowing about: + </para> + + <!-- FIXME --> + <para> + <screen> + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa] + "lmcompatibilitylevel"=dword:00000003 + + 0x3 - Send NTLMv2 response only. Clients will use NTLMv2 authentication, + use NTLMv2 session security if the server supports it. Domain + controllers accept LM, NTLM and NTLMv2 authentication. + + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0] + "NtlmMinClientSec"=dword:00080000 + + 0x80000 - NTLMv2 session security. If either NtlmMinClientSec or + NtlmMinServerSec is set to 0x80000, the connection will fail if NTLMv2 + session security is not negotiated. + </screen> + </para> + </sect2> </sect1> <sect1> -<title>Using a IPC$ share deny</title> - -<para> -If the above methods are not suitable, then you could also place a -more specific deny on the IPC$ share that is used in the recently -discovered security hole. This allows you to offer access to other -shares while denying access to IPC$ from potentially untrustworthy -hosts. -</para> - -<para> -To do that you could use: -</para> - -<para><programlisting> - [ipc$] - hosts allow = 192.168.115.0/24 127.0.0.1 - hosts deny = 0.0.0.0/0 -</programlisting></para> - -<para> -this would tell Samba that IPC$ connections are not allowed from -anywhere but the two listed places (localhost and a local -subnet). Connections to other shares would still be allowed. As the -IPC$ share is the only share that is always accessible anonymously -this provides some level of protection against attackers that do not -know a username/password for your host. -</para> - -<para> -If you use this method then clients will be given a 'access denied' -reply when they try to access the IPC$ share. That means that those -clients will not be able to browse shares, and may also be unable to -access some other resources. -</para> +<title>Upgrading Samba</title> <para> -This is not recommended unless you cannot use one of the other -methods listed above for some reason. +Please check regularly on <ulink url="http://www.samba.org/">http://www.samba.org/</ulink> for updates and +important announcements. Occasionally security releases are made and +it is highly recommended to upgrade Samba when a security vulnerability +is discovered. </para> </sect1> <sect1> -<title>NTLMv2 Security</title> - -<para> -To configure NTLMv2 authentication the following registry keys are worth knowing about: -</para> +<title>Common Errors</title> <para> -<programlisting> - [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa] - "lmcompatibilitylevel"=dword:00000003 - - 0x3 - Send NTLMv2 response only. Clients will use NTLMv2 authentication, - use NTLMv2 session security if the server supports it. Domain - controllers accept LM, NTLM and NTLMv2 authentication. - - [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0] - "NtlmMinClientSec"=dword:00080000 - - 0x80000 - NTLMv2 session security. If either NtlmMinClientSec or - NtlmMinServerSec is set to 0x80000, the connection will fail if NTLMv2 - session security is not negotiated. -</programlisting> +If all of samba and host platform configuration were really as intuitive as one might like then this +section would not be necessary. Security issues are often vexing for a support person to resolve, not +because of the complexity of the problem, but for reason that most admininstrators who post what turns +out to be a security problem request are totally convinced that the problem is with Samba. </para> -</sect1> - -<sect1> -<title>Upgrading Samba</title> -<para> -Please check regularly on <ulink url="http://www.samba.org/">http://www.samba.org/</ulink> for updates and -important announcements. Occasionally security releases are made and -it is highly recommended to upgrade Samba when a security vulnerability -is discovered. -</para> + <sect2> + <title>Smbclient works on localhost, but the network is dead</title> + + <para> + This is a very common problem. Red Hat Linux (as do others) will install a default firewall. + With the default firewall in place only traffic on the loopback adapter (IP address 127.0.0.1) + will be allowed through the firewall. + </para> + + <para> + The solution is either to remove the firewall (stop it) or to modify the firewall script to + allow SMB networking traffic through. See section above in this chapter. + </para> + + </sect2> + + <sect2> + <title>Why can users access home directories of other users?</title> + + <para> + <quote> + We are unable to keep individual users from mapping to any other user's + home directory once they have supplied a valid password! They only need + to enter their own password. I have not found *any* method that I can + use to configure samba to enforce that only a user may map their own + home directory. + </quote> + </para> + + <para><quote> + User xyzzy can map his home directory. Once mapped user xyzzy can also map + *anyone* elses home directory! + </quote></para> + + <para> + This is not a security flaw, it is by design. Samba allows + users to have *exactly* the same access to the UNIX filesystem + as they would if they were logged onto the UNIX box, except + that it only allows such views onto the file system as are + allowed by the defined shares. + </para> + + <para> + This means that if your UNIX home directories are set up + such that one user can happily cd into another users + directory and do an ls, the UNIX security solution is to + change the UNIX file permissions on the users home directories + such that the cd and ls would be denied. + </para> + + <para> + Samba tries very hard not to second guess the UNIX administrators + security policies, and trusts the UNIX admin to set + the policies and permissions he or she desires. + </para> + + <para> + Samba does allow the setup you require when you have set the + <parameter>only user = yes</parameter> option on the share, is that you have not set the + valid users list for the share. + </para> + + <para> + Note that only user works in conjunction with the users= list, + so to get the behavior you require, add the line : + <programlisting> + users = %S + </programlisting> + this is equivalent to: + <programlisting> + valid users = %S + </programlisting> + to the definition of the <parameter>[homes]</parameter> share, as recommended in + the &smb.conf; man page. + </para> + </sect2> </sect1> - </chapter> diff --git a/docs/docbook/projdoc/unicode.xml b/docs/docbook/projdoc/unicode.xml index 2351668e56..cb55c084c4 100644 --- a/docs/docbook/projdoc/unicode.xml +++ b/docs/docbook/projdoc/unicode.xml @@ -13,6 +13,32 @@ <title>Unicode/Charsets</title> <sect1> +<title>Features and Benefits</title> + +<para> +Every industry eventually matures. One of the great areas of maturation is in +the focus that has been given over the past decade to make it possible for anyone +anywhere to use a computer. It has not always been that way, in fact, not so long +ago it was common for software to be written for exclusive use in the country of +origin. +</para> + +<para> +Of all the effort that has been brought to bear on providing native language support +for all computer users, the efforts of the Openi18n organisation is deserving of +special mention. For more information about Openi18n please refer to: +<link url="http://www.openi18n.org/">http://www.openi18n.org/</link>. +</para> + +<para> +Samba-2.x supported a single locale through a mechanism called +<emphasis>codepages</emphasis>. Samba-3 is destined to become a truely trans-global +file and printer sharing platform. +</para> + +</sect1> + +<sect1> <title>What are charsets and unicode?</title> <para> @@ -61,7 +87,7 @@ samba knows of three kinds of character sets: <variablelist> <varlistentry> - <term>unix charset</term> + <term><parameter>unix charset</parameter></term> <listitem><para> This is the charset used internally by your operating system. The default is <constant>ASCII</constant>, which is fine for most @@ -70,14 +96,14 @@ samba knows of three kinds of character sets: </varlistentry> <varlistentry> - <term>display charset</term> + <term><parameter>display charset</parameter></term> <listitem><para>This is the charset samba will use to print messages on your screen. It should generally be the same as the <command>unix charset</command>. </para></listitem> </varlistentry> <varlistentry> - <term>dos charset</term> + <term><parameter>dos charset</parameter></term> <listitem><para>This is the charset samba uses when communicating with DOS and Windows 9x clients. It will talk unicode to all newer clients. The default depends on the charsets you have installed on your system. @@ -114,24 +140,24 @@ points of attention when setting it up:</para> <itemizedlist> -<listitem><para>You should set <command>mangling method = -hash</command></para></listitem> +<listitem><para>You should set <parameter>mangling method = +hash</parameter></para></listitem> <listitem><para>There are various iconv() implementations around and not all of them work equally well. glibc2's iconv() has a critical problem in CP932. libiconv-1.8 works with CP932 but still has some problems and does not work with EUC-JP.</para></listitem> -<listitem><para>You should set <command>dos charset = CP932</command>, not +<listitem><para>You should set <parameter>dos charset = CP932</parameter>, not Shift_JIS, SJIS...</para></listitem> -<listitem><para>Currently only <command>unix charset = CP932</command> +<listitem><para>Currently only <parameter>unix charset = CP932</parameter> will work (but still has some problems...) because of iconv() issues. -<command>unix charset = EUC-JP</command> doesn't work well because of +<parameter>unix charset = EUC-JP</parameter> doesn't work well because of iconv() issues.</para></listitem> -<listitem><para>Currently Samba 3.0 does not support <command>unix charset -= UTF8-MAC/CAP/HEX/JIS*</command></para></listitem> +<listitem><para>Currently Samba 3.0 does not support <parameter>unix charset += UTF8-MAC/CAP/HEX/JIS*</parameter></para></listitem> </itemizedlist> diff --git a/docs/docbook/projdoc/upgrading-to-3.0.xml b/docs/docbook/projdoc/upgrading-to-3.0.xml index 3dc4816664..b4c0732a65 100644 --- a/docs/docbook/projdoc/upgrading-to-3.0.xml +++ b/docs/docbook/projdoc/upgrading-to-3.0.xml @@ -4,7 +4,7 @@ <pubdate>25 October 2002</pubdate> </chapterinfo> -<title>Issues when upgrading from 2.2 to 3.0</title> +<title>Upgrading from Samba-2.x to Samba-3.0.0</title> <sect1> <title>Charsets</title> @@ -31,6 +31,34 @@ In 3.0, the following configuration options have been removed. <member>use rhosts</member> <member>postscript</member> <member>client code page (replaced by dos charset)</member> +<member>vfs path</member> +<member>vfs options</member> </simplelist> </sect1> + +<sect1> +<title>Password Backend</title> + +<para> +Effective with the release of samba-3 it is now imperative that the password backend +be correctly defined in smb.conf. +</para> + +<para> +Those migrating from samba-2.x with plaintext password support need the following: +<emphasis>passdb backend = guest</emphasis>. +</para> + +<para> +Those migrating from samba-2.x with encrypted password support should add to smb.conf +<emphasis>passdb backend = smbpasswd, guest</emphasis>. +</para> + +<para> +LDAP using Samba-2.x systems can continue to operate with the following entry +<emphasis>passdb backend = ldapsam_compat, guest</emphasis>. +</para> + +</sect1> + </chapter> diff --git a/docs/docbook/projdoc/winbind.xml b/docs/docbook/projdoc/winbind.xml index cb6a56687d..4b2951805e 100644 --- a/docs/docbook/projdoc/winbind.xml +++ b/docs/docbook/projdoc/winbind.xml @@ -10,7 +10,6 @@ </affiliation> </author> &author.tridge; - &author.jht; <author> <firstname>Naag</firstname><surname>Mummaneni</surname> <affiliation> @@ -18,14 +17,15 @@ </affiliation> </author> &author.jelmer; + &author.jht; </authorgroup> <pubdate>27 June 2002</pubdate> </chapterinfo> -<title>Unified Logons between Windows NT and UNIX using Winbind</title> +<title>Integrated Logon Support using Winbind</title> <sect1> - <title>Abstract</title> + <title>Features and Benefits</title> <para>Integration of UNIX and Microsoft Windows NT through a unified logon has been considered a "holy grail" in heterogeneous @@ -223,7 +223,9 @@ of that service should be tried and in what order. If the passwd config line is:</para> - <para><command>passwd: files example</command></para> + <para><programlisting> +passwd: files example + </programlisting></para> <para>then the C library will first load a module called <filename>/lib/libnss_files.so</filename> followed by @@ -337,8 +339,8 @@ the winbind services which come with SAMBA 3.0. <title>Introduction</title> <para> -This HOWTO describes the procedures used to get winbind up and -running on my RedHat 7.1 system. Winbind is capable of providing access +This section describes the procedures used to get winbind up and +running on a RedHat 7.1 system. Winbind is capable of providing access and authentication control for Windows Domain users through an NT or Win2K PDC for 'regular' services, such as telnet a nd ftp, as well for SAMBA services. @@ -428,17 +430,15 @@ install the development packages in <filename>pam-devel-0.74-22</filename>. <para> Before starting, it is probably best to kill off all the SAMBA -related daemons running on your server. Kill off all <command>smbd</command>, -<command>nmbd</command>, and <command>winbindd</command> processes that may +related daemons running on your server. Kill off all &smbd;, +&nmbd;, and &winbindd; processes that may be running. To use PAM, you will want to make sure that you have the standard PAM package (for RedHat) which supplies the <filename>/etc/pam.d</filename> directory structure, including the pam modules are used by pam-aware services, several pam libraries, and the <filename>/usr/doc</filename> and <filename>/usr/man</filename> entries for pam. Winbind built better in SAMBA if the pam-devel package was also installed. This package includes -the header files needed to compile pam-aware applications. For instance, -my RedHat system has both <filename>pam-0.74-22</filename> and -<filename>pam-devel-0.74-22</filename> RPMs installed. +the header files needed to compile pam-aware applications. </para> <sect3> @@ -450,14 +450,14 @@ The first three steps may not be necessary depending upon whether or not you have previously built the Samba binaries. </para> -<para><programlisting> -<prompt>root#</prompt> <command>autoconf</command> -<prompt>root#</prompt> <command>make clean</command> -<prompt>root#</prompt> <command>rm config.cache</command> -<prompt>root#</prompt> <command>./configure</command> -<prompt>root#</prompt> <command>make</command> -<prompt>root#</prompt> <command>make install</command> -</programlisting></para> +<para><screen> +&rootprompt;<command>autoconf</command> +&rootprompt;<command>make clean</command> +&rootprompt;<command>rm config.cache</command> +&rootprompt;<command>./configure</command> +&rootprompt;<command>make</command> +&rootprompt;<command>make install</command> +</screen></para> <para> @@ -473,12 +473,14 @@ It will also build the winbindd executable and libraries. winbind libraries on Linux and Solaris</title> <para> -The libraries needed to run the <command>winbindd</command> daemon +The libraries needed to run the &winbindd; daemon through nsswitch need to be copied to their proper locations, so </para> <para> -<prompt>root#</prompt> <command>cp ../samba/source/nsswitch/libnss_winbind.so /lib</command> +<screen> +&rootprompt;<userinput>cp ../samba/source/nsswitch/libnss_winbind.so /lib</userinput> +</screen> </para> <para> @@ -486,19 +488,19 @@ I also found it necessary to make the following symbolic link: </para> <para> -<prompt>root#</prompt> <command>ln -s /lib/libnss_winbind.so /lib/libnss_winbind.so.2</command> +&rootprompt; <userinput>ln -s /lib/libnss_winbind.so /lib/libnss_winbind.so.2</userinput> </para> <para>And, in the case of Sun solaris:</para> -<para> -<prompt>root#</prompt> <userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/libnss_winbind.so.1</userinput> -<prompt>root#</prompt> <userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/nss_winbind.so.1</userinput> -<prompt>root#</prompt> <userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/nss_winbind.so.2</userinput> -</para> +<screen> +&rootprompt;<userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/libnss_winbind.so.1</userinput> +&rootprompt;<userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/nss_winbind.so.1</userinput> +&rootprompt;<userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/nss_winbind.so.2</userinput> +</screen> <para> Now, as root you need to edit <filename>/etc/nsswitch.conf</filename> to -allow user and group entries to be visible from the <command>winbindd</command> +allow user and group entries to be visible from the &winbindd; daemon. My <filename>/etc/nsswitch.conf</filename> file look like this after editing: </para> @@ -517,7 +519,7 @@ is faster (and you don't need to reboot) if you do it manually: </para> <para> -<prompt>root#</prompt> <command>/sbin/ldconfig -v | grep winbind</command> +&rootprompt;<userinput>/sbin/ldconfig -v | grep winbind</userinput> </para> <para> @@ -566,11 +568,11 @@ url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/baseadmn/ia <para> Several parameters are needed in the smb.conf file to control -the behavior of <command>winbindd</command>. Configure -<filename>smb.conf</filename> These are described in more detail in +the behavior of &winbindd;. Configure +&smb.conf; These are described in more detail in the <citerefentry><refentrytitle>winbindd</refentrytitle> <manvolnum>8</manvolnum></citerefentry> man page. My -<filename>smb.conf</filename> file was modified to +&smb.conf; file was modified to include the following entries in the [global] section: </para> @@ -606,7 +608,7 @@ a domain user who has administrative privileges in the domain. <para> -<prompt>root#</prompt> <command>/usr/local/samba/bin/net join -S PDC -U Administrator</command> +&rootprompt;<userinput>/usr/local/samba/bin/net join -S PDC -U Administrator</userinput> </para> @@ -631,7 +633,7 @@ command as root: </para> <para> -<prompt>root#</prompt> <command>/usr/local/samba/bin/winbindd</command> +&rootprompt;<userinput>/usr/local/samba/bin/winbindd</userinput> </para> <para> @@ -640,11 +642,11 @@ run as 2 processes. The first will answer all requests from the cache, thus making responses to clients faster. The other will update the cache for the query that the first has just responded. Advantage of this is that responses stay accurate and are faster. -You can enable dual daemon mode by adding '-B' to the commandline: +You can enable dual daemon mode by adding <option>-B</option> to the commandline: </para> <para> -<prompt>root#</prompt> <command>/usr/local/samba/bin/winbindd -B</command> +&rootprompt;<userinput>/usr/local/samba/bin/winbindd -B</userinput> </para> <para> @@ -653,14 +655,14 @@ is really running... </para> <para> -<prompt>root#</prompt> <command>ps -ae | grep winbindd</command> +&rootprompt;<userinput>ps -ae | grep winbindd</userinput> </para> <para> This command should produce output like this, if the daemon is running </para> -<para> +<screen> 3025 ? 00:00:00 winbindd -</para> +</screen> <para> Now... for the real test, try to get some information about the @@ -668,7 +670,7 @@ users on your PDC </para> <para> -<prompt>root#</prompt> <command>/usr/local/samba/bin/wbinfo -u</command> +&rootprompt;<userinput>/usr/local/samba/bin/wbinfo -u</userinput> </para> <para> @@ -676,14 +678,14 @@ This should echo back a list of users on your Windows users on your PDC. For example, I get the following response: </para> -<para><programlisting> +<para><screen> CEO+Administrator CEO+burdell CEO+Guest CEO+jt-ad CEO+krbtgt CEO+TsInternetUser -</programlisting></para> +</screen></para> <para> Obviously, I have named my domain 'CEO' and my <parameter>winbind @@ -695,8 +697,8 @@ You can do the same sort of thing to get group information from the PDC: </para> -<para><programlisting> -<prompt>root#</prompt> <command>/usr/local/samba/bin/wbinfo -g</command> +<para><screen> +&rootprompt;<userinput>/usr/local/samba/bin/wbinfo -g</userinput> CEO+Domain Admins CEO+Domain Users CEO+Domain Guests @@ -706,7 +708,7 @@ the PDC: CEO+Schema Admins CEO+Enterprise Admins CEO+Group Policy Creator Owners -</programlisting></para> +</screen></para> <para> The function 'getent' can now be used to get unified @@ -715,7 +717,7 @@ Try the following command: </para> <para> -<prompt>root#</prompt> <command>getent passwd</command> +&rootprompt;<userinput>getent passwd</userinput> </para> <para> @@ -729,7 +731,7 @@ The same thing can be done for groups with the command </para> <para> -<prompt>root#</prompt> <command>getent group</command> +&rootprompt;<userinput>getent group</userinput> </para> </sect3> @@ -742,14 +744,13 @@ The same thing can be done for groups with the command <title>Linux</title> <para> -The <command>winbindd</command> daemon needs to start up after the -<command>smbd</command> and <command>nmbd</command> daemons are running. +The &winbindd; daemon needs to start up after the +&smbd; and &nmbd; daemons are running. To accomplish this task, you need to modify the startup scripts of your system. They are located at <filename>/etc/init.d/smb</filename> in RedHat and <filename>/etc/init.d/samba</filename> in Debian. script to add commands to invoke this daemon in the proper sequence. My -startup script starts up <command>smbd</command>, -<command>nmbd</command>, and <command>winbindd</command> from the +startup script starts up &smbd;, &nmbd;, and &winbindd; from the <filename>/usr/local/samba/bin</filename> directory directly. The 'start' function in the script looks like this: </para> @@ -898,8 +899,7 @@ in the script above with: <sect4> <title>Restarting</title> <para> -If you restart the <command>smbd</command>, <command>nmbd</command>, -and <command>winbindd</command> daemons at this point, you +If you restart the &smbd;, &nmbd;, and &winbindd; daemons at this point, you should be able to connect to the samba server as a domain member just as if you were a local user. </para> @@ -924,7 +924,7 @@ by invoking the command </para> <para> -<prompt>root#</prompt> <command>make nsswitch/pam_winbind.so</command> +&rootprompt;<userinput>make nsswitch/pam_winbind.so</userinput> </para> <para> @@ -936,7 +936,7 @@ modules reside in <filename>/usr/lib/security</filename>. </para> <para> -<prompt>root#</prompt> <command>cp ../samba/source/nsswitch/pam_winbind.so /lib/security</command> +&rootprompt;<userinput>cp ../samba/source/nsswitch/pam_winbind.so /lib/security</userinput> </para> <sect4> @@ -981,8 +981,8 @@ For ftp services to work properly, you will also need to either have individual directories for the domain users already present on the server, or change the home directory template to a general directory for all domain users. These can be easily set using -the <filename>smb.conf</filename> global entry -<command>template homedir</command>. +the &smb.conf; global entry +<parameter>template homedir</parameter>. </para> <para> @@ -1022,8 +1022,8 @@ same way. It now looks like this: </programlisting></para> <para> -In this case, I added the <command>auth sufficient /lib/security/pam_winbind.so</command> -lines as before, but also added the <command>required pam_securetty.so</command> +In this case, I added the <programlisting>auth sufficient /lib/security/pam_winbind.so</programlisting> +lines as before, but also added the <programlisting>required pam_securetty.so</programlisting> above it, to disallow root logins over the network. I also added a <command>sufficient /lib/security/pam_unix.so use_first_pass</command> line after the <command>winbind.so</command> line to get rid of annoying @@ -1124,7 +1124,19 @@ configured in the pam.conf. </sect1> <sect1> - <title>Limitations</title> +<title>Conclusion</title> + + <para>The winbind system, through the use of the Name Service + Switch, Pluggable Authentication Modules, and appropriate + Microsoft RPC calls have allowed us to provide seamless + integration of Microsoft Windows NT domain users on a + UNIX system. The result is a great reduction in the administrative + cost of running a mixed UNIX and NT network.</para> + +</sect1> + +<sect1> +<title>Common Errors</title> <para>Winbind has a number of limitations in its current released version that we hope to overcome in future @@ -1153,17 +1165,4 @@ configured in the pam.conf. </itemizedlist> </sect1> - -<sect1> - <title>Conclusion</title> - - <para>The winbind system, through the use of the Name Service - Switch, Pluggable Authentication Modules, and appropriate - Microsoft RPC calls have allowed us to provide seamless - integration of Microsoft Windows NT domain users on a - UNIX system. The result is a great reduction in the administrative - cost of running a mixed UNIX and NT network.</para> - -</sect1> - </chapter> |