diff options
Diffstat (limited to 'docs/Samba3-HOWTO')
122 files changed, 38100 insertions, 0 deletions
diff --git a/docs/Samba3-HOWTO/TOSHARG-AccessControls.xml b/docs/Samba3-HOWTO/TOSHARG-AccessControls.xml new file mode 100644 index 0000000000..f074d2c140 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-AccessControls.xml @@ -0,0 +1,1588 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> + +<chapter id="AccessControls"> +<chapterinfo> + &author.jht; + &author.jeremy; + <author>&person.jelmer;<contrib>drawing</contrib></author> + <pubdate>May 10, 2003</pubdate> +</chapterinfo> +<title>File, Directory and Share Access Controls</title> + +<para> +<indexterm><primary>ACLs</primary></indexterm> +Advanced MS Windows users are frequently perplexed when file, directory and share manipulation of +resources shared via Samba do not behave in the manner they might expect. MS Windows network +administrators are often confused regarding network access controls and how to +provide users with the access they need while protecting resources from unauthorized access. +</para> + +<para> +Many UNIX administrators are unfamiliar with the MS Windows environment and in particular +have difficulty in visualizing what the MS Windows user wishes to achieve in attempts to set file +and directory access permissions. +</para> + +<para> +The problem lies in the differences in how file and directory permissions and controls work +between the two environments. This difference is one that Samba cannot completely hide, even +though it does try to bridge the chasm to a degree. +</para> + +<para> +<indexterm><primary>Extended Attributes</primary></indexterm> +<indexterm><primary>ACLs</primary><secondary>POSIX</secondary></indexterm> + +POSIX Access Control List technology has been available (along with Extended Attributes) +for UNIX for many years, yet there is little evidence today of any significant use. This +explains to some extent the slow adoption of ACLs into commercial Linux products. MS Windows +administrators are astounded at this, given that ACLs were a foundational capability of the now +decade-old MS Windows NT operating system. +</para> + +<para> +The purpose of this chapter is to present each of the points of control that are possible with +Samba-3 in the hope that this will help the network administrator to find the optimum method +for delivering the best environment for MS Windows desktop users. +</para> + +<para> +This is an opportune point to mention that Samba was created to provide a means of interoperability +and interchange of data between differing operating environments. Samba has no intent to change +UNIX/Linux into a platform like MS Windows. Instead the purpose was and is to provide a sufficient +level of exchange of data between the two environments. What is available today extends well +beyond early plans and expectations, yet the gap continues to shrink. +</para> + +<sect1> +<title>Features and Benefits</title> + + <para> + Samba offers a lot of flexibility in file system access management. These are the key access control + facilities present in Samba today: + </para> + + <itemizedlist> + <title>Samba Access Control Facilities</title> + <listitem><para> + <indexterm><primary>permissions</primary><secondary>UNIX file and directory</secondary></indexterm> + <emphasis>UNIX File and Directory Permissions</emphasis> + </para> + + <para> + Samba honors 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 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 + to whom the UNIX permissions and controls are a little strange or unknown. + </para> + </listitem> + + <listitem><para> + <emphasis>Samba Share Definitions</emphasis> + </para> + + <para> + In configuring share settings and controls in the &smb.conf; file, + the network administrator can exercise overrides to native file + system permissions and behaviors. This can be handy and convenient + to effect behavior that is more like what MS Windows NT users expect + but it is seldom the <emphasis>best</emphasis> way to achieve this. + The basic options and techniques are described herein. + </para> + </listitem> + + <listitem><para> + <emphasis>Samba Share ACLs</emphasis> + <indexterm><primary>ACLs</primary><secondary>share</secondary></indexterm> + </para> + + <para> + Just like it is possible in MS Windows NT to set ACLs on shares + themselves, so it is possible to do this in Samba. + Few people make use of this facility, yet it remains one of the + easiest ways to affect access controls (restrictions) and can often + do so with minimum invasiveness compared with other methods. + </para> + </listitem> + + <listitem><para> + <indexterm><primary>ACLs</primary><secondary>POSIX</secondary></indexterm> + <indexterm><primary>ACLs</primary><secondary>Windows</secondary></indexterm> + <emphasis>MS Windows ACLs through UNIX POSIX ACLs</emphasis> + </para> + + <para> + The use of POSIX ACLs on UNIX/Linux is possible only if the underlying + operating system supports them. If not, then this option will not be + available to you. Current UNIX technology platforms have native support + for POSIX ACLs. There are patches for the Linux kernel that also provide + this. Sadly, few Linux platforms ship today with native ACLs and + Extended Attributes enabled. This chapter has pertinent information + for users of platforms that support them. + </para> + </listitem> + </itemizedlist> + +</sect1> + +<sect1> +<title>File System Access Controls</title> + +<para> +Perhaps the most important recognition to be made is the simple fact that MS Windows NT4/200x/XP +implement a totally divergent file system technology from what is provided in the UNIX operating system +environment. First we consider what the most significant differences are, then we look +at how Samba helps to bridge the differences. +</para> + + <sect2> + <title>MS Windows NTFS Comparison with UNIX File Systems</title> + + <para> +<indexterm><primary>NTFS</primary></indexterm> +<indexterm><primary>File System</primary></indexterm> +<indexterm><primary>File System</primary><secondary>UNIX</secondary></indexterm> +<indexterm><primary>File System</primary><secondary>Windows</secondary></indexterm> + + Samba operates on top of the UNIX file system. This means it is subject to UNIX file system conventions + and permissions. It also means that if the MS Windows networking environment requires file system + behavior that differs from UNIX file system behavior then somehow Samba is responsible for emulating + that in a transparent and consistent manner. + </para> + + <para> + It is good news that Samba does this to a large extent and on top of that provides a high degree + of optional configuration to override the default behavior. We look at some of these over-rides, + but for the greater part we will stay within the bounds of default behavior. Those wishing to explore + the depths of control ability should review the &smb.conf; man page. + </para> + + <para>The following compares file system features for UNIX with those of Microsoft Windows NT/200x: + <indexterm><primary>File System</primary><secondary>feature comparison</secondary></indexterm> + + </para> + + <variablelist> + <varlistentry> + <term>Name Space</term> + <listitem> + <para> + MS Windows NT4/200x/XP files names may be up to 254 characters long, and UNIX file names + may be 1023 characters long. In MS Windows, file extensions indicate particular file types, + in UNIX this is not so rigorously observed as all names are considered arbitrary. + </para> + <para> + What MS Windows calls a folder, UNIX calls a directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Case Sensitivity</term> + <listitem> + <para> + <indexterm><primary>8.3 file names</primary></indexterm> + <indexterm><primary>File System</primary><secondary>case sensitivity</secondary></indexterm> + MS Windows file names are generally upper case if made up of 8.3 (8 character file name + and 3 character extension. File names that are longer than 8.3 are case preserving and case + insensitive. + </para> + + <para> + UNIX file and directory names are case sensitive and case preserving. Samba implements the + MS Windows file name behavior, but it does so as a user application. The UNIX file system + provides no mechanism to perform case insensitive file name lookups. MS Windows does this + by default. This means that Samba has to carry the processing overhead to provide features + that are not native to the UNIX operating system environment. + </para> + <para> + Consider the following. All are unique UNIX names but one single MS Windows file name: + <screen> + MYFILE.TXT + MyFile.txt + myfile.txt + </screen></para> + + <para> + So clearly, in an MS Windows file name space these three files cannot co-exist, but in UNIX + they can. + </para> + <para> + So what should Samba do if all three are present? That which is lexically first will be + accessible to MS Windows users, the others are invisible and unaccessible &smbmdash; any + other solution would be suicidal. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Directory Separators</term> + <listitem> + + <para> + <indexterm><primary>Directory Separators</primary></indexterm> + MS Windows and DOS uses the backslash <constant>\</constant> as a directory delimiter, and UNIX uses + the forward-slash <constant>/</constant> as its directory delimiter. This is handled transparently by Samba. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Drive Identification</term> + <listitem> + <para> + <indexterm><primary>Drive Identification</primary></indexterm> + MS Windows products support a notion of drive letters, like <command>C:</command> to represent + disk partitions. UNIX has no concept of separate identifiers for file partitions, each + such file system is mounted to become part of the overall directory tree. + The UNIX directory tree begins at <constant>/</constant> just like the root of a DOS drive is specified as + <constant>C:\</constant>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>File Naming Conventions</term> + <listitem> + <para> + <indexterm><primary>File Naming Conventions</primary></indexterm> + MS Windows generally never experiences file names that begin with a dot (<constant>.</constant>) while in UNIX these + are commonly found in a user's home directory. Files that begin with a dot (<constant>.</constant>) are typically + either start-up files for various UNIX applications, or they may be files that contain + start-up configuration data. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Links and Short-Cuts</term> + <listitem> + <para> + <indexterm><primary>Links</primary><secondary>hard</secondary></indexterm> + <indexterm><primary>Links</primary><secondary>soft</secondary></indexterm> + <indexterm><primary>Short-Cuts</primary></indexterm> + MS Windows make use of <quote>links and short-cuts</quote> 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 + links, but they are entirely different from what MS Windows users are used to. + </para> + <para> + Symbolic links are files in UNIX that contain the actual location of the data (file or directory). An + operation (like read or write) will operate directly on the file referenced. Symbolic links are also + referred to as <quote>soft links.</quote> A hard link is something that MS Windows is not familiar with. It allows + one physical file to be known simultaneously by more than one file name. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + There are many other subtle differences that may cause the MS Windows administrator some temporary discomfort + in the process of becoming familiar with UNIX/Linux. These are best left for a text that is dedicated to the + purpose of UNIX/Linux training and education. + </para> + + </sect2> + + <sect2> + <title>Managing Directories</title> + + <para> + There are three basic operations for managing directories: <command>create, delete, rename</command>. + <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> + + <sect2> + <title>File and Directory Access Control</title> + + + <para> + <indexterm><primary>ACLs</primary><secondary>File System</secondary></indexterm> + The network administrator is strongly advised to read foundational training manuals and reference materials + regarding file and directory permissions maintenance. Much can be achieved with the basic UNIX permissions + without having to resort to more complex facilities like POSIX Access Control Lists (ACLs) or Extended + Attributes (EAs). + </para> + + <para> + UNIX/Linux file and directory access permissions involves setting three primary sets of data and one control set. + A UNIX file listing looks as follows: +<screen> +&prompt;<userinput>ls -la</userinput> +total 632 +drwxr-xr-x 13 maryo gnomes 816 2003-05-12 22:56 . +drwxrwxr-x 37 maryo gnomes 3800 2003-05-12 22:29 .. +dr-xr-xr-x 2 maryo gnomes 48 2003-05-12 22:29 muchado02 +drwxrwxrwx 2 maryo gnomes 48 2003-05-12 22:29 muchado03 +drw-rw-rw- 2 maryo gnomes 48 2003-05-12 22:29 muchado04 +d-w--w--w- 2 maryo gnomes 48 2003-05-12 22:29 muchado05 +dr--r--r-- 2 maryo gnomes 48 2003-05-12 22:29 muchado06 +drwsrwsrwx 2 maryo gnomes 48 2003-05-12 22:29 muchado08 +---------- 1 maryo gnomes 1242 2003-05-12 22:31 mydata00.lst +--w--w--w- 1 maryo gnomes 7754 2003-05-12 22:33 mydata02.lst +-r--r--r-- 1 maryo gnomes 21017 2003-05-12 22:32 mydata04.lst +-rw-rw-rw- 1 maryo gnomes 41105 2003-05-12 22:32 mydata06.lst +&prompt; +</screen> + </para> + + <para> + The columns above represent (from left to right): permissions, number of hard links to file, owner, group, size (bytes), access date, time of last modification, and file name. + </para> + + <para> + An overview of the permissions field can be found in <link linkend="access1">Overview of UNIX permissions field</link>. + </para> + + <image id="access1"><imagedescription>Overview of UNIX permissions field.</imagedescription> + <imagefile scale="40">access1</imagefile></image> + + <para> + Any bit flag may be unset. An unset bit flag is the equivalent of <quote>cannot</quote> and is represented + as a <quote>-</quote> character. + + <example> + <title>Example File</title> + <programlisting> + -rwxr-x--- Means: The owner (user) can read, write, execute + the group can read and execute + everyone else cannot do anything with it. + </programlisting> + </example> + + </para> + + <para> + Additional possibilities in the [type] field are: c = character device, b = block device, p = pipe device, s = UNIX Domain Socket. + </para> + + <para> + The letters <constant>rwxXst</constant> set permissions for the user, group and others as: read (r), write (w), + execute (or access for directories) (x), execute only if the file is a directory or already has execute + permission for some user (X), set user or group ID on execution (s), sticky (t). + </para> + + <para> + When the sticky bit is set on a directory, files in that directory may be unlinked (deleted) or renamed only by root or their owner. + Without the sticky bit, anyone able to write to the directory can delete or rename files. The sticky bit is commonly found on + directories, such as <filename>/tmp</filename>, that are world-writable. + </para> + + <para> + When the set user or group ID bit (s) is set on a directory, then all files created within it will be owned by the user and/or + group whose `set user or group' bit is set. This can be helpful in setting up directories for which it is desired that + all users who are in a group should be able to write to and read from a file, particularly when it is undesirable for that file + to be exclusively owned by a user whose primary group is not the group that all such users belong to. + </para> + + <para> + When a directory is set <constant>d-wx--x---</constant> this means that the owner can read and create (write) files in it, but because + the (r) read flags are not set, files cannot be listed (seen) in the directory by anyone. The group can read files in the + directory but cannot create new files. 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. + </para> + + <sect3> + <title>Protecting Directories and Files from Deletion</title> + + <para> + People have asked on the Samba mailing list how is it possible to protect files or directories from deletion by users. + For example, Windows NT/2K/XP provides the capacity to set access controls on a directory into which people can + write files but not delete them. It is possible to set an ACL on a Windows file that permits the file to be written to + but not deleted. Such concepts are foreign to the UNIX operating system file space. Within the UNIX file system + anyone who has the ability to create a file can write to it, and has the capability to delete it. + </para> + + <para> + For the record, in the UNIX environment the ability to delete a file is controlled by the permissions on + the directory that the file is in. In other words, a user can delete a file in a directory to which that + user had write access, even if that user does not own the file. + </para> + + <para> + Of necessity, Samba is subject to the file system semantics of the host operating system. Samba is therefore + limited in the file system capabilities that can be made available through Windows ACLs, and therefore performs + a <quote>best fit</quote> translation to POSIX ACLs. Some UNIX file systems do however support a feature known + as extended attributes. Only the Windows concept of <quote>inheritance</quote> is implemented by Samba through + the appropriate extended attribute. + </para> + + <para> + The specific semantics of the extended attributes are not consistent across UNIX and UNIX-like systems such as Linux. + For example, it is possible on some implementations of the extended attributes to set a flag that prevents the directory + or file from being deleted. The extended attribute that may achieve this is called the <constant>immutible</constant> bit. + Unfortunately, the implementation of the immutible flag is NOT consistent with published documentation. For example, the + man page for the <command>chattr</command> on SUSE Linux 9.2 says: +<screen> +A file with the i attribute cannot be modified: it cannot be deleted +or renamed, no link can be created to this file and no data can be +written to the file. Only the superuser or a process possessing the +CAP_LINUX_IMMUTABLE capability can set or clear this attribute. +</screen> + A simple test can be done to check if the immutible flag is supported on files in the file system of the Samba host + server. + </para> + +<procedure> + <step><para> + Create a file called <filename>filename</filename> + </para></step> + + <step><para> + Login as the <constant>root</constant> user, then set the immutibile flag on a test file as follows: +<screen> +&rootprompt; chatter +i 'filename' +</screen> + </para></step> + + <step><para> + Login as the user who owns the file (not root) attempt to remove the file as follows: +<screen> +mystic:/home/hannibal > rm filename +</screen> + It will not be possible to delete the file if the immutible flag is correctly honored. + </para></step> +</procedure> + + <para> + On those systems and file system types that support the immutible bit it is possible to create directories + that can not be deleted. Check the man page on your particular host system to determine whether or not + immutable directories are writable. If they are not, then the entire directory and its contents will effectively + by protected from writing (file creation also) and deletion. + </para> + + </sect3> + + </sect2> + +</sect1> + +<sect1> +<title>Share Definition Access Controls</title> + + +<para> +<indexterm><primary>permissions</primary><secondary>share</secondary></indexterm> +The following parameters in the &smb.conf; file sections define a share control or effect access controls. +Before using any of the following options, please refer to the man page for &smb.conf;. +</para> + + <sect2> + <title>User and Group-Based Controls</title> + + <para> + User and group-based controls can prove quite useful. In some situations it is distinctly desirable to affect all + file system operations as if a single user were doing so. The use of the <smbconfoption name="force user"/> and + <smbconfoption name="force group"/> behavior will achieve this. In other situations it may be necessary to effect a + paranoia level of control to ensure that only particular authorized persons will be able to access a share or + its contents. Here the use of the <smbconfoption name="valid users"/> or the + <smbconfoption name="invalid users"/> 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, when you leave the scene someone else will need to provide assistance and + if he finds too great a mess or does not understand what you have done, there is risk of + Samba being removed and an alternative solution being adopted. + </para> + + <para> + <link linkend="ugbc">Following table</link> enumerates these controls. + </para> + + <table frame='all' pgwide='0' id="ugbc"><title>User and Group Based Controls</title> + <tgroup cols='2'> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row> + <entry align="center">Control Parameter</entry> + <entry align="center">Description - Action - Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry><smbconfoption name="admin users"/></entry> + <entry><para> + List of users who will be granted administrative privileges on the share. + They will do all file operations as the super-user (root). + Any user in this list will be able to do anything they like on the share, + irrespective of file permissions. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force group"/></entry> + <entry><para> + Specifies a UNIX group name that will be assigned as the default primary group + for all users connecting to this service. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force user"/></entry> + <entry><para> + Specifies a UNIX user name that will be assigned as the default user for all users connecting to this service. + This is useful for sharing files. Incorrect use can cause security problems. + </para></entry> + </row> + <row> + <entry><smbconfoption name="guest ok"/></entry> + <entry><para> + If this parameter is set for a service, then no password is required to connect to the service. Privileges will be + those of the guest account. + </para></entry> + </row> + <row> + <entry><smbconfoption name="invalid users"/></entry> + <entry><para> + List of users that should not be allowed to login to this service. + </para></entry> + </row> + <row> + <entry><smbconfoption name="only user"/></entry> + <entry><para> + Controls whether connections with usernames not in the user list will be allowed. + </para></entry> + </row> + <row> + <entry><smbconfoption name="read list"/></entry> + <entry><para> + List of users that are given read-only access to a service. Users in this list + will not be given write access, no matter what the read only option is set to. + </para></entry> + </row> + <row> + <entry><smbconfoption name="username"/></entry> + <entry><para> + Refer to the &smb.conf; man page for more information -- this is a complex and potentially misused parameter. + </para></entry> + </row> + <row> + <entry><smbconfoption name="valid users"/></entry> + <entry><para> + List of users that should be allowed to login to this service. + </para></entry> + </row> + <row> + <entry><smbconfoption name="write list"/></entry> + <entry><para> + List of users that are given read-write access to a service. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>File and Directory Permissions-Based Controls</title> + + <para> + The following file and directory permission-based controls, if misused, can result in considerable difficulty to + diagnose causes of misconfiguration. Use them sparingly and carefully. By gradually introducing each one by one, + undesirable side effects may be detected. In the event of a problem, always comment all of them out and then gradually + reintroduce them in a controlled way. + </para> + + <para> + Refer to <link linkend="fdpbc">the following table</link> for information regarding the parameters that may be used to affect file and + directory permission-based access controls. + </para> + + <table frame='all' id="fdpbc"><title>File and Directory Permission Based Controls</title> + <tgroup cols='2'> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row> + <entry align="center">Control Parameter</entry> + <entry align="center">Description - Action - Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry><smbconfoption name="create mask"/></entry> + <entry><para> + Refer to the &smb.conf; man page. + </para></entry> + </row> + <row> + <entry><smbconfoption name="directory mask"/></entry> + <entry><para> + The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories. + See also: directory security mask. + </para></entry></row> + <row> + <entry><smbconfoption name="dos filemode"/></entry> + <entry><para> + Enabling this parameter allows a user who has write access to the file to modify the permissions on it. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force create mode"/></entry> + <entry><para> + This parameter specifies a set of UNIX mode bit permissions that will always be set on a file created by Samba. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force directory mode"/></entry> + <entry><para> + This parameter specifies a set of UNIX mode bit permissions that will always be set on a directory created by Samba. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force directory security mode"/></entry> + <entry><para> + Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory. + </para></entry> + </row> + <row> + <entry><smbconfoption name="force security mode"/></entry> + <entry><para> + Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions. + </para></entry> + </row> + <row> + <entry><smbconfoption name="hide unreadable"/></entry> + <entry><para> + Prevents clients from seeing the existence of files that cannot be read. + </para></entry> + </row> + <row> + <entry><smbconfoption name="hide unwriteable files"/></entry> + <entry><para> + Prevents clients from seeing the existence of files that cannot be written to. Unwriteable directories are shown as usual. + </para></entry> + </row> + <row> + <entry><smbconfoption name="nt acl support"/></entry> + <entry><para> + This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists. + </para></entry> + </row> + <row> + <entry><smbconfoption name="security mask"/></entry> + <entry><para> + Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>Miscellaneous Controls</title> + + <para> + The following are documented because of the prevalence of administrators creating inadvertent barriers to file + access by not understanding the full implications of &smb.conf; file settings. See <link linkend="mcoc">following table</link>. + </para> + + <table frame='all' id="mcoc"><title>Other Controls</title> + <tgroup cols='2'> + <colspec align="justify" colwidth="1*"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row> + <entry align="center">Control Parameter</entry> + <entry align="center">Description - Action - Notes</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <smbconfoption name="case sensitive"/>, + <smbconfoption name="default case"/>, + <smbconfoption name="short preserve case"/> + </entry> + <entry><para> + This means that all file name lookup will be done in a case sensitive manner. + Files will be created with the precise file name Samba received from the MS Windows client. + </para></entry> + </row> + <row> + <entry><smbconfoption name="csc policy"/></entry> + <entry><para> + Client Side Caching Policy - parallels MS Windows client side file caching capabilities. + </para></entry> + </row> + <row> + <entry><smbconfoption name="dont descend"/></entry> + <entry><para> + Allows specifying a comma-delimited list of directories that the server should always show as empty. + </para></entry> + </row> + <row> + <entry><smbconfoption name="dos filetime resolution"/></entry> + <entry><para> + This option is mainly used as a compatibility option for Visual C++ when used against Samba shares. + </para></entry> + </row> + <row> + <entry><smbconfoption name="dos filetimes"/></entry> + <entry><para> + DOS and Windows allow users to change file time stamps if they can write to the file. POSIX semantics prevent this. + This option allows DOS and Windows behavior. + </para></entry> + </row> + <row> + <entry><smbconfoption name="fake oplocks"/></entry> + <entry><para> + Oplocks are the way that SMB clients get permission from a server to locally cache file operations. If a server grants an + oplock, the client is free to assume that it is the only one accessing the file and it will aggressively cache file data. + </para></entry> + </row> + <row> + <entry> + <smbconfoption name="hide dot files"/>, + <smbconfoption name="hide files"/>, + <smbconfoption name="veto files"/> + </entry> + <entry><para> + Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible. + </para></entry> + </row> + <row> + <entry><smbconfoption name="read only"/></entry> + <entry><para> + If this parameter is yes, then users of a service may not create or modify files in the service's directory. + </para></entry> + </row> + <row> + <entry><smbconfoption name="veto files"/></entry> + <entry><para> + List of files and directories that are neither visible nor accessible. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + +</sect1> + +<sect1> +<title>Access Controls on Shares</title> + + + <para> +<indexterm><primary>permissions</primary><secondary>share ACLs</secondary></indexterm> + This section deals with how to configure Samba per share access control restrictions. + By default, Samba sets no restrictions on the share itself. Restrictions on the share itself + can be set on MS Windows NT4/200x/XP shares. This can be an 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 <constant>Everyone - Full Control</constant> (full control, change and read). + </para> + + <para> + At this time Samba does not provide a tool for configuring access control setting on the share + itself. Samba does have the capacity to store and act on access control settings, but the only + way to create those settings is to use either the NT4 Server Manager or the Windows 200x MMC for + Computer Management. + </para> + + <para> + Samba stores the per share access control settings in a file called <filename>share_info.tdb</filename>. + The location of this file on your system will depend on how Samba was compiled. The default location + for Samba's tdb files is under <filename>/usr/local/samba/var</filename>. If the <filename>tdbdump</filename> + utility has been compiled and installed on your system, then you can examine the contents of this file + by executing: <command>tdbdump share_info.tdb</command> in the directory containing the tdb files. + </para> + + <sect2> + <title>Share Permissions Management</title> + + <para> + The best tool for the task is platform dependant. Choose the best tool for your environment. + </para> + + <sect3> + <title>Windows NT4 Workstation/Server</title> + <para> + The tool you need to use to manage share permissions on a Samba server is the NT Server Manager. + Server Manager is shipped with Windows NT4 Server products but not with Windows NT4 Workstation. + You can obtain the NT Server Manager for MS Windows NT4 Workstation from Microsoft &smbmdash; see details below. + </para> + + <procedure> + <title>Instructions</title> + <step><para> + Launch the <application>NT4 Server Manager</application>, click on the Samba server you want to administer. From the menu + select <guimenu>Computer</guimenu>, then click on <guimenuitem>Shared Directories</guimenuitem>. + </para></step> + + <step><para> + Click on the share that you wish to manage, then click the <guilabel>Properties</guilabel> tab. then click + the <guilabel>Permissions</guilabel> tab. Now you can add or change access control settings as you wish. + </para></step> + </procedure> + + </sect3> + + <sect3> + <title>Windows 200x/XP</title> + + <para> + On <application>MS Windows NT4/200x/XP</application> system access control lists on the share itself are set using native + tools, usually from File Manager. For example, in Windows 200x, right click on the shared folder, + then select <guimenuitem>Sharing</guimenuitem>, then click on <guilabel>Permissions</guilabel>. The default + Windows NT4/200x permission allows <quote>Everyone</quote> full control on the share. + </para> + + <para> + MS Windows 200x and later versions come with a tool called the <application>Computer Management</application> snap-in for the + Microsoft Management Console (MMC). This tool is located by clicking on <guimenu>Control Panel -> + Administrative Tools -> Computer Management</guimenu>. + </para> + + <procedure> + <title>Instructions</title> + <step><para> + After launching the MMC with the Computer Management snap-in, click the menu item <guimenuitem>Action</guimenuitem>, + and 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 are already logged in with administrative privilege, this step is not offered. + </para></step> + + <step><para> + If the Samba server is not shown in the <guilabel>Select Computer</guilabel> box, type in the name of the target + Samba server in the field <guilabel>Name:</guilabel>. Now click the on <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> + In the right panel, double-click on the share on which you wish to set access control permissions. + Then click the tab <guilabel>Share Permissions</guilabel>. It is now possible to add access control entities + to the shared folder. Remember to set what type of access (full control, change, read) you + wish to assign for each entry. + </para></step> + </procedure> + + <warning> + <para> + Be careful. If you take away all permissions from the <constant>Everyone</constant> user without removing this user, + effectively no user will be able to access the share. This is a result of what is known as + ACL precedence. Everyone with <emphasis>no access</emphasis> means that <constant>MaryK</constant> who is part of the group + <constant>Everyone</constant> will have no access even if she is given explicit full control access. + </para> + </warning> + + </sect3> + </sect2> + +</sect1> + +<sect1> +<title>MS Windows Access Control Lists and UNIX Interoperability</title> + + <sect2> + <title>Managing UNIX Permissions Using NT Security Dialogs</title> + + + <para> +<indexterm><primary>permissions</primary><secondary>file/directory ACLs</secondary></indexterm> + Windows NT clients can use their native security settings dialog box to view and modify the + underlying UNIX permissions. + </para> + + <para> + This ability is careful not to compromise the security of the UNIX host on which Samba is running, and + still obeys all the file permission rules that a Samba administrator can set. + </para> + + <para> + Samba does not attempt to go beyond POSIX ACLs, so the various finer-grained access control + options provided in Windows are actually ignored. + </para> + + <note> + <para> + All access to UNIX/Linux system files via Samba is controlled by the operating system file access controls. + When trying to figure out file access problems, it is vitally important to find the identity of the Windows + user as it is presented by Samba at the point of file access. This can best be determined from the + Samba log files. + </para> + </note> + </sect2> + + <sect2> + <title>Viewing File Security on a Samba Share</title> + + <para> + From an NT4/2000/XP client, right click on any file or directory in a Samba-mounted drive letter + or UNC path. When the menu pops up, click on the <guilabel>Properties</guilabel> entry at the bottom + of the menu. This brings up the file <constant>Properties</constant> dialog box. Click on the + <guilabel>Security</guilabel> tab 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 <guibutton>Add</guibutton> + button, will not currently allow a list of users to be seen. + </para> + + </sect2> + + <sect2> + <title>Viewing File Ownership</title> + + <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 displayed like this: + </para> + + <para> + <constant>SERVER\user (Long name)</constant> + </para> + + <para> + <replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server, <replaceable>user</replaceable> + is the user name of the UNIX user who owns the file, and <replaceable>(Long name)</replaceable> is the + descriptive string identifying the user (normally found in the GECOS field of the UNIX password database). + Click on the <guibutton>Close </guibutton> button to remove this dialog. + </para> + + <para> + If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>, + the file owner will be shown as the NT user <emphasis>Everyone</emphasis>. + </para> + + <para> + The <guibutton>Take Ownership</guibutton> button will not allow you to change the ownership of this file to + yourself (clicking it will display a dialog box complaining that the user you are currently logged onto + the NT client cannot be found). The reason for this is that changing the ownership of a file is a privileged + operation in UNIX, available only to the <emphasis>root</emphasis> user. As clicking on this button causes + NT to attempt to change the ownership of a file to the current user logged into the NT client, this will + not work with Samba at this time.</para> + + <para> + There is an NT <command>chown</command> command that will work with Samba and allow a user with Administrator privilege connected + to a Samba server as root to change the ownership of files on both a local NTFS filesystem or remote mounted NTFS + or Samba drive. This is available as part of the <application>Seclib</application> NT security library written + by Jeremy Allison of the Samba Team, and is available from the main Samba FTP site.</para> + + </sect2> + + <sect2> + <title>Viewing File or Directory Permissions</title> + + <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 like this: + </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 the UNIX user who owns the file, and + <replaceable>(Long name)</replaceable> is the descriptive string identifying the user (normally found in the + GECOS field of the UNIX password database).</para> + + <para> + If the parameter <smbconfoption name="nt acl support"/> is set to <constant>false</constant>, + the file owner will be shown as the NT user <constant>Everyone</constant> and the permissions will be + shown as NT <quote>Full Control</quote>. + </para> + + + <para> + The permissions field is displayed differently for files and directories, both are discussed here: + </para> + + <sect3> + <title>File Permissions</title> + + <para>The standard UNIX user/group/world triplet and the corresponding <constant>read, write, execute</constant> permissions + triplets are mapped by Samba into a three element NT ACL with the <quote>r</quote>, <quote>w</quote> and <quote>x</quote> bits mapped into the corresponding + NT permissions. The UNIX world permissions are mapped into the global NT group <constant>Everyone</constant>, followed + by the list of permissions allowed for the UNIX world. The UNIX owner and group permissions are displayed as an NT + <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>Because many UNIX permission sets do not map into common NT names such as <constant>read</constant>, + <constant>change</constant> or <constant>full control</constant>, 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 + to allow <quote>no permissions</quote> to be seen and modified Samba then overloads the NT <constant>Take Ownership</constant> ACL attribute + (which has no meaning in UNIX) and reports a component with no permissions as having the NT <command>O</command> bit set. + This was chosen, of course, to make it look like a zero, meaning zero permissions. More details on the decision behind this is + given below.</para> + </sect3> + + <sect3> + <title>Directory Permissions</title> + + <para>Directories on an NT NTFS file system have two different sets of permissions. The first set is the ACL set on the + directory itself, which is usually displayed 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 <constant> + inherited</constant> permissions that any file created within this directory would inherit.</para> + + <para>Samba synthesizes these inherited permissions for NT by returning as an NT ACL the UNIX permission mode that a new file + created by Samba on this share would receive.</para> + </sect3> + </sect2> + + <sect2> + <title>Modifying File or Directory Permissions</title> + + <para>Modifying file and directory permissions is as simple + as changing the displayed permissions in the dialog box, and + clicking on <guibutton>OK</guibutton>. 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 <smbconfoption name="nt acl support"/> + is set to <constant>false</constant>, any attempt to set + security permissions will fail with an <errorname>`Access Denied' + </errorname> message.</para> + + <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 saying <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 triplet (either user, group, or world) + is removed from the list of permissions in the NT dialog box, + then when the <guibutton>OK</guibutton> button is pressed it will + be applied as <quote>no permissions</quote> on the UNIX side. If you then + view the permissions again, the <quote>no permissions</quote> entry will appear + as the NT <command>O</command> flag, as described above. This + allows you to add permissions back to a file or directory once + you have removed them from a triplet component.</para> + + <para>As UNIX supports only the <quote>r</quote>, <quote>w</quote> and <quote>x</quote> bits of + an NT ACL, if other NT security attributes such as <constant>Delete Access</constant> are + selected they will be ignored when applied on the Samba server.</para> + + <para>When setting permissions on a directory, the second + set of permissions (in the second set of parentheses) is + by default applied to all files within that directory. If this + is not what you want, you must un-check the <guilabel>Replace + permissions on existing files</guilabel> check-box in the NT + dialog before clicking on <guibutton>OK</guibutton>.</para> + + <para>If you wish to remove all permissions from a + user/group/world component, you may either highlight the + component and click on 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> + + <sect2> + <title>Interaction with the Standard Samba <quote>create mask</quote> Parameters</title> + + <para>There are four parameters that control interaction with the standard Samba <parameter>create mask</parameter> parameters. + These are: + + <itemizedlist> + <listitem><para><smbconfoption name="security mask"/></para></listitem> + <listitem><para><smbconfoption name="force security mode"/></para></listitem> + <listitem><para><smbconfoption name="directory security mask"/></para></listitem> + <listitem><para><smbconfoption name="force directory security mode"/></para></listitem> + </itemizedlist> + + </para> + + <para>When a user clicks on <guibutton>OK</guibutton> to apply the + permissions, Samba maps the given permissions into a user/group/world + r/w/x triplet set, and then checks the changed permissions for a + file against the bits set in the + <smbconfoption name="security mask"/> parameter. Any bits that + were changed that are not set to <quote>1</quote> in this parameter are left alone + in the file permissions.</para> + + <para>Essentially, zero bits in the <smbconfoption name="security mask"/> + may be treated as a set of bits the user is <emphasis>not</emphasis> + allowed to change, and one bits are those the user is allowed to change. + </para> + + <para>If not explicitly set, this parameter defaults to the same value as + the <smbconfoption name="create mask"/> parameter. To allow a user to modify all the + user/group/world permissions on a file, set this parameter to 0777. + </para> + + <para>Next Samba checks the changed permissions for a file against the bits set in the + <smbconfoption name="force security mode"/> parameter. Any bits + that were changed that correspond to bits set to <quote>1</quote> in this parameter + are forced to be set.</para> + + <para>Essentially, bits set in the <parameter>force security mode</parameter> parameter + may be treated as a set of bits that, when modifying security on a file, the user has always set to be <quote>on</quote>.</para> + + <para>If not explicitly set, this parameter defaults to the same value + as the <smbconfoption name="force create mode"/> parameter. + To allow a user to modify all the user/group/world permissions on a file + with no restrictions set this parameter to 000. The + <smbconfoption name="security mask"/> and <parameter>force + security mode</parameter> parameters are applied to the change + request in that order.</para> + + <para>For a directory, Samba will perform the same operations as + described above for a file except it uses the parameter <parameter> + directory security mask</parameter> instead of <parameter>security + mask</parameter>, and <parameter>force directory security mode + </parameter> parameter instead of <parameter>force security mode + </parameter>.</para> + + <para>The <smbconfoption name="directory security mask"/> parameter + by default is set to the same value as the <parameter>directory mask + </parameter> parameter and the <parameter>force directory security + mode</parameter> parameter by default is set to the same value as + the <smbconfoption name="force directory mode"/> parameter. + In this way Samba enforces the permission restrictions that + an administrator can set on a Samba share, while still allowing users + to modify the permission bits within that restriction.</para> + + <para>If you want to set up a share that allows users full control + in modifying the permission bits on their files and directories and + does not force any particular bits to be set <quote>on</quote>, then set the following + parameters in the &smb.conf; file in that share-specific section: + </para> + + <smbconfblock> + <smbconfoption name="security mask">0777</smbconfoption> + <smbconfoption name="force security mode">0</smbconfoption> + <smbconfoption name="directory security mask">0777</smbconfoption> + <smbconfoption name="force directory security mode">0</smbconfoption> + </smbconfblock> + </sect2> + + <sect2> + <title>Interaction with the Standard Samba File Attribute Mapping</title> + + <note> + <para>Samba maps some of the DOS attribute bits (such as <quote>read + only</quote>) into the UNIX permissions of a file. This means there can + be a conflict between the permission bits set via the security + dialog and the permission bits set by the file attribute mapping. + </para> + </note> + + <para>If a file has no UNIX read access for the owner, it will show up + as <quote>read only</quote> in the standard file attributes tabbed dialog. + Unfortunately, this dialog is the same one that contains the security information + in another tab.</para> + + <para>What this can mean is that if the owner changes the permissions + to allow himself read access using the security dialog, clicks on + <guibutton>OK</guibutton> to get back to the standard attributes tab + dialog, and clicks on <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 on <guibutton>OK</guibutton> to get back to the + attributes dialog, you should always press <guibutton>Cancel</guibutton> + rather than <guibutton>OK</guibutton> to ensure that your changes + are not overridden.</para> + </sect2> + + <sect2> + <title>Windows NT/200X ACLS and POSIX ACLS &smbmdash; Limitations</title> + + <para> + Windows administrators are familiar with simple ACL controls and they typically + consider that UNIX user/group/other (ugo) permissions are inadequate and not + sufficiently fine-grained. + </para> + + <para> + Competing SMB implementations differ in how they handle Windows ACLs. Samba handles + Windows ACLs from the perspective of UNIX file system adminsitration and thus adopts + the limitations of POSIX ACLs. Therefore, where POSIX ACLs lack a capability of the + Windows NT/200X ACLs, the POSIX semantics and limitations are imposed on the Windows + administrator. + </para> + + <para> + POSIX ACLs present an interesting challenge to the UNIX adminsitrator and therfore a + force a compromise to be applied to Windows ACLs administration. POSIX ACLs are not + covered by an official standard, rather the latest standard is a draft standard + 1003.1e revision 17. This is the POSIX document on which the Samba implementation has + been implemented. + </para> + + <para> + UNIX vendors differ in the manner in which POSIX ACLs are implemented. There are a + number of Linux file systems that support ACLs. Samba has to provide a way to make + transparent all the differences between the various implementations of POSIX ACLs. + The pressure for ACLs support in Samba has noticibly increased the pressure to + standardize ACLs support in the UNIX world. + </para> + + <para> + Samba has to deal with the complicated matter of handling the challenge of the Windows + ACL that implements <emphasis>inheritance</emphasis>, a concept not anticipated by POSIX + ACLs as implemented in UNIX file systems. Samba provides support for <emphasis>masks</emphasis> + that permit normal ugo and ACLs functionality to be overrided. This further complicates + the way in which Windows ACLs must be implemented. + </para> + + <sect3> + <title>UNIX POSIX ACL Overview</title> + + <para> + In examining POSIX ACLs we must consider the manner in which they operate for + both files and directories. File ACLs have the following significance: +<screen> +# file: testfile <- the file name +# owner: jeremy <-- the file owner +# group: users <-- the POSIX group owner +user::rwx <-- perms for the file owner (user) +user:tpot:r-x <-- perms for the additional user 'tpot' +group::r-- <-- perms for the file group owner (group) +group:engrs:r-- <-- perms for the additonal group 'engineers' +mask:rwx <-- the mask that is 'ANDed' with groups +other::--- <-- perms applied to everyone else (other) +</screen> + Directory ACLs have the following signficance: +<screen> +# file: testdir <-- the directory name +# owner: jeremy <-- the directory owner +# group: jeremy <-- the POSIX group owner +user::rwx <-- directory perms for owner (user) +group::rwx <-- directory perms for owning group (group) +mask::rwx <-- the mask that is 'ANDed' with group perms +other:r-x <-- perms applied to everyone else (other) +default:user::rwx <-- inherited owner perms +default:user:tpot:rwx <-- inherited extra perms for user 'tpot' +default:group::r-x <-- inherited group perms +default:mask:rwx <-- inherited default mask +default:other:--- <-- inherited permissions for everyone (other) +</screen> + </para> + + </sect3> + + <sect3> + <title>Mapping of Windows File ACLs to UNIX POSIX ACLs</title> + + <para> + Microsoft Windows NT4/200X ACLs must of necessity be mapped to POSIX ACLs. + The mappings for file permissions are shown in <link linkend="fdsacls"/>. + The '#' character means this flag is set only when the Windows administrator + sets the <constant>Full Control</constant> flag on the file. + </para> + + <table frame='all' pgwide='0' id="fdsacls"><title>How Windows File ACLs Map to UNIX POSIX File ACLs</title> + <tgroup cols='2'> + <colspec align="left"/> + <colspec align="center"/> + <thead> + <row> + <entry align="left">Windows ACE</entry> + <entry align="center">File Attribute Flag</entry> + </row> + </thead> + <tbody> + <row> + <entry><para>Full Control</para></entry> + <entry><para>#</para></entry> + </row> + <row> + <entry><para>Traverse Folder / Execute File</para></entry> + <entry><para>x</para></entry> + </row> + <row> + <entry><para>List Folder / Read Data</para></entry> + <entry><para>r</para></entry> + </row> + <row> + <entry><para>Read Attributes</para></entry> + <entry><para>r</para></entry> + </row> + <row> + <entry><para>Read Extended Attribures</para></entry> + <entry><para>r</para></entry> + </row> + <row> + <entry><para>Create Files / Write Data</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Create Folders / Append Data</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Write Attributes</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Write Extended Attributes</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Delete Subfolders and Files</para></entry> + <entry><para>w</para></entry> + </row> + <row> + <entry><para>Delete</para></entry> + <entry><para>#</para></entry> + </row> + <row> + <entry><para>Read Permissions</para></entry> + <entry><para>all</para></entry> + </row> + <row> + <entry><para>Change Permissions</para></entry> + <entry><para>#</para></entry> + </row> + <row> + <entry><para>Take Ownership</para></entry> + <entry><para>#</para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + As can be seen from the mapping table, there is no 1:1 mapping capability and therefore + Samba must make a logical mapping that will permit Windows to operate more-or-less the way + that is intended by the Administrator. + </para> + + <para> + In general the mapping of UNIX POSIX user/group/other permissions will be mapped to + Windows ALCs. This has precidence over the creation of POSIX ACLs. POSIX ACLs are necessary + to establish access controls for users and groups other than the user and group that + own the file or directory. + </para> + + <para> + The UNIX administrator can set any directory permission from within the UNIX environment. + The Windows administrator is more restricted in that it is not possible from within the + Windows Explorer to remove read permission for the file owner. + </para> + + </sect3> + + <sect3> + <title>Mapping of Windows Directory ACLs to UNIX POSIX ACLs</title> + + <para> + Interesting things happen in the mapping of UNIX POSIX directory permissions as well + as UNIX POSIX ACLs to Windows ACEs (Access Control Entries, the discrete component of + an Access Control List (ACL), are mapped to Windows directory ACLs. + </para> + + <para> + Directory permissions function in much the same way as shown for file permissions, but + there are some notable exceptions and a few peculiarities that the astute administrator + will want to take into account in the setting up of directory permissions. + </para> + + </sect3> + + </sect2> +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +File, directory and share access problems are common on the mailing list. The following +are examples taken from the mailing list in recent times. +</para> + + + <sect2> + <title>Users Cannot 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 there's 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 the server to + <userinput>chgrp -R users *</userinput> and <userinput>chown -R nobody *</userinput> to allow others users to change the file. + </quote> + </para> + + <para> + There are many ways to solve this problem and here are a few hints: + </para> + + <procedure> + <step> + <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 +<screen> +&prompt;find 'directory_name' -type d -exec chown user.group {}\; +&prompt;find 'directory_name' -type d -exec chmod 1775 'directory_name' +&prompt;find 'directory_name' -type f -exec chmod 0775 {} \; +&prompt;find 'directory_name' -type f -exec chown user.group {}\; +</screen> + </para> + + <note><para> + The above will set the <constant>sticky bit</constant> 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> + + Directory is: <replaceable>/foodbar</replaceable> +<screen> +&prompt;<userinput>chown jack.engr /foodbar</userinput> +</screen> + </para> + + <note> + <para>This is the same as doing:</para> +<screen> +&prompt;<userinput>chown jack /foodbar</userinput> +&prompt;<userinput>chgrp engr /foodbar</userinput> +</screen> + </note> + </step> + <step> + <para>Now type: + +<screen> +&prompt;<userinput>chmod 6775 /foodbar</userinput> +&prompt;<userinput>ls -al /foodbar/..</userinput> +</screen> + + </para> + + <para>You should see: +<screen> +drwsrwsr-x 2 jack engr 48 2003-02-04 09:55 foodbar +</screen> + </para> + </step> + <step> + + <para>Now type: +<screen> +&prompt;<userinput>su - jill</userinput> +&prompt;<userinput>cd /foodbar</userinput> +&prompt;<userinput>touch Afile</userinput> +&prompt;<userinput>ls -al</userinput> +</screen> + </para> + + <para> + You should see that the file <filename>Afile</filename> created by Jill will have ownership + and permissions of Jack, as follows: +<screen> +-rw-r--r-- 1 jack engr 0 2003-02-04 09:57 Afile +</screen> + </para> + </step> + + <step> + <para> + Now in your &smb.conf; for the share add: + <smbconfblock> +<smbconfoption name="force create mode">0775</smbconfoption> +<smbconfoption name="force directory mode">6775</smbconfoption> + </smbconfblock> + </para> + + <note><para> + These procedures are needed only if your users are not members of the group + you have used. That is if 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: + <smbconfblock> +<smbconfoption name="force user">jack</smbconfoption> +<smbconfoption name="force group">engr</smbconfoption> + </smbconfblock> + </para> + </step> + </procedure> + </sect2> + + + <sect2> + <title>File Operations Done as <emphasis>root</emphasis> with <emphasis>force user</emphasis> Set</title> + + <para> + When you have a user in <smbconfoption name="admin users"/>, Samba will always do file operations for + this user as <emphasis>root</emphasis>, even if <smbconfoption name="force user"/> has been set. + </para> + </sect2> + + <sect2> + <title>MS Word with Samba Changes Owner of File</title> + + <para> + <emphasis>Question:</emphasis> <quote>When user B saves a word document that is owned by user A the updated file is now owned by user B. + Why is Samba doing this? How do I fix this?</quote> + </para> + + <para> + <emphasis>Answer:</emphasis> Word does the following when you modify/change a Word document: MS Word creates a NEW document with + a temporary name, Word then closes the old document and deletes it, Word then renames the new document to the original document name. + There is no mechanism by which Samba can in any way know that the new document really should be owned by the owners + of the original file. Samba has no way of knowing that the file will be renamed by MS Word. As far as Samba is able + to tell, the file that gets created is a NEW file, not one that the application (Word) is updating. + </para> + + <para> + There is a work-around to solve the permissions problem. That work-around involves understanding how you can manage file + system behavior from within the &smb.conf; file, as well as understanding how UNIX file systems work. Set on the directory + in which you are changing Word documents: <command>chmod g+s `directory_name'</command> This ensures that all files will + be created with the group that owns the directory. In &smb.conf; share declaration section set: + </para> + + <para> + <smbconfblock> + <smbconfoption name="force create mode">0660</smbconfoption> + <smbconfoption name="force directory mode">0770</smbconfoption> + </smbconfblock> + </para> + + <para> + These two settings will ensure that all directories and files that get created in the share will be read/writable by the + owner and group set on the directory itself. + </para> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml b/docs/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml new file mode 100644 index 0000000000..66b4c27406 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml @@ -0,0 +1,403 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="AdvancedNetworkManagement"> +<chapterinfo> + &author.jht; + <pubdate>April 3 2003</pubdate> +</chapterinfo> + +<title>Advanced Network Management</title> + +<para> +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 make everything work more +harmoniously. A key part of every network environment solution is the +ability to remotely +manage MS Windows workstations, remotely access the Samba server, provide customized +logon scripts, as well as other housekeeping activities that help to sustain more reliable +network operations. +</para> + +<para> +This chapter presents information on each of these areas. They are placed here, and not in +other chapters, for ease of reference. +</para> + +</sect1> + +<sect1> +<title>Remote Server Administration</title> + + +<para><quote>How do I get `User Manager' and `Server Manager'?</quote></para> + +<para> +<indexterm><primary>User Manager</primary></indexterm> +<indexterm><primary>Server Manager</primary></indexterm> +<indexterm><primary>Event Viewer</primary></indexterm> +Since I do not need to buy an <application>NT4 Server</application>, how do I get the `User Manager for Domains' +and the `Server Manager'? +</para> + +<para> +<indexterm><primary>Nexus.exe</primary></indexterm> +Microsoft distributes a version of these tools called <filename>Nexus.exe</filename> 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> + +<para> +Download the archived file at <ulink noescape="1" url="ftp://ftp.microsoft.com/Softlib/MSLFILES/NEXUS.EXE">ftp://ftp.microsoft.com/Softlib/MSLFILES/NEXUS.EXE.</ulink> +</para> + +<para> +<indexterm><primary>SRVTOOLS.EXE</primary></indexterm> +The <application>Windows NT 4.0</application> version of the `User Manager for +Domains' and `Server Manager' are available from Microsoft <ulink url="ftp://ftp.microsoft.com/Softlib/MSLFILES/SRVTOOLS.EXE">via ftp</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 solution 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 NoMachine.Com</title> + + <para> + <indexterm><primary>NoMachine.Com</primary></indexterm> + 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><quote> + I have a wonderful Linux/Samba server running as pdc for a network. Now I would like to add remote + desktop capabilities so users outside could login to the system and get their desktop up from home or + another country. + </quote></para> + + <para><quote> + Is there a way to accomplish this? Do I need a Windows Terminal Server? Do I need to configure it so + 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? + </quote></para> + + <para> + Answer provided: Check out the new offer of <quote>NX</quote> software from + <ulink noescape="1" url="http://www.nomachine.com/">NoMachine</ulink>. + </para> + + <para> + It implements an 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 that makes the thing + fast enough to run even over slow modem/ISDN connections. + </para> + + <para> + I could test drive their (public) Red Hat machine in Italy, over a loaded + Internet connection, with enabled thumbnail previews in KDE konqueror + which popped up immediately on <quote>mouse-over</quote>. 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 + that my score was 631750 points at first try. + </para> + + <para> + NX performs better on my local LAN than any of the other <quote>pure</quote> + 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 <quote>copy'n'paste</quote> 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 test drive NX to anybody with a only a passing interest in remote computing + <ulink noescape="1" 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 Red Hat, + SuSE, Debian and Windows) and be up and running within five 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. You also can run it + full-screen, and after a short time you forget that it is a remote session + at all). + </para> + + <para> + Now the best thing for last: 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 technologies 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 do not need to install a terminal server; XP has RDP support built in. + </para></listitem> + + <listitem><para> + NX is much cheaper than Citrix &smbmdash; and comparable in performance, probably faster. + </para></listitem> + + <listitem><para> + You do not need to hack XP &smbmdash; 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 &smbmdash; + you can now use a (very inconvenient) command-line at no cost, + but you can buy a comfortable (proprietary) NX GUI front end for money. + </para></listitem> + + <listitem><para> + NoMachine are encouraging and offering help to OSS/Free Software implementations + for such a front end 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> + +<para> +There are several opportunities for creating a custom network startup configuration environment. +</para> + +<itemizedlist> + <listitem><para>No Logon Script.</para></listitem> + <listitem><para>Simple universal Logon Script that applies to all users.</para></listitem> + <listitem><para>Use of a conditional Logon Script that applies per user or per group attributes.</para></listitem> + <listitem><para>Use of Samba's preexec and postexec functions on access to the NETLOGON share to create + a custom logon script and then execute it.</para></listitem> + <listitem><para>User of a tool such as KixStart.</para></listitem> +</itemizedlist> + +<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. +</para> + +<para> +The following listings are from the genlogon directory. +</para> + + +<para> +<indexterm><primary>genlogon.pl</primary></indexterm> +This is the <filename>genlogon.pl</filename> file: + +<smbfile name="genlogon.pl"> +<programlisting> + #!/usr/bin/perl + # + # genlogon.pl + # + # Perl script to generate user logon scripts on the fly, when users + # connect from a Windows client. This script should be called from + # smb.conf with the %U, %G and %L parameters. I.e: + # + # root preexec = genlogon.pl %U %G %L + # + # The script generated will perform + # the following: + # + # 1. Log the user connection to /var/log/samba/netlogon.log + # 2. Set the PC's time to the Linux server time (which is maintained + # daily to the National Institute of Standards Atomic clock on the + # internet. + # 3. Connect the user's home drive to H: (H for Home). + # 4. Connect common drives that everyone uses. + # 5. Connect group-specific drives for certain user groups. + # 6. Connect user-specific drives for certain users. + # 7. Connect network printers. + + # Log client connection + #($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); + ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time); + open LOG, ">>/var/log/samba/netlogon.log"; + print LOG "$mon/$mday/$year $hour:$min:$sec"; + print LOG " - User $ARGV[0] logged into $ARGV[1]\n"; + close LOG; + + # Start generating logon script + open LOGON, ">/shared/netlogon/$ARGV[0].bat"; + print LOGON "\@ECHO OFF\r\n"; + + # Connect shares just use by Software Development group + if ($ARGV[1] eq "SOFTDEV" || $ARGV[0] eq "softdev") + { + print LOGON "NET USE M: \\\\$ARGV[2]\\SOURCE\r\n"; + } + + # Connect shares just use by Technical Support staff + if ($ARGV[1] eq "SUPPORT" || $ARGV[0] eq "support") + { + print LOGON "NET USE S: \\\\$ARGV[2]\\SUPPORT\r\n"; + } + + # Connect shares just used by Administration staff + If ($ARGV[1] eq "ADMIN" || $ARGV[0] eq "admin") + { + print LOGON "NET USE L: \\\\$ARGV[2]\\ADMIN\r\n"; + print LOGON "NET USE K: \\\\$ARGV[2]\\MKTING\r\n"; + } + + # Now connect Printers. We handle just two or three users a little + # differently, because they are the exceptions that have desktop + # printers on LPT1: - all other user's go to the LaserJet on the + # server. + if ($ARGV[0] eq 'jim' + || $ARGV[0] eq 'yvonne') + { + print LOGON "NET USE LPT2: \\\\$ARGV[2]\\LJET3\r\n"; + print LOGON "NET USE LPT3: \\\\$ARGV[2]\\FAXQ\r\n"; + } + else + { + print LOGON "NET USE LPT1: \\\\$ARGV[2]\\LJET3\r\n"; + print LOGON "NET USE LPT3: \\\\$ARGV[2]\\FAXQ\r\n"; + } + + # All done! Close the output file. + close LOGON; +</programlisting> +</smbfile> +</para> + +<para> +Those wishing to use more elaborate or capable logon processing system should check out these sites: +</para> + +<itemizedlist> + <listitem><para><ulink noescape="1" url="http://www.craigelachie.org/rhacer/ntlogon">http://www.craigelachie.org/rhacer/ntlogon</ulink></para></listitem> + <listitem><para><ulink noescape="1" url="http://www.kixtart.org">http://www.kixtart.org</ulink></para></listitem> +</itemizedlist> + +<sect2> +<title>Adding Printers without User Intervention</title> + + +<para> +<indexterm><primary>rundll32</primary></indexterm> +Printers may be added automatically during logon script processing through the use of: + +<screen> +&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /?</userinput> +</screen> + +See the documentation in the <ulink url="http://support.microsoft.com/default.asp?scid=kb;en-us;189105">Microsoft knowledgebase article 189105.</ulink> +</para> +</sect2> + +<sect2> + <title>Limiting Logon Connections</title> + + <para> + Sometimes it is necessary to limit the number of concurrent connections to a + Samba shared resource. For example, a site may wish to permit only one network + logon per user. + </para> + + <para> + The Samba <parameter>preexec script</parameter> parameter can be used to permit only one + connection per user. Though this method is not fool-proof, and may have side-effects + the following contributed method may inspire someone to provide a better solution. + </para> + + <para> + This is not a perfect solution because Windows clients can drop idle connections + with an auto-reconnect capability that could result in the appearance that a share + is no longer in use, while actually it is. Even so, it demonstrates the principle + of use of the <parameter>preexec script</parameter> parameter. + </para> + + <para> + The following share configuration demonstrates use of the script shown in <link linkend="Tpees"/>: + <programlisting> +[myshare] + ... + preexec script = /sbin/PermitSingleLogon.sh + preexec close = Yes + ... + </programlisting> + </para> + +<example id="Tpees"> + <title>Script to Enforce Single Resource Logon</title> +<screen> +#!/bin/bash + +IFS="-" +RESULT=$(smbstatus -S -u $1 2> /dev/null | awk 'NF > 6 {print $1}' | sort | uniq -d) + +if [ "X${RESULT}" == X ]; then + exit 0 +else + exit 1 +fi +</screen> +</example> + +</sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-BDC.xml b/docs/Samba3-HOWTO/TOSHARG-BDC.xml new file mode 100644 index 0000000000..7d4ff18dd7 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-BDC.xml @@ -0,0 +1,645 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="samba-bdc"> + +<chapterinfo> + &author.jht; + &author.vl; + <author>&person.gd;<contrib>LDAP updates</contrib></author> +</chapterinfo> + +<title>Backup Domain Control</title> + +<para> +Before you continue reading this section, please make sure that you are comfortable +with configuring a Samba Domain Controller as described in <link linkend="samba-pdc">Domain Control</link>. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +This is one of the most difficult chapters to summarize. It does not matter what we say here +for someone will still draw conclusions and/or approach the Samba Team with expectations +that are either not yet capable of being delivered, or that can be achieved far more +effectively using a totally different approach. In the event that you should have a persistent +concern that is not addressed in this book, please email <ulink url="mailto:jht@samba.org">John H. Terpstra</ulink> +clearly setting out your requirements and/or question and we will do our best to provide a solution. +</para> + +<para> +<indexterm><primary>SAM backend</primary><secondary>LDAP</secondary></indexterm> +Samba-3 is capable of acting as a Backup Domain Controller (BDC) to another Samba Primary Domain +Controller (PDC). A Samba-3 PDC can operate with an LDAP Account backend. The LDAP backend can be +either a common master LDAP server, or a slave server. The use of a slave LDAP server has the +benefit that when the master is down, clients may still be able to log onto the network. +This effectively gives Samba a high degree of scalability and is an effective solution +for large organizations. If you use an LDAP slave server for a PDC, +you will need to ensure the master's continued availability - if the +slave finds it's master down at the wrong time, you will have +stability and operational problems. +</para> + +<para> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> +While it is possible to run a Samba-3 BDC with non-LDAP backend, that +backend must allow some form of 'two way' propagation, of changes +from the BDC to the master. Only LDAP is capable of this at this stage. +</para> + +<para> +<indexterm><primary>SAM backend</primary><secondary>non-LDAP</secondary></indexterm> +The use of a non-LDAP backend SAM database is particularly problematic because Domain Member +servers and workstations periodically change the Machine Trust Account password. The new +password is then stored only locally. This means that in the absence of a centrally stored +accounts database (such as that provided with an LDAP-based solution) if Samba-3 is running +as a BDC, the BDC instance of the Domain Member trust account password will not reach the +PDC (master) copy of the SAM. If the PDC SAM is then replicated to BDCs, this results in +overwriting the SAM that contains the updated (changed) trust account password with resulting +breakage of the domain trust. +</para> + +<para> +Considering the number of comments and questions raised concerning how to configure a BDC, +let's consider each possible option and look at the pros and cons for each possible solution. +<link linkend="pdc-bdc-table">Following table</link> lists possible design configurations for a PDC/BDC infrastructure. +<indexterm><primary>net</primary><secondary>rpc</secondary></indexterm> +<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm> +<indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> +</para> + +<table frame="all" id="pdc-bdc-table"><title>Domain Backend Account Distribution Options</title> +<tgroup cols="3"> + <colspec align="center" colwidth="1*"/> + <colspec align="center" colwidth="1*"/> + <colspec align="left" colwidth="3*"/> + + <thead> + <row><entry>PDC Backend</entry><entry>BDC Backend</entry><entry>Notes/Discussion</entry></row> + </thead> + <tbody> + <row> + <entry><para>Master LDAP Server</para></entry> + <entry><para>Slave LDAP Server</para></entry> + <entry><para>The optimal solution that provides high integrity. The SAM will be + replicated to a common master LDAP server.</para></entry> + </row> + <row> + <entry><para>Single Central LDAP Server</para></entry> + <entry><para>Single Central LDAP Server</para></entry> + <entry><para> + A workable solution without fail-over ability. This is a usable solution, but not optimal. + </para></entry> + </row> + <row> + <entry><para>tdbsam</para></entry> + <entry><para>tdbsam + <command>net rpc vampire</command></para></entry> + <entry><para> + Does not work with Samba-3.0; as Samba does not implement the + server-side protocols required. + </para></entry> + </row> + <row> + <entry><para>tdbsam</para></entry> + <entry><para>tdbsam + <command>rsync</command></para></entry> + <entry><para> + Do not use this configuration. + Does not work because the TDB files are live and data may not + have been flushed to disk. Furthermore, this will cause + domain trust breakdown. + </para></entry> + </row> + <row> + <entry><para>smbpasswd file</para></entry> + <entry><para>smbpasswd file</para></entry> + <entry><para> + Do not use this configuration. + Not an elegant solution due to the delays in synchronization + and also suffers + from the issue of domain trust breakdown. + </para></entry> + </row> + </tbody> +</tgroup> +</table> + +</sect1> + +<sect1> +<title>Essential Background Information</title> + +<para> +A Domain Controller is a machine that is able to answer logon requests from network +workstations. Microsoft LanManager and IBM LanServer were two early products that +provided this capability. The technology has become known as the LanMan Netlogon service. +</para> + +<para> +When MS Windows NT3.10 was first released, it supported a new style of Domain Control +and with it a new form of the network logon service that has extended functionality. +This service became known as the NT NetLogon Service. The nature of this service has +changed with the evolution of MS Windows NT and today provides a complex array of +services that are implemented over an intricate spectrum of technologies. +</para> + +<sect2> +<title>MS Windows NT4-style Domain Control</title> + +<para> +Whenever a user logs into a Windows NT4/200x/XP Professional Workstation, +the workstation connects to a Domain Controller (authentication server) to validate that +the username and password the user entered are valid. If the information entered +does not match account information that has been stored in the Domain +Control database (the SAM, or Security Account Manager database), a set of error +codes is returned to the workstation that has made the authentication request. +</para> + +<para> +When the username/password pair has been validated, the Domain Controller +(authentication server) will respond with full enumeration of the account information +that has been stored regarding that user in the User and Machine Accounts database +for that Domain. This information contains a complete network access profile for +the user but excludes any information that is particular to the user's desktop profile, +or for that matter it excludes all desktop profiles for groups that the user may +belong to. It does include password time limits, password uniqueness controls, +network access time limits, account validity information, machine names from which the +user may access the network, and much more. All this information was stored in the SAM +in all versions of MS Windows NT (3.10, 3.50, 3.51, 4.0). +</para> + +<para> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> +The account information (user and machine) on Domain Controllers is stored in two files, +one containing the Security information and the other the SAM. These are stored in files +by the same name in the <filename>%SystemRoot%\System32\config</filename> directory. +This normally translates to the path <filename>C:\WinNT\System32\config</filename>. These +are the files that are involved in replication of the SAM database where Backup Domain +Controllers are present on the network. +</para> + +<para> +There are two situations in which it is desirable to install Backup Domain Controllers: +</para> + +<itemizedlist> + <listitem><para> + On the local network that the Primary Domain Controller is on, if there are many + workstations and/or where the PDC is generally very busy. In this case the BDCs + will pick up network logon requests and help to add robustness to network services. + </para></listitem> + + <listitem><para> + At each remote site, to reduce wide area network traffic and to add stability to + remote network operations. The design of the network, the strategic placement of + Backup Domain Controllers, together with an implementation that localizes as much + of network to client interchange as possible will help to minimize wide area network + bandwidth needs (and thus costs). + </para></listitem> +</itemizedlist> + +<para> +The inter-operation of a PDC and its BDCs in a true Windows NT4 environment is worth +mentioning here. The PDC contains the master copy of the SAM. In the event that an +administrator makes a change to the user account database while physically present +on the local network that has the PDC, the change will likely be made directly to +the PDC instance of the master copy of the SAM. In the event that this update may +be performed in a branch office, the change will likely be stored in a delta file +on the local BDC. The BDC will then send a trigger to the PDC to commence the process +of SAM synchronization. The PDC will then request the delta from the BDC and apply +it to the master SAM. The PDC will then contact all the BDCs in the Domain and +trigger them to obtain the update and then apply that to their own copy of the SAM. +</para> + +<para> +Samba-3 can not participate in true SAM replication and is therefore not able to +employ precisely the same protocols used by MS Windows NT4. A Samba-3 BDC will +not create SAM update delta files. It will not inter-operate with a PDC (NT4 or Samba) +to synchronize the SAM from delta files that are held by BDCs. +</para> + +<para> +Samba-3 cannot function as a BDC to an MS Windows NT4 PDC, and Samba-3 can not +function correctly as a PDC to an MS Windows NT4 BDC. Both Samba-3 and MS Windows +NT4 can function as a BDC to its own type of PDC. +</para> + +<para> +The BDC is said to hold a <emphasis>read-only</emphasis> of the SAM from which +it is able to process network logon requests and authenticate users. The BDC can +continue to provide this service, particularly while, for example, the wide area +network link to the PDC is down. A BDC plays a very important role in both the +maintenance of Domain Security as well as in network integrity. +</para> + +<para> +In the event that the NT4 PDC should need to be taken out of service, or if it dies, +one of the NT4 BDCs can be promoted to a PDC. If this happens while the original NT4 PDC is on +line, it is automatically demoted to an NT4 BDC. This is an important aspect of Domain +Controller management. The tool that is used to effect a promotion or a demotion is the +Server Manager for Domains. It should be noted that Samba-3 BDCs can not be promoted +in this manner because reconfiguration of Samba requires changes to the &smb.conf; file. +</para> + +<sect3> +<title>Example PDC Configuration</title> + +<para> +Beginning with 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 <smbconfsection name="[global]"/>-section of the &smb.conf; have to be set. +Refer to <link linkend="minimalPDC">following configuration</link> for an example of the minimum required settings. +</para> + +<para><smbconfexample id="minimalPDC"> +<title>Minimal smb.conf for a PDC in Use With a BDC &smbmdash; LDAP Server on PDC.</title> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +<smbconfoption name="passdb backend">ldapsam://localhost:389</smbconfoption> +<smbconfoption name="domain master">yes</smbconfoption> +<smbconfoption name="domain logons">yes</smbconfoption> +</smbconfexample></para> + +<para> +Several other things like a <smbconfsection name="[homes]"/> and a +<smbconfsection name="[netlogon]"/> share also need to be set along with +settings for the profile path, the user's home drive, and so on. This is not covered in this +chapter; for more information please refer to <link linkend="samba-pdc">Domain Control</link>. +</para> + +</sect3> +</sect2> + +<sect2> +<title>LDAP Configuration Notes</title> + +<para> +When configuring a master and a slave LDAP server, it is advisable to use the master LDAP server +for the PDC and slave LDAP servers for the BDCs. It is not essential to use slave LDAP servers, however, +many administrators will want to do so in order to provide redundant services. Of course, one or more BDCs +may use any slave LDAP server. Then again, it is entirely possible to use a single LDAP server for the +entire network. +</para> + +<para> +When configuring a master LDAP server that will have slave LDAP servers, do not forget to configure +this in the <filename>/etc/openldap/slapd.conf</filename> file. It must be noted that the DN of a +server certificate must use the CN attribute to name the server, and the CN must carry the servers' +fully qualified domain name. Additional alias names and wildcards may be present in the +subjectAltName certificate extension. More details on server certificate names are in RFC2830. +</para> + +<para> +It does not really fit within the scope of this document, but a working LDAP installation is +basic to LDAP enabled Samba operation. When using an OpenLDAP server with Transport Layer Security +(TLS), the machine name in <filename>/etc/ssl/certs/slapd.pem</filename> must be the +same as in <filename>/etc/openldap/sldap.conf</filename>. The Red Hat Linux startup script +creates the <filename>slapd.pem</filename> file with hostname <quote>localhost.localdomain.</quote> +It is impossible to access this LDAP server from a slave LDAP server (i.e., a Samba BDC) unless the +certificate is recreated with a correct hostname. +</para> + +<para> +For preference, do not install a Samba PDC on a OpenLDAP slave server. Joining client machines to the domain +will fail in this configuration because the change to the machine account in the LDAP tree +must take place on the master LDAP server. This is not replicated rapidly enough to the slave +server that the PDC queries. It therefore gives an error message on the client machine about +not being able to set up account credentials. The machine account is created on the LDAP server +but the password fields will be empty. Unfortunately, some sites are +unable to avoid such configurations, and these sites should review the +<smbconfoption name="ldap replication sleep"/> parameter, intended to slow down Samba sufficiently +for the replication to catch up. This is a kludge, and one that the +administrator must manually duplicate in any scripts (such as the +<smbconfoption name="add machine script"/>) that +they use. +</para> + +<para> +Possible PDC/BDC plus LDAP configurations include: +</para> + +<itemizedlist> + <listitem><para> + PDC+BDC -> One Central LDAP Server. + </para></listitem> + <listitem><para> + PDC -> LDAP master server, BDC -> LDAP slave server. + </para></listitem> + <listitem><para> + PDC -> LDAP master, with secondary slave LDAP server. + </para><para> + BDC -> LDAP master, with secondary slave LDAP server. + </para></listitem> + <listitem><para> + PDC -> LDAP master, with secondary slave LDAP server. + </para><para> + BDC -> LDAP slave server, with secondary master LDAP server. + </para></listitem> +</itemizedlist> + +<para> +In order to have a fall-back configuration (secondary) LDAP server one would specify +the secondary LDAP server in the &smb.conf; file as shown in <link linkend="mulitldapcfg">following example</link>. +</para> + +<para> +<smbconfexample id="mulitldapcfg"> +<title>Multiple LDAP Servers in &smb.conf;</title> +<member>...</member> +<smbconfoption name="passdb backend"> </smbconfoption> +<member><parameter>ldapsam:"ldap://master.quenya.org ldap://slave.quenya.org"</parameter></member> +<member>...</member> +</smbconfexample> +</para> + +</sect2> + +<sect2> +<title>Active Directory Domain Control</title> + +<para> +As of the release of MS Windows 2000 and Active Directory, this information is now stored +in a directory that can be replicated and for which partial or full administrative control +can be delegated. Samba-3 is not able to be a Domain Controller within an Active Directory +tree, and it cannot be an Active Directory server. This means that Samba-3 also cannot +act as a Backup Domain Controller to an Active Directory Domain Controller. +</para> + +</sect2> + +<sect2> +<title>What Qualifies a Domain Controller on the Network?</title> + +<para> +Every machine that is a Domain Controller for the domain MIDEARTH has to register the NetBIOS +group name MIDEARTH<#1c> with the WINS server and/or by broadcast on the local network. +The PDC also registers the unique NetBIOS name MIDEARTH<#1b> with the WINS server. +The name type <#1b> name is normally reserved for the Domain Master Browser, a role +that has nothing to do with anything related to authentication, but the Microsoft Domain +implementation requires the Domain Master Browser to be on the same machine as the PDC. +</para> + +<para> +Where a WINS server is not used, broadcast name registrations alone must suffice. Refer to +<link linkend="netdiscuss">Network Browsing: Discussion</link> for more information regarding TCP/IP network protocols and how + SMB/CIFS names are handled. +</para> + +</sect2> + +<sect2> +<title>How does a Workstation find its Domain Controller?</title> + +<para> +There are two different mechanisms to locate a domain controller, one method is used when +NetBIOS over TCP/IP is enabled and the other when it has been disabled in the TCP/IP +network configuration. +</para> + +<para> +Where NetBIOS over TCP/IP is disabled, all name resolution involves the use of DNS, broadcast +messaging over UDP, as well as Active Directory communication technologies. In this type of +environment all machines require appropriate DNS entries. More information may be found in +<link linkend="adsdnstech">DNS and Active Directory</link>. +</para> + +<sect3> +<title>NetBIOS Over TCP/IP Enabled</title> +<para> +An MS Windows NT4/200x/XP Professional workstation in the domain MIDEARTH that wants a +local user to be authenticated has to find the Domain Controller for MIDEARTH. It does this +by doing a NetBIOS name query for the group name MIDEARTH<#1c>. It assumes that each +of the machines it gets back from the queries is a Domain Controller and can answer logon +requests. To not open security holes, both the workstation and the selected Domain Controller +authenticate each other. After that the workstation sends the user's credentials (name and +password) to the local Domain Controller for validation. +</para> + +</sect3> + +<sect3> +<title>NetBIOS Over TCP/IP Disabled</title> + +<para> +An MS Windows NT4/200x/XP Professional workstation in the realm <constant>quenya.org</constant> +that has a need to affect user logon authentication will locate the Domain Controller by +re-querying DNS servers for the <constant>_ldap._tcp.pdc._msdcs.quenya.org</constant> record. +More information regarding this subject may be found in <link linkend="adsdnstech">DNS and Active Directory</link>. +</para> + +</sect3> +</sect2> +</sect1> + +<sect1> +<title>Backup Domain Controller Configuration</title> + +<para> +The creation of a BDC requires some steps to prepare the Samba server before +&smbd; is executed for the first time. These steps are outlines as follows: +<indexterm><primary>SID</primary></indexterm> +</para> + +<itemizedlist> +<listitem><para> + The domain SID has to be the same on the PDC and the BDC. In Samba versions + pre-2.2.5, the domain SID was stored in the file <filename>private/MACHINE.SID</filename>. + The domain SID is now stored in the file <filename>private/secrets.tdb</filename>. This file + is unique to each server and can not be copied from a PDC to a BDC, the BDC will generate + a new SID at start-up. It will over-write the PDC domain SID with the newly created BDC SID. + There is a procedure that will allow the BDC to aquire the Domain SID. This is described here. + </para> + + <para> + To retrieve the domain SID from the PDC or an existing BDC and store it in the + <filename>secrets.tdb</filename>, execute: + </para> +<screen> +&rootprompt;<userinput>net rpc getsid</userinput> +</screen> + </listitem> + + <listitem><para> + Specification of the <smbconfoption name="ldap admin dn"/> is obligatory. + This also requires the LDAP administration password to be set in the <filename>secrets.tdb</filename> + using the <command>smbpasswd -w <replaceable>mysecret</replaceable></command>. + </para></listitem> + + <listitem><para> + Either <smbconfoption name="ldap suffix"/> or + <smbconfoption name="ldap idmap suffix"/> must be specified in + the &smb.conf; file. + </para></listitem> + + <listitem><para> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> + The UNIX user database has to be synchronized from the PDC to the + BDC. This means that both the <filename>/etc/passwd</filename> and + <filename>/etc/group</filename> have to be replicated from the PDC + to the BDC. This can be done manually whenever changes are made. + Alternately, the PDC is set up as an NIS master server and the BDC as an NIS slave + server. To set up the BDC as a mere NIS client would not be enough, + as the BDC would not be able to access its user database in case of + a PDC failure. NIS is by no means the only method to synchronize + passwords. An LDAP solution would also work. + </para> + </listitem> + + <listitem><para> + The Samba password database must be replicated from the PDC to the BDC. + Although it is possible to synchronize the <filename>smbpasswd</filename> + file with <command>rsync</command> and <command>ssh</command>, this method + is broken and flawed, and is therefore not recommended. A better solution + is to set up slave LDAP servers for each BDC and a master LDAP server for the PDC. + </para></listitem> + + <listitem><para> + The netlogon share has to be replicated from the PDC to the + BDC. This can be done manually whenever login scripts are changed, + or it can be done automatically using a <command>cron</command> job + that will replicate the directory structure in this share using a tool + like <command>rsync</command>. + </para></listitem> + +</itemizedlist> + +<sect2> +<title>Example Configuration</title> + +<para> Finally, the BDC has to be found by the workstations. This can be +done by setting Samba as shown in <link linkend="minim-bdc">the next example</link>. +</para> + +<para><smbconfexample id="minim-bdc"> +<title>Minimal setup for being a BDC</title> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +<smbconfoption name="passdb backend">ldapsam:ldap://slave-ldap.quenya.org</smbconfoption> +<smbconfoption name="domain master">no</smbconfoption> +<smbconfoption name="domain logons">yes</smbconfoption> +<smbconfoption name="idmap backend">ldap:ldap://slave-ldap.quenya.org</smbconfoption> +</smbconfexample></para> + +<para> +In the <smbconfsection name="[global]"/>-section of the &smb.conf; of the BDC. This makes the BDC +only register the name MIDEARTH<#1c> with the WINS server. This is no +problem as the name MIDEARTH<#1c> is a NetBIOS group name that is meant to +be registered by more than one machine. The parameter +<smbconfoption name="domain master">no</smbconfoption> +forces the BDC not to register <?latex \linebreak ?>MIDEARTH<#1b> which as a unique NetBIOS +name is reserved for the Primary Domain Controller. +</para> + +<para> +<indexterm><primary>idmap backend</primary></indexterm> +<indexterm><primary>winbindd</primary></indexterm> +The <parameter>idmap backend</parameter> will redirect the <command>winbindd</command> utility to +use the LDAP database to resolve all UIDs and GIDs for UNIX accounts. +</para> + +<note><para> +<indexterm><primary>Server Type</primary><secondary>Domain Member</secondary></indexterm> +Samba-3 has introduced a new ID mapping facility. One of the features of this facility is that it +allows greater flexibility in how user and group IDs are handled in respect to NT Domain User and Group +SIDs. One of the new facilities provides for explicitly ensuring that UNIX/Linux UID and GID values +will be consistent on the PDC, all BDCs and all Domain Member servers. The parameter that controls this +is called <parameter>idmap backend</parameter>. Please refer to the man page for &smb.conf; for more information +regarding its behavior. +</para></note> + +<para> +The use of the <smbconfoption name="idmap backend">ldap:ldap://master.quenya.org</smbconfoption> +option on a BDC only make sense where ldapsam is used on a PDC. The purpose for an LDAP based idmap backend is +also to allow a domain-member (without its own passdb backend) to use winbindd to resolve Windows network users +and groups to common UID/GIDs. In other words, this option is generally intended for use on BDCs and on Domain +Member servers. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +As this is a rather new area for Samba, there are not many examples that we may refer to. +Updates will be published as they become available and may be found in later Samba releases or +from the Samba web <ulink url="http://samba.org">site.</ulink> +</para> + +<sect2> +<title>Machine Accounts Keep Expiring</title> + +<para> +<indexterm><primary>Machine Trust Accounts</primary></indexterm> +This problem will occur when the passdb (SAM) files are copied from a central +server but the local Backup Domain Controller is acting as a PDC. This results in the application of +Local Machine Trust Account password updates to the local SAM. Such updates +are not copied back to the central server. The newer machine account password is then over +written when the SAM is re-copied from the PDC. The result is that the Domain Member machine +on start up will find that its passwords do not match the one now in the database and +since the startup security check will now fail, this machine will not allow logon attempts +to proceed and the account expiry error will be reported. +</para> + +<para> +The solution is to use a more robust passdb backend, such as the ldapsam backend, setting up +a slave LDAP server for each BDC, and a master LDAP server for the PDC. +</para> + +</sect2> + +<sect2> +<title>Can Samba Be a Backup Domain Controller to an NT4 PDC?</title> + +<para> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> +No. The native NT4 SAM replication protocols have not yet been fully implemented. +</para> + +<para> +Can I get the benefits of a BDC with Samba? Yes, but only to a Samba PDC.The +main reason for implementing a BDC is availability. If the PDC is a Samba +machine, a second Samba machine can be set up to service logon requests whenever +the PDC is down. +</para> + +</sect2> + +<sect2> +<title>How Do I Replicate the smbpasswd File?</title> + +<para> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> +Replication of the smbpasswd file is sensitive. It has to be done whenever changes +to the SAM are made. Every user's password change is done in the smbpasswd file and +has to be replicated to the BDC. So replicating the smbpasswd file very often is necessary. +</para> + +<para> +As the smbpasswd file contains plain text password equivalents, it must not be +sent unencrypted over the wire. The best way to set up smbpasswd replication from +the PDC to the BDC is to use the utility rsync. rsync can use ssh as a transport. +<command>ssh</command> itself can be set up to accept <emphasis>only</emphasis> +<command>rsync</command> transfer without requiring the user to type a password. +</para> + +<para> +As said a few times before, use of this method is broken and flawed. Machine trust +accounts will go out of sync, resulting in a broken domain. This method is +<emphasis>not</emphasis> recommended. Try using LDAP instead. +</para> + +</sect2> + +<sect2> +<title>Can I Do This All with LDAP?</title> + +<para> +The simple answer is yes. Samba's pdb_ldap code supports binding to a replica +LDAP server, and will also follow referrals and re-bind to the master if it ever +needs to make a modification to the database. (Normally BDCs are read only, so +this will not occur often). +</para> + +</sect2> +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Backup.xml b/docs/Samba3-HOWTO/TOSHARG-Backup.xml new file mode 100644 index 0000000000..7844fb13f2 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Backup.xml @@ -0,0 +1,203 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="Backup"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>Backup Techniques</title> + +<sect1> +<title>Features and Benefits</title> + +<para> +The Samba project is over ten years old. During the early history +of Samba, UNIX administrators were its key implementors. UNIX administrators +will use UNIX system tools to backup UNIX system files. Over the past +four years, an increasing number of Microsoft network administrators have +taken an interest in Samba. This is reflected in the questions about backup +in general on the Samba mailing lists. +</para> + +</sect1> + +<sect1> +<title>Discussion of Backup Solutions</title> + +<para> +During discussions at a Microsoft Windows training course, one of +the pro-UNIX delegates stunned the class when he pointed out that Windows +NT4 is so limiting compared with UNIX. He likened UNIX to a Meccano set +that has an unlimited number of tools that are simple, efficient, +and, in combination, capable of achieving any desired outcome. +</para> + +<para> +One of the Windows networking advocates retorted that if she wanted a +Meccano set, she would buy one. She made it clear that a complex single +tool that does more than is needed but does it with a clear purpose and +intent is preferred by some like her. +</para> + +<para> +Please note that all information here is provided as is and without recommendation +of fitness or suitability. The network administrator is strongly encouraged to +perform due-diligence research before implementing any backup solution, whether free +software or commercial. +</para> + +<para> +A useful Web site I recently stumbled across that you might like to refer to +is located at <ulink noescape="1" url="http://www.allmerchants.com/Software/Backup_Software/"> +www.allmerchants.com</ulink>. +</para> + +<para> +The following three free software projects might also merit consideration. +</para> + + <sect2> + <title>BackupPC</title> + + + <para> + <indexterm><primary>BackupPC</primary></indexterm> + BackupPC version 2.0.0 has been released on <ulink url="http://backuppc.sourceforge.net">SourceForge.</ulink> + New features include support for <command>rsync/rsyncd</command> and internationalization of the CGI interface + (including English, French, Spanish, and German). + </para> + + <para> + BackupPC is a high-performance Perl-based package for backing up Linux, + UNIX or Windows PCs and laptops to a server's disk. BackupPC is highly + configurable and easy to install and maintain. SMB (via smbclient), + <command>tar</command> over <command>rsh/ssh</command> or <command>rsync/rsyncd</command> + are used to extract client data. + </para> + + <para> + Given the ever decreasing cost of disks and raid systems, it is now + practical and cost effective to backup a large number of machines onto + a server's local disk or network storage. This is what BackupPC does. + </para> + + <para> + Key features are pooling of identical files (big savings in server disk + space), compression, and a comprehensive CGI interface that allows users + to browse backups and restore files. + </para> + + <para> + BackupPC is free software distributed under a GNU GPL license. + BackupPC runs on Linux/UNIX/freenix servers, and has been tested + on Linux, UNIX, Windows 9x/ME, Windows 98, Windows 200x, Windows XP, and Mac OSX clients. + </para> + + </sect2> + + <sect2> + <title>Rsync</title> + + <para><command>rsync</command> is a flexible program for efficiently copying files or + directory trees.</para> + + <para><command>rsync</command> has many options to select which files will be copied + and how they are to be transferred. It may be used as an + alternative to <command>ftp, http, scp</command>, or <command>rcp</command>.</para> + + <para>The rsync remote-update protocol allows rsync to transfer just + the differences between two sets of files across the network link, + using an efficient checksum-search algorithm described in the + technical report that accompanies the rsync package.</para> + + <para>Some of the additional features of rsync are:</para> + + <itemizedlist> + + <listitem> + <para> + Support for copying links, devices, owners, groups, and permissions. + </para> + </listitem> + + <listitem> + <para> + Exclude and exclude-from options are similar to GNU tar. + </para> + </listitem> + + <listitem> + <para> + A CVS exclude mode for ignoring the same files that CVS would ignore. + </para> + </listitem> + + <listitem> + <para> + Can use any transparent remote shell, including rsh or ssh. + </para> + </listitem> + + <listitem> + <para> + Does not require root privileges. + </para> + </listitem> + + <listitem> + <para> + Pipelining of file transfers to minimize latency costs. + </para> + </listitem> + + <listitem> + <para> + Support for anonymous or authenticated rsync servers (ideal for + mirroring). + </para> + </listitem> + </itemizedlist> + + </sect2> + + <sect2> + <title>Amanda</title> + + + <para> + <indexterm><primary>Amanda</primary></indexterm> + Amanda, the Advanced Maryland Automatic Network Disk Archiver, is a backup system that + allows the administrator of a LAN to set up a single master backup server to back up + multiple hosts to a single large capacity tape drive. Amanda uses native dump and/or + GNU tar facilities and can back up a large number of workstations running multiple + versions of UNIX. Recent versions can also use Samba to back up Microsoft Windows hosts. + </para> + + <para> + For more information regarding Amanda, please check the <ulink url="http://www.amanda.org/"> + www.amanda.org/ site.</ulink> + </para> + + </sect2> + + <sect2> + <title>BOBS: Browseable Online Backup System</title> + + + <para> + <indexterm><primary>BOBS</primary></indexterm> + Browseable Online Backup System (BOBS) is a complete online backup system. Uses large + disks for storing backups and lets users browse the files using a Web browser. Handles + some special files like AppleDouble and icon files. + </para> + + <para> + The home page for BOBS is located at <ulink url="http://bobs.sourceforge.net/"> + bobs.sourceforge.net.</ulink> + </para> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Bugs.xml b/docs/Samba3-HOWTO/TOSHARG-Bugs.xml new file mode 100644 index 0000000000..5af66fc05a --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Bugs.xml @@ -0,0 +1,277 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="bugreport"> + +<chapterinfo> + &author.jht; + &author.jelmer; + &author.tridge; + <pubdate> 27 June 1997 </pubdate> +</chapterinfo> + +<title>Reporting Bugs</title> + +<sect1> +<title>Introduction</title> + +<para>Please report bugs using Samba's +<ulink url="https://bugzilla.samba.org/">Bugzilla</ulink> facilities and +take the time to read this file before you submit a bug +report. Also, check to see if it has changed between releases, as we +may be changing the bug reporting mechanism at some point. +</para> + +<para> +Please do as much as you can yourself to help track down the +bug. Samba is maintained by a dedicated group of people who volunteer +their time, skills and efforts. We receive far more mail than +we can possibly answer, so you have a much higher chance of a response +and a fix if you send us a <quote>developer friendly</quote> bug report that lets +us fix it fast. +</para> + +<para> +Do not assume that if you post the bug to the comp.protocols.smb +newsgroup or the mailing list that we will read it. If you suspect that your +problem is not a bug but a configuration problem, it is better to send +it to the Samba mailing list, as there are thousands of other users on +that list who may be able to help you. +</para> + +<para> +You may also like to look though the recent mailing list archives, +which are conveniently accessible on the Samba Web pages +at <ulink noescape="1" url="http://samba.org/samba/">http://samba.org/samba/</ulink>. +</para> + +</sect1> + +<sect1> +<title>General Information</title> + +<para> +Before submitting a bug report, check your config for silly +errors. Look in your log files for obvious messages that tell +you've mis-configured something. Run testparm to check your config +file for correct syntax. +</para> + +<para> +Have you looked through <link linkend="diagnosis">The Samba Checklist</link>? This is extremely important. +</para> + +<para> +If you include part of a log file with your bug report, then be sure to +annotate it with exactly what you were doing on the client at the +time and exactly what the results were. +</para> + +</sect1> + +<sect1 id="dbglvl"> +<title>Debug Levels</title> + +<para> +If the bug has anything to do with Samba behaving incorrectly as a +server (like refusing to open a file), then the log files will probably +be quite useful. Depending on the problem, a log level of between 3 and +10 showing the problem may be appropriate. A higher level gives more +detail, but may use too much disk space. +</para> + +<para> +To set the debug level, use the <smbconfoption name="log level"/> 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, add the following lines to your main &smb.conf; file: +</para> + +<para><smbconfblock> +<smbconfoption name="log level">10</smbconfoption> +<smbconfoption name="log file">/usr/local/samba/lib/log.%m</smbconfoption> +<smbconfoption name="include">/usr/local/samba/lib/smb.conf.%m</smbconfoption> +</smbconfblock></para> + +<para> +and 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 +<smbconfoption name="log level"/> may be useful. This also allows you to +experiment with different security systems, protocol levels and so on, on just +one machine. +</para> + +<para> +The &smb.conf; entry <smbconfoption name="log level"/> +is synonymous with the parameter <smbconfoption name="debuglevel"/> that has +been used in older versions of Samba and is being retained for backward +compatibility of &smb.conf; files. +</para> + +<para> +As the <smbconfoption name="log level"/> value is increased, you will record +a significantly greater level of debugging information. For most +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 large volume of log data. +</para> + + <sect2> + <title>Debugging Specific Operations</title> + + <para> + Samba-3.x permits debugging (logging) of specific functional components without unnecessarily + cluttering the log files with detailed logs for all operations. An example configuration to + achive this is shown in: + </para> + +<para> +<smbconfblock> +<smbconfoption name="log level">0 tdb:3 passdb:5 auth:4 vfs:2</smbconfoption> +<smbconfoption name="max log size">0</smbconfoption> +<smbconfoption name="log file">/var/log/samba/%U.%m.log</smbconfoption> +</smbconfblock> +</para> + + <para> + This will cause the level of detail to be expanded to the debug class (log level) passed to + each funtional area per the value shown above. The first value passed to the <parameter>log level</parameter> + of <constant>0</constant> means turn off all unnecessary debugging except the debug classes set for + the functional areas as specified. The table shown in <link linkend="dbgclass">Debugable Functions</link> + may be used to affect very precise analysis of each SMB operation Samba is conducting. + </para> + + <table frame="all" id="dbgclass"> + <title>Debuggable Functions</title> + <tgroup cols="2" align="center"> + <thead> + <row><entry>Function Name</entry><entry>Function Name</entry></row> + </thead> + <tbody> + <row><entry>all</entry><entry>passdb</entry></row> + <row><entry>tdb</entry><entry>sam</entry></row> + <row><entry>printdrivers</entry><entry>auth</entry></row> + <row><entry>lanman</entry><entry>winbind</entry></row> + <row><entry>smb</entry><entry>vfs</entry></row> + <row><entry>rpc_parse</entry><entry>idmap</entry></row> + <row><entry>rpc_srv</entry><entry>quota</entry></row> + <row><entry>rpc_cli</entry><entry>acls</entry></row> + </tbody> + </tgroup> + </table> + + </sect2> + +</sect1> + +<sect1> +<title>Internal Errors</title> + +<para> +If you get the message <quote><errorname>INTERNAL ERROR</errorname></quote> 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> + +<para> +If the message came from smbd, it will probably be accompanied by +a message that details the last SMB message received by smbd. This +information is often useful in tracking down the problem so please +include it in your bug report. +</para> + +<para> +You should also detail how to reproduce the problem, if +possible. Please make this reasonably detailed. +</para> + + +<para> +<indexterm><primary>core files</primary></indexterm> +You may also find that a core file appeared in a <filename>corefiles</filename> +subdirectory of the directory where you keep your Samba log +files. This file is the most useful tool for tracking down the bug. To +use it, you do this: +<indexterm><primary>gdb</primary></indexterm> +<indexterm><primary>debug</primary></indexterm> +</para> + + +<screen> +&prompt;<userinput>gdb smbd core</userinput> +</screen> + +<para> +adding appropriate paths to smbd and core so gdb can find them. If you +do not have gdb, 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, 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 +do not know assembly, including this information in the bug report can be +useful. +</para> +</sect1> + +<sect1> +<title>Attaching to a Running Process</title> + +<para> +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 <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> + +<para> +Sometimes it is necessary to build a Samba binary files that have debugging +symbols so as to make it possible to capture enough information from a crashed +operation to permit the Samba Team to fix the problem. +</para> + +<para> +Compile with <constant>-g</constant> to ensure you have symbols in place. +Add the following line to the &smb.conf; file global section: +<screen> +panic action = "/bin/sleep 90000" +</screen> +to catch any panics. If <command>smbd</command> seems to be frozen look for any sleep +processes. If it is not, and appears to be spinning, find the process id +of the spinning process and type: +<screen> +gdb /usr/local/samba/sbin/smbd +</screen> +then <quote>attach 'pid'</quote> (of the spinning process), then type <quote>bt</quote> to +get a backtrace to see where the smbd is in the call path. +</para> + +</sect1> + +<sect1> +<title>Patches</title> + + +<para> +<indexterm><primary>diff</primary></indexterm> +<indexterm><primary>patch</primary></indexterm> +The best sort of bug report is one that includes a fix! If you send us +patches, please use <userinput>diff -u</userinput> format if your version of +diff supports it, otherwise use <userinput>diff -c4</userinput>. Make sure +you do the diff against a clean version of the source and let me know +exactly what version you used. +</para> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml b/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml new file mode 100644 index 0000000000..aac9bc4999 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml @@ -0,0 +1,5491 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="CUPS-printing"> + +<chapterinfo> + + <author> + <firstname>Kurt</firstname><surname>Pfeifle</surname> + <affiliation> + <orgname>Danka Deutschland GmbH </orgname> + <address><email>kpfeifle@danka.de</email></address> + </affiliation> + </author> + <author> + <firstname>Ciprian</firstname><surname>Vizitiu</surname> + <affiliation> + <address><email>CVizitiu@gbif.org</email></address> + </affiliation> + <contrib>drawings</contrib> + </author> + + <author>&person.jelmer;<contrib>drawings</contrib></author> + + <pubdate> (27 Jan 2004) </pubdate> +</chapterinfo> + +<title>CUPS Printing Support</title> + +<sect1> + + <title>Introduction</title> + + <sect2> + <title>Features and Benefits</title> + + <para> + The Common UNIX Print System (<ulink url="http://www.cups.org/">CUPS</ulink>) + has become quite popular. All major Linux distributions now ship it as their default printing + system. To many, it is still a mystical tool. Mostly, it just works. + People tend to regard it as a <quote>black box</quote> + that they do not want to look into as long as it works. But once + there is a little problem, they are in trouble to find out where to + start debugging it. Refer to the chapter <quote>Classical Printing</quote> that + contains a lot of information that is relevant for CUPS. + </para> + + <para> + CUPS sports quite a few unique and powerful features. While their + basic functions may be grasped quite easily, they are also + new. Because they are different from other, more traditional printing + systems, it is best not to try and apply any prior knowledge about + printing to this new system. Rather, try to understand CUPS + from the beginning. This documentation will lead you to a + complete understanding of CUPS. Let's start with the most basic + things first. + </para> + + </sect2> + + <sect2> + <title>Overview</title> + + <para> + CUPS is more than just a print spooling system. It is a complete + printer management system that complies with the new + Internet Printing Protocol (IPP). IPP is an industry + and Internet Engineering Task Force (IETF) + standard for network printing. Many of its functions can be managed + remotely (or locally) via a Web browser (giving you a + platform-independent access to the CUPS print server). Additionally, it + has the traditional command line and several more modern GUI interfaces + (GUI interfaces developed by third parties, like KDE's + overwhelming <ulink url="http://printing.kde.org/">KDEPrint</ulink>). + </para> + + <para> + CUPS allows creation of <quote>raw</quote> printers (i.e., no print file + format translation) as well as <quote>smart</quote> printers (i.e., CUPS does + file format conversion as required for the printer). In many ways + this gives CUPS similar capabilities to the MS Windows print + monitoring system. Of course, if you are a CUPS advocate, you would + argue that CUPS is better! In any case, let us now move on to + explore how one may configure CUPS for interfacing with MS Windows + print clients via Samba. + </para> + </sect2> +</sect1> + +<sect1> + <title>Basic CUPS Support Configuration</title> + + <para> + Printing with CUPS in the most basic &smb.conf; setup in Samba-3.0 (as was true for 2.2.x) only needs two + settings: <smbconfoption name="printing">cups</smbconfoption> and + <smbconfoption name="printcap">cups</smbconfoption>. CUPS does not need a printcap file. + However, the <filename>cupsd.conf</filename> configuration file knows of two related directives that control + how such a file will be automatically created and maintained by CUPS for the convenience of third-party + applications (example: <parameter>Printcap /etc/printcap</parameter> and <parameter>PrintcapFormat BSD</parameter>). + Legacy programs often require the existence of a printcap file containing printer names or they will refuse to + print. Make sure CUPS is set to generate and maintain a printcap file. For details, see + <command>man cupsd.conf</command> and other CUPS-related documentation, like the wealth of documents on your CUPS server + itself: <ulink noescape="1" url="http://localhost:631/documentation.html">http://localhost:631/documentation.html</ulink>. + </para> + + <sect2> + <title>Linking smbd with libcups.so</title> + + <para> + Samba has a special relationship to CUPS. Samba can be compiled with CUPS library support. + Most recent installations have this support enabled. Per default, CUPS linking is compiled + into smbd and other Samba binaries. Of course, you can use CUPS even + if Samba is not linked against <filename>libcups.so</filename> &smbmdash; but + there are some differences in required or supported configuration. + </para> + + <para> + When Samba is compiled against <filename>libcups</filename>, <smbconfoption name="printcap">cups</smbconfoption> + uses the CUPS API to list printers, submit jobs, query queues, and so on. Otherwise it maps to the System V + commands with an additional <command>-oraw</command> option for printing. On a Linux + system, you can use the <command>ldd</command> utility to find out details (ldd may not be present on + other OS platforms, or its function may be embodied by a different command): + </para> + +<para><screen> +&rootprompt;<userinput>ldd `which smbd`</userinput> +libssl.so.0.9.6 => /usr/lib/libssl.so.0.9.6 (0x4002d000) +libcrypto.so.0.9.6 => /usr/lib/libcrypto.so.0.9.6 (0x4005a000) +libcups.so.2 => /usr/lib/libcups.so.2 (0x40123000) +[....] +</screen></para> + + <para> + The line <computeroutput>libcups.so.2 => /usr/lib/libcups.so.2 (0x40123000)</computeroutput> shows + there is CUPS support compiled into this version of Samba. If this is the case, and printing = cups + is set, then <emphasis>any otherwise manually set print command in &smb.conf; is ignored</emphasis>. + This is an important point to remember! + </para> + + <tip><para> Should it be necessary, for any reason, to set your own print commands, you can do this by setting + <smbconfoption name="printing">sysv</smbconfoption>. However, you will lose all the benefits + of tight CUPS/Samba integration. When you do this you must manually configure the printing system commands + (most important: + <smbconfoption name="print command"/>; other commands are + <smbconfoption name="lppause command"/>, + <smbconfoption name="lpresume command"/>, + <smbconfoption name="lpq command"/>, + <smbconfoption name="lprm command"/>, + <smbconfoption name="queuepause command"/> and + <smbconfoption name="queue resume command"/>).</para></tip> + </sect2> + + <sect2> + <title>Simple &smb.conf; Settings for CUPS</title> + + <para> + To summarize, <link linkend="cups-exam-simple">following example</link> shows simplest printing-related setup for &smb.conf; to enable basic CUPS support: + </para> + + <para><smbconfexample id="cups-exam-simple"> + <title>Simplest printing-related smb.conf</title> + <smbconfsection name="[global]"/> + <smbconfoption name="load printers">yes</smbconfoption> + <smbconfoption name="printing">cups</smbconfoption> + <smbconfoption name="printcap name">cups</smbconfoption> + + <smbconfsection name="[printers]"/> + <smbconfoption name="comment">All Printers</smbconfoption> + <smbconfoption name="path">/var/spool/samba</smbconfoption> + <smbconfoption name="browseable">no</smbconfoption> + <smbconfoption name="public">yes</smbconfoption> + <smbconfoption name="guest ok">yes</smbconfoption> + <smbconfoption name="writable">no</smbconfoption> + <smbconfoption name="printable">yes</smbconfoption> + <smbconfoption name="printer admin">root, @ntadmins</smbconfoption> + + </smbconfexample></para> + + <para> + This is all you need for basic printing setup for CUPS. It will print + all graphic, text, PDF, and PostScript files submitted from Windows + clients. However, most of your Windows users would not know how to + send these kinds of files to print without opening a GUI + application. Windows clients tend to have local printer drivers + installed, and the GUI application's print buttons start a printer + driver. Your users also rarely send files from the command + line. Unlike UNIX clients, they hardly submit graphic, text or PDF + formatted files directly to the spooler. They nearly exclusively print + from GUI applications with a <quote>printer driver</quote> hooked in between the + application's native format and the print-data-stream. If the backend + printer is not a PostScript device, the print data stream is <quote>binary,</quote> + sensible only for the target printer. Read on to learn which problem + this may cause and how to avoid it. + </para> + </sect2> + + <sect2> + <title>More Complex CUPS &smb.conf; Settings</title> + + <para> + <link linkend="overridesettings">Next configuration</link> is a slightly more complex printing-related setup + for &smb.conf;. It enables general CUPS printing + support for all printers, but defines one printer share, which is set + up differently. + </para> + + <para><smbconfexample id="overridesettings"> + <title>Overriding global CUPS settings for one printer</title> + <smbconfsection name="[global]"/> + <smbconfoption name="printing">cups</smbconfoption> + <smbconfoption name="printcap name">cups</smbconfoption> + <smbconfoption name="load printers">yes</smbconfoption> + + <smbconfsection name="[printers]"/> + <smbconfoption name="comment">All Printers</smbconfoption> + <smbconfoption name="path">/var/spool/samba</smbconfoption> + <smbconfoption name="public">yes</smbconfoption> + <smbconfoption name="guest ok">yes</smbconfoption> + <smbconfoption name="writable">no</smbconfoption> + <smbconfoption name="printable">yes</smbconfoption> + <smbconfoption name="printer admin">root, @ntadmins</smbconfoption> + + <smbconfsection name="[special_printer]"/> + <smbconfoption name="comment">A special printer with his own settings</smbconfoption> + <smbconfoption name="path">/var/spool/samba-special</smbconfoption> + <smbconfoption name="printing">sysv</smbconfoption> + <smbconfoption name="printcap">lpstat</smbconfoption> + <smbconfoption name="print command">echo "NEW: `date`: printfile %f" \</smbconfoption> + <member><parameter> >> /tmp/smbprn.log ; \</parameter></member> + <member><parameter>echo " `date`: p-%p s-%s f-%f" >> /tmp/smbprn.log ; \</parameter></member> + <member><parameter>echo " `date`: j-%j J-%J z-%z c-%c" >> /tmp/smbprn.log ; rm %f</parameter></member> + <smbconfoption name="public">no</smbconfoption> + <smbconfoption name="guest ok">no</smbconfoption> + <smbconfoption name="writable">no</smbconfoption> + <smbconfoption name="printable">yes</smbconfoption> + <smbconfoption name="printer admin">kurt</smbconfoption> + <smbconfoption name="hosts deny">0.0.0.0</smbconfoption> + <smbconfoption name="hosts allow">turbo_xp, 10.160.50.23, 10.160.51.60</smbconfoption> + </smbconfexample></para> + + <para> + This special share is only there for testing purposes. It does not write the print job to a file. It just logs the job parameters + known to Samba into the <filename>/tmp/smbprn.log</filename> file and deletes the job-file. Moreover, the + <smbconfoption name="printer admin"/> of this share is <quote>kurt</quote> (not the <quote>@ntadmins</quote> group), + guest access is not allowed, the share isn't published to the Network Neighborhood (so you need to know it is there), and it only + allows access from only three hosts. To prevent CUPS kicking in and taking over the print jobs for that share, we need to set + <smbconfoption name="printing">sysv</smbconfoption> and + <smbconfoption name="printcap">lpstat</smbconfoption>. + </para> + </sect2> +</sect1> + +<sect1> + <title>Advanced Configuration</title> + + <para> + Before we delve into all the configuration options, let us clarify a few + points. <emphasis>Network printing needs to be organized and setup + correctly</emphasis>. This frequently doesn't happen. Legacy systems + or small business LAN environments often lack design and good housekeeping. + </para> + + + <sect2> + <title>Central Spooling vs. <quote>Peer-to-Peer</quote> Printing</title> + + + <para> +<indexterm><primary>spooling</primary><secondary>central</secondary></indexterm> +<indexterm><primary>spooling</primary><secondary>peer-to-peer</secondary></indexterm> + Many small office or home networks, as well as badly organized larger + environments, allow each client a direct access to available network + printers. This is generally a bad idea. It often blocks one client's + access to the printer when another client's job is printing. It might + freeze the first client's application while it is waiting to get + rid of the job. Also, there are frequent complaints about various jobs + being printed with their pages mixed with each other. A better concept + is the usage of a print server: it routes all jobs through one + central system, which responds immediately, takes jobs from multiple + concurrent clients at the same time, and in turn transfers them to the + printer(s) in the correct order. + </para> + </sect2> + + <sect2> + <title>Raw Print Serving &smbmdash; Vendor Drivers on Windows Clients</title> + + + <para> + <indexterm><primary>spooling-only</primary></indexterm> + <indexterm><primary>"raw" printing</primary></indexterm> + Most traditionally configured UNIX print servers acting on behalf of + Samba's Windows clients represented a really simple setup. Their only + task was to manage the <quote>raw</quote> spooling of all jobs handed to them by + Samba. This approach meant that the Windows clients were expected to + prepare the print job file that its ready to be sent to the printing + device. Here a native (vendor-supplied) Windows printer driver needs to + be installed on each and every client for the target device. + </para> + + <para> + It is possible to configure CUPS, Samba and your Windows clients in the + same traditional and simple way. When CUPS printers are configured + for RAW print-through mode operation, it is the responsibility of the + Samba client to fully render the print job (file). The file must be + sent in a format that is suitable for direct delivery to the + printer. Clients need to run the vendor-provided drivers to do + this. In this case, CUPS will not do any print file format conversion + work. + </para> + + <para> + The easiest printing configuration possible is to use raw print-through. + This is achieved by installation of the printer as if it was physically + attached to the Windows client. You then redirect output to a raw network + print queue. The following procedure may be followed to achieve this: + </para> + + <procedure> + <step><para> + Edit <filename>/etc/cups/mime.types</filename> to uncomment the line + near the end of the file that has: +<screen> +#application/octet-... +</screen> + </para></step> + + <step><para> + Do the same for the file <filename>/etc/cups/mime.convs</filename>. + </para></step> + + <step><para> + Add a raw printer using the Web interface. Point your browser at + <constant>http://localhost:631</constant>. Enter Administration, add + the printer following the prompts. Do not install any drivers for it. + Choose Raw. Choose queue name <constant>Raw Queue</constant>. + </para></step> + + <step><para> + In the &smb.conf; file <constant>[printers]</constant> section add + <smbconfoption name="use client driver">Yes</smbconfoption>, + and in the <constant>[global]</constant> section add + <smbconfoption name="printing">CUPS</smbconfoption>, plus + <smbconfoption name="printcap">CUPS</smbconfoption>. + </para></step> + + <step><para> + Install the printer as if it is a local printer. i.e.: Printing to <constant>LPT1:</constant>. + </para></step> + + <step><para> + Edit the configuration under the <guimenu>Detail</guimenu> tab, create a + <constant>local port</constant> that points to the raw printer queue that + you have configured above. Example: <constant>\\server\raw_q</constant>. + Here, the name <constant>raw_q</constant> is the name you gave the print + queue in the CUPS environment. + </para></step> + </procedure> + + </sect2> + + <sect2> + <title>Installation of Windows Client Drivers</title> + + <para> + The printer drivers on the Windows clients may be installed + in two functionally different ways: + </para> + + <itemizedlist> + <listitem><para>Manually install the drivers locally on each client, + one by one; this yields the old <emphasis>LanMan</emphasis> style + printing and uses a <filename>\\sambaserver\printershare</filename> + type of connection.</para></listitem> + + + <listitem><para> + <indexterm><primary>point 'n' print</primary></indexterm> + Deposit and prepare the drivers (for later download) on + the print server (Samba); this enables the clients to use + <quote>Point'n'Print</quote> to get drivers semi-automatically installed the + first time they access the printer; with this method NT/200x/XP + clients use the <emphasis>SPOOLSS/MS-RPC</emphasis> + type printing calls.</para></listitem> + </itemizedlist> + + <para> + The second method is recommended for use over the first. + </para> + </sect2> + + <sect2 id="cups-raw"> + <title>Explicitly Enable <quote>raw</quote> Printing for <emphasis>application/octet-stream</emphasis></title> + + + <para> + <indexterm><primary>application/octet-stream</primary></indexterm> + <indexterm><primary>raw printing</primary></indexterm> + <indexterm><primary>MIME</primary><secondary>raw</secondary></indexterm> + If you use the first option (drivers are installed on the client + side), there is one setting to take care of: CUPS needs to be told + that it should allow <quote>raw</quote> printing of deliberate (binary) file + formats. The CUPS files that need to be correctly set for RAW mode + printers to work are: + </para> + + <itemizedlist> + <listitem><para><filename>/etc/cups/mime.types</filename></para></listitem> + <listitem><para><filename>/etc/cups/mime.convs</filename></para></listitem> + </itemizedlist> + + <para> + Both contain entries (at the end of the respective files) which must + be uncommented to allow RAW mode operation. + In <filename>/etc/cups/mime.types</filename>, make sure this line is + present: + + <programlisting> + application/octet-stream + </programlisting> + + <indexterm><primary>/etc/cups/mime.convs</primary></indexterm> + <indexterm><primary>/etc/cups/mime.types</primary></indexterm> + + In <filename>/etc/cups/mime.convs</filename>, + have this line: + + <indexterm><primary>application/vnd.cups-raw</primary></indexterm> + + <programlisting> + application/octet-stream application/vnd.cups-raw 0 - + </programlisting> + + If these two files are not set up correctly for raw Windows client + printing, you may encounter the dreaded <computeroutput>Unable to + convert file 0</computeroutput> in your CUPS error_log file. + </para> + + <note><para>Editing the <filename>mime.convs</filename> and the + <filename>mime.types</filename> file does not + <emphasis>enforce</emphasis> <quote>raw</quote> printing, it only + <emphasis>allows</emphasis> it. + </para></note> + + <formalpara><title>Background</title> + + + <para> + <indexterm><primary>application/octet-stream</primary></indexterm> + CUPS being a more security-aware printing system than traditional ones + does not by default allow a user to send deliberate (possibly binary) + data to printing devices. This could be easily abused to launch a + <quote>Denial of Service</quote> attack on your printer(s), causing at least + the loss of a lot of paper and ink. <quote>Unknown</quote> data are tagged by CUPS + as <parameter>MIME type: application/octet-stream</parameter> and not + allowed to go to the printer. By default, you can only send other + (known) MIME types <quote>raw</quote>. Sending data <quote>raw</quote> means that CUPS does not + try to convert them and passes them to the printer untouched (see the next + chapter for even more background explanations). + </para> + </formalpara> + + <para> + This is all you need to know to get the CUPS/Samba combo printing + <quote>raw</quote> files prepared by Windows clients, which have vendor drivers + locally installed. If you are not interested in background information about + more advanced CUPS/Samba printing, simply skip the remaining sections + of this chapter. + </para> + </sect2> + + <sect2> + <title>Driver Upload Methods</title> + + <para> + This section describes three familiar methods, plus one new one, by which + printer drivers may be uploaded. + </para> + + <para> + <indexterm><primary>point 'n' print</primary></indexterm> + If you want to use the MS-RPC type printing, you must upload the + drivers onto the Samba server first (<smbconfsection name="[print$]"/> + share). For a discussion on how to deposit printer drivers on the + Samba host (so the Windows clients can download and use them via + <quote>Point'n'Print</quote>), please refer to the previous chapter of this + HOWTO Collection. There you will find a description or reference to + three methods of preparing the client drivers on the Samba server: + </para> + <itemizedlist> + <listitem><para> + <indexterm><primary>add printer wizard</primary></indexterm> + The GUI, <quote>Add Printer Wizard</quote> + <emphasis>upload-from-a-Windows-client</emphasis> + method.</para></listitem> + + <listitem><para>The command line, <quote>smbclient/rpcclient</quote> + upload-from-a-UNIX-workstation method.</para></listitem> + + + <listitem><para> + <indexterm><primary>imprints</primary></indexterm> + The Imprints Toolset + method.</para></listitem> + </itemizedlist> + + <para> + These three methods apply to CUPS all the same. A new and more + convenient way to load the Windows drivers into Samba is provided + if you use CUPS: + </para> + + + <itemizedlist> + <listitem><para> + <indexterm><primary>cupsaddsmb</primary></indexterm> + the <parameter>cupsaddsmb</parameter> + utility.</para></listitem> + </itemizedlist> + + <para> + <command>cupsaddsmb</command> is discussed in much detail further below. But we first + explore the CUPS filtering system and compare the Windows and UNIX printing architectures. + </para> + </sect2> +</sect1> + +<sect1> + <title>Advanced Intelligent Printing with PostScript Driver Download</title> + + + <para> + <indexterm><primary>PostScript</primary><seealso>Ghostscript</seealso></indexterm> + We now know + how to set up a <quote>dump</quote> printserver, that is, a server which is spooling + print-jobs <quote>raw</quote>, leaving the print data untouched. + </para> + + <para> + Possibly you need to setup CUPS in a smarter way. The reasons could + be manifold: + </para> + + <itemizedlist> + <listitem><para>Maybe your boss wants to get monthly statistics: Which + printer did how many pages? What was the average data size of a job? + What was the average print run per day? What are the typical hourly + peaks in printing? Which department prints how much?</para></listitem> + + <listitem><para>Maybe you are asked to setup a print quota system: + Users should not be able to print more jobs, once they have surpassed + a given limit per period.</para></listitem> + + <listitem><para>Maybe your previous network printing setup is a mess + and must be re-organized from a clean beginning.</para></listitem> + + <listitem><para>Maybe you have experiencing too many <quote>blue screens</quote> + originating from poorly debugged printer drivers running in NT <quote>kernel mode</quote>?</para></listitem> + </itemizedlist> + + <para> + These goals cannot be achieved by a raw print server. To build a + server meeting these requirements, you'll first need to learn about + how CUPS works and how you can enable its features. + </para> + + <para> + What follows is the comparison of some fundamental concepts for + Windows and UNIX printing; then follows a description of the + CUPS filtering system, how it works and how you can tweak it. + </para> + + <sect2 id="gdipost"> + <title>GDI on Windows -- PostScript on UNIX</title> + + + <para> + <indexterm><primary>GDI</primary></indexterm> + <indexterm><primary>PostScript</primary></indexterm> + Network printing is one of the most complicated and error-prone + day-to-day tasks any user or administrator may encounter. This is + true for all OS platforms. And there are reasons for this. + </para> + + + <para> + <indexterm><primary>PCL</primary></indexterm> + <indexterm><primary>PDL</primary></indexterm> + You can't expect most file formats to just throw them toward + printers and they get printed. There needs to be a file format + conversion in between. The problem is that there is no common standard for + print file formats across all manufacturers and printer types. While + PostScript (trademark held by Adobe) and, to an + extent, PCL (trademark held by HP) have developed + into semi-official <quote>standards</quote> by being the most widely used PDLs + Page Description Languages (PDLs), there are still + many manufacturers who <quote>roll their own</quote> (their reasons may be + unacceptable license fees for using printer-embedded PostScript + interpreters, and so on). + </para> + </sect2> + + <sect2> + <title>Windows Drivers, GDI and EMF</title> + + + <para> + <indexterm><primary>GDI</primary></indexterm> + <indexterm><primary>EMF</primary></indexterm> + <indexterm><primary>WYSIWYG</primary></indexterm> + In Windows OS, the format conversion job is done by the printer + drivers. On MS Windows OS platforms all application programmers have + at their disposal a built-in API, the Graphical Device + Interface (GDI), as part and parcel of the OS itself to base + themselves on. This GDI core is used as one common unified ground for + all Windows programs to draw pictures, fonts and documents + <emphasis>on screen</emphasis> as well as <emphasis>on + paper</emphasis> (print). Therefore, printer driver developers can + standardize on a well-defined GDI output for their own driver + input. Achieving WYSIWYG (<quote>What You See Is What You Get</quote>) is + relatively easy, because the on-screen graphic primitives, as well as + the on-paper drawn objects, come from one common source. This source, + the GDI, often produces a file format called Enhanced + MetaFile (EMF). The EMF is processed by the printer driver and + converted to the printer-specific file format. + </para> + + <note><para> + <indexterm><primary>PDF</primary></indexterm> + To the GDI foundation in MS Windows, Apple has chosen to + put paper and screen output on a common foundation for their + (BSD-UNIX-based, did you know?) Mac OS X and Darwin Operating + <indexterm><primary>X Window System</primary></indexterm> + <indexterm><primary>PostScript</primary></indexterm> + <indexterm><primary>PCL</primary></indexterm> + <indexterm><primary>Xprint</primary></indexterm> + Systems. Their <emphasis>Core Graphic Engine</emphasis> uses a + <emphasis>PDF</emphasis> derivative for all display work. + </para></note> + + <para> + + <image> + <imagedescription>Windows printing to a local printer.</imagedescription> + <imagefile>1small</imagefile> + </image> + </para> + </sect2> + + <sect2> + <title>UNIX Printfile Conversion and GUI Basics</title> + + + <para> + <indexterm><primary>X Window System</primary></indexterm> + <indexterm><primary>PostScript</primary></indexterm> + <indexterm><primary>PCL</primary></indexterm> + <indexterm><primary>Xprint</primary></indexterm> + In UNIX and Linux, there is no comparable layer built into the OS + kernel(s) or the X (screen display) server. Every application is + responsible for itself to create its print output. Fortunately, most + use PostScript and that at least gives some common ground. Unfortunately, + there are many different levels of quality for this PostScript. And + worse, there is a huge difference (and no common root) in the way + the same document is displayed on screen and how it is presented on + paper. WYSIWYG is more difficult to achieve. This goes back to the + time, decades ago, when the predecessors of X.org, + designing the UNIX foundations and protocols for Graphical User + Interfaces, refused to take responsibility for <quote>paper output</quote> + also, as some had demanded at the time, and restricted itself to + <quote>on-screen only.</quote> (For some years now, the <quote>Xprint</quote> project has been + under development, attempting to build printing support into the X + framework, including a PostScript and a PCL driver, but it is not yet + ready for prime time.) You can see this unfavorable inheritance up to + the present day by looking into the various <quote>font</quote> directories on your + system; there are separate ones for fonts used for X display and fonts + to be used on paper. + </para> + + <formalpara> + <title>Background</title> + + + <para> + <indexterm><primary>PostScript</primary></indexterm> + The PostScript programming language is an <quote>invention</quote> by Adobe Inc., + but its specifications have been published to the full. Its strength + lies in its powerful abilities to describe graphical objects (fonts, + shapes, patterns, lines, curves, and dots), their attributes (color, + linewidth) and the way to manipulate (scale, distort, rotate, + shift) them. Because of its open specification, anybody with the + skill can start writing his own implementation of a PostScript + interpreter and use it to display PostScript files on screen or on + paper. Most graphical output devices are based on the concept of + <quote>raster images</quote> or <quote>pixels</quote> (one notable exception is pen + plotters). Of course, you can look at a PostScript file in its textual + form and you will be reading its PostScript code, the language + instructions which need to be interpreted by a rasterizer. Rasterizers + produce pixel images, which may be displayed on screen by a viewer + program or on paper by a printer. + </para> + </formalpara> + </sect2> + + <sect2 id="post-and-ghost"> + <title>PostScript and Ghostscript</title> + + + <para> + <indexterm><primary>PostScript</primary></indexterm> + <indexterm><primary>GhostScript</primary><seealso>PostScript</seealso></indexterm> + <indexterm><primary>PostScript</primary><secondary>RIP</secondary></indexterm> + So, UNIX is lacking a common ground for printing on paper and + displaying on screen. Despite this unfavorable legacy for UNIX, basic + printing is fairly easy if you have PostScript printers at your + disposal. The reason is these devices have a built-in PostScript + language <quote>interpreter,</quote> also called a Raster Image + Processor (RIP) (which makes them more expensive than + other types of printers); throw PostScript toward them, and they will + spit out your printed pages. Their RIP is doing all the hard work of + converting the PostScript drawing commands into a bitmap picture as + you see it on paper, in a resolution as done by your printer. This is + no different to PostScript printing a file from a Windows origin. + </para> + + <note><para> + <indexterm><primary>PPD</primary></indexterm> + Traditional UNIX programs and printing systems &smbmdash; while + using PostScript &smbmdash; are largely not PPD-aware. PPDs are <quote>PostScript + Printer Description</quote> files. They enable you to specify and control all + options a printer supports: duplexing, stapling and punching. Therefore, + UNIX users for a long time couldn't choose many of the supported + device and job options, unlike Windows or Apple users. But now there + is CUPS. + </para> + </note> + + <para> + <image> + <imagedescription>Printing to a PostScript printer.</imagedescription> + <imagefile>2small</imagefile> + </image> + </para> + + + <para> + <indexterm><primary>PDL</primary></indexterm> + However, there are other types of printers out there. These do not know + how to print PostScript. They use their own Page Description + Language (PDL, often proprietary). To print to them is much + more demanding. Since your UNIX applications mostly produce + PostScript, and since these devices do not understand PostScript, you + need to convert the print files to a format suitable for your printer + on the host before you can send it away. + </para> + </sect2> + + <sect2> + <title>Ghostscript &smbmdash; the Software RIP for Non-PostScript Printers</title> + + + <para> + <indexterm><primary>GhostScript</primary></indexterm> + Here is where Ghostscript kicks in. Ghostscript is + the traditional (and quite powerful) PostScript interpreter used on + UNIX platforms. It is a RIP in software, capable of doing a + <emphasis>lot</emphasis> of file format conversions for a very broad + spectrum of hardware devices as well as software file formats. + Ghostscript technology and drivers are what enable PostScript printing + to non-PostScript hardware. + </para> + + <para> + <image><imagedescription>Ghostscript as a RIP for non-postscript printers.</imagedescription> + <imagefile>3small</imagefile> + </image> + </para> + + <tip><para> + Use the <quote>gs -h</quote> command to check for all built-in <quote>devices</quote> + of your Ghostscript version. If you specify a parameter of + <parameter>-sDEVICE=png256</parameter> on your Ghostscript command + line, you are asking Ghostscript to convert the input into a PNG + file. Naming a <quote>device</quote> on the command line is the most important + single parameter to tell Ghostscript exactly how it should render the + input. New Ghostscript versions are released at fairly regular + intervals, now by artofcode LLC. They are initially put under the + <quote>AFPL</quote> license, but re-released under the GNU GPL as soon as the next + AFPL version appears. GNU Ghostscript is probably the version + installed on most Samba systems. But it has some deficiencies. + <indexterm><primary>Ghostscript</primary><secondary>ESP</secondary><see>ESP GhostScript</see></indexterm> + Therefore, ESP Ghostscript was developed as an + enhancement over GNU Ghostscript, with lots of bug-fixes, additional + devices and improvements. It is jointly maintained by developers from + CUPS, Gimp-Print, MandrakeSoft, SuSE, Red Hat, and Debian. It includes + the <quote>cups</quote> device (essential to print to non-PS printers from CUPS). + </para></tip> + </sect2> + + <sect2> + <title>PostScript Printer Description (PPD) Specification</title> + + + <para> + <indexterm><primary>PPD</primary></indexterm> + While PostScript in essence is a Page Description + Language (PDL) to represent the page layout in a + device-independent way, real-world print jobs are + always ending up being output on hardware with device-specific + features. To take care of all the differences in hardware and to + allow for innovations, Adobe has specified a syntax and file format + for PostScript Printer Description (PPD) + files. Every PostScript printer ships with one of these files. + </para> + + <para> + PPDs contain all the information about general and special features of the + given printer model: Which different resolutions can it handle? Does + it have a Duplexing Unit? How many paper trays are there? What media + types and sizes does it take? For each item, it also names the special + command string to be sent to the printer (mostly inside the PostScript + file) in order to enable it. + </para> + + <para> + Information from these PPDs is meant to be taken into account by the + printer drivers. Therefore, installed as part of the Windows + PostScript driver for a given printer is the printer's PPD. Where it + makes sense, the PPD features are presented in the drivers' UI dialogs + to display to the user a choice of print options. In the end, the + user selections are somehow written (in the form of special + PostScript, PJL, JCL or vendor-dependent commands) into the PostScript + file created by the driver. + </para> + + <warning><para> + <indexterm><primary>PDF</primary></indexterm> + A PostScript file that was created to contain device-specific commands + for achieving a certain print job output (e.g., duplex-ed, stapled and + punched) on a specific target machine, may not print as expected, or + may not be printable at all on other models; it also may not be fit + for further processing by software (e.g., by a PDF distilling program). + </para></warning> + </sect2> + + <sect2> + <title>Using Windows-Formatted Vendor PPDs</title> + + <para> + CUPS can handle all spec-compliant PPDs as supplied by the + manufacturers for their PostScript models. Even if a + vendor might not have mentioned our favorite + OS in his manuals and brochures, you can safely trust this: + <emphasis>If you get the Windows NT version of the PPD, you + can use it unchanged in CUPS</emphasis> and thus access the full + power of your printer just like a Windows NT user could! + </para> + + <tip><para> + To check the spec compliance of any PPD online, go to <ulink + noescape="1" url="http://www.cups.org/testppd.php">http://www.cups.org/testppd.php</ulink> + and upload your PPD. You will see the results displayed + immediately. CUPS in all versions after 1.1.19 has a much more strict + internal PPD parsing and checking code enabled; in case of printing + trouble, this online resource should be one of your first pit-stops. + </para></tip> + + <warning><para> + <indexterm><primary>foomatic</primary></indexterm> + <indexterm><primary>cupsomatic</primary></indexterm> + For real PostScript printers, <emphasis>do not</emphasis> use the + <emphasis>Foomatic</emphasis> or <emphasis>cupsomatic</emphasis> + PPDs from Linuxprinting.org. With these devices, the original + vendor-provided PPDs are always the first choice! + </para></warning> + + <tip><para> + If you are looking for an original vendor-provided PPD of a specific + device, and you know that an NT4 box (or any other Windows box) on + your LAN has the PostScript driver installed, just use + <command>smbclient //NT4-box/print\$ -U username</command> to + access the Windows directory where all printer driver files are + stored. First look in the <filename>W32X86/2</filename> subdir for + the PPD you are seeking. + </para></tip> + </sect2> + + <sect2> + <title>CUPS Also Uses PPDs for Non-PostScript Printers</title> + + <para> + CUPS also uses specially crafted PPDs to handle non-PostScript + printers. These PPDs are usually not available from the vendors (and + no, you can't just take the PPD of a PostScript printer with the same + model name and hope it works for the non-PostScript version too). To + understand how these PPDs work for non-PS printers, we first need to + dive deeply into the CUPS filtering and file format conversion + architecture. Stay tuned. + </para> + </sect2> +</sect1> + +<sect1> +<title>The CUPS Filtering Architecture</title> + +<para> +The core of the CUPS filtering system is based on +Ghostscript. In addition to Ghostscript, CUPS +uses some other filters of its own. You (or your OS vendor) may have +plugged in even more filters. CUPS handles all data file formats under +the label of various MIME types. Every incoming +printfile is subjected to an initial +auto-typing. The auto-typing determines its given +MIME type. A given MIME type implies zero or more possible filtering +chains relevant to the selected target printer. This section discusses +how MIME types recognition and conversion rules interact. They are +used by CUPS to automatically setup a working filtering chain for any +given input data format. +</para> + +<para> +If CUPS rasterizes a PostScript file natively to +a bitmap, this is done in two stages: +</para> + +<itemizedlist> + <listitem><para>The first stage uses a Ghostscript device named <quote>cups</quote> +(this is since version 1.1.15) and produces a generic raster format +called <quote>CUPS raster</quote>. +</para></listitem> + +<listitem><para>The second stage uses a <quote>raster driver</quote> that converts + the generic CUPS raster to a device-specific raster.</para></listitem> +</itemizedlist> + +<para> +Make sure your Ghostscript version has the <quote>cups</quote> device compiled in +(check with <command>gs -h | grep cups</command>). Otherwise you +may encounter the dreaded <computeroutput>Unable to convert file +0</computeroutput> in your CUPS error_log file. To have <quote>cups</quote> as a +device in your Ghostscript, you either need to patch GNU +Ghostscript and re-compile, or use <indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm><ulink +url="http://www.cups.org/ghostscript.php">ESP Ghostscript</ulink>. The +superior alternative is ESP Ghostscript. It supports not just CUPS, +but 300 other devices too (while GNU Ghostscript supports only about +180). Because of this broad output device support, ESP Ghostscript is +the first choice for non-CUPS spoolers, too. It is now recommended by +Linuxprinting.org for all spoolers. +</para> + +<para> +<indexterm><primary>cupsomatic</primary></indexterm> +<indexterm><primary>foomatic</primary></indexterm> +CUPS printers may be setup to use external rendering paths. One of the most common is provided by the +Foomatic/cupsomatic concept from <ulink url="http://www.linuxprinting.org/">Linuxprinting.org.</ulink> This +uses the classical Ghostscript approach, doing everything in one step. +It does not use the <quote>cups</quote> device, but one of the many +others. However, even for Foomatic/cupsomatic usage, best results and +<indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm> +broadest printer model support is provided by ESP Ghostscript (more +about cupsomatic/Foomatic, particularly the new version called now +<emphasis>foomatic-rip</emphasis>, follows below). +</para> + +<sect2> +<title>MIME Types and CUPS Filters</title> + + +<para> +<indexterm><primary>MIME</primary><secondary>filters</secondary></indexterm> + <indexterm><primary>MIME</primary></indexterm> +CUPS reads the file <filename>/etc/cups/mime.types</filename> +(and all other files carrying a <filename>*.types</filename> suffix +in the same directory) upon startup. These files contain the MIME +type recognition rules that are applied when CUPS runs its +auto-typing routines. The rule syntax is explained in the man page +for <filename>mime.types</filename> and in the comments section of the +<filename>mime.types</filename> file itself. A simple rule reads +like this: + +<indexterm><primary>application/pdf</primary></indexterm> +<programlisting> + application/pdf pdf string(0,%PDF) +</programlisting> + +This means if a filename has either a +<filename>.pdf</filename> suffix or if the magic +string <emphasis>%PDF</emphasis> is right at the +beginning of the file itself (offset 0 from the start), then it is +a PDF file (<parameter>application/pdf</parameter>). +Another rule is this: + +<programlisting> + application/postscript ai eps ps string(0,%!) string(0,<04>%!) +</programlisting> + +If the filename has one of the suffixes +<filename>.ai</filename>, <filename>.eps</filename>, +<filename>.ps</filename> or if the file itself starts with one of the +strings <emphasis>%!</emphasis> or <emphasis><![CDATA[<04>%!]]></emphasis>, it +is a generic PostScript file +(<parameter>application/postscript</parameter>). +</para> + +<warning><para> +Don't confuse the other mime.types files your system might be using +with the one in the <filename>/etc/cups/</filename> directory. +</para></warning> + +<note><para> +There is an important difference between two similar MIME types in +CUPS: one is <parameter>application/postscript</parameter>, the other is +<parameter>application/vnd.cups-postscript</parameter>. While +<parameter>application/postscript</parameter> is meant to be device +independent (job options for the file are still outside the PS file +content, embedded in command line or environment variables by CUPS), +<parameter>application/vnd.cups-postscript</parameter> may have the job +options inserted into the PostScript data itself (where +applicable). The transformation of the generic PostScript +(<parameter>application/postscript</parameter>) to the device-specific version +(<parameter>application/vnd.cups-postscript</parameter>) is the responsibility of the +CUPS <parameter>pstops</parameter> filter. pstops uses information +contained in the PPD to do the transformation. +</para></note> + +<para> +CUPS can handle ASCII text, HP-GL, PDF, PostScript, DVI, and +many image formats (GIF. PNG, TIFF, JPEG, Photo-CD, SUN-Raster, +PNM, PBM, SGI-RGB, and more) and their associated MIME types +with its filters. +</para> +</sect2> + +<sect2> +<title>MIME Type Conversion Rules</title> + + +<para> +<indexterm><primary>MIME</primary></indexterm> +<indexterm><primary>application/pdf</primary></indexterm> +CUPS reads the file <filename>/etc/cups/mime.convs</filename> +(and all other files named with a <filename>*.convs</filename> +suffix in the same directory) upon startup. These files contain +lines naming an input MIME type, an output MIME type, a format +conversion filter that can produce the output from the input type +and virtual costs associated with this conversion. One example line +reads like this: + +<programlisting> + application/pdf application/postscript 33 pdftops +</programlisting> + +This means that the <parameter>pdftops</parameter> filter will take +<parameter>application/pdf</parameter> as input and produce +<parameter>application/postscript</parameter> as output; the virtual +cost of this operation is 33 CUPS-$. The next filter is more +expensive, costing 66 CUPS-$: + +<indexterm><primary>pdf</primary></indexterm> + +<programlisting> + application/vnd.hp-HPGL application/postscript 66 hpgltops +</programlisting> + +This is the <parameter>hpgltops</parameter>, which processes HP-GL +plotter files to PostScript. + +<indexterm><primary>application/octet-stream</primary></indexterm> + +<programlisting> + application/octet-stream +</programlisting> + +Here are two more examples: + +<indexterm><primary>text/plain</primary></indexterm> + +<programlisting> + application/x-shell application/postscript 33 texttops + text/plain application/postscript 33 texttops +</programlisting> + +The last two examples name the <parameter>texttops</parameter> filter +to work on <parameter>text/plain</parameter> as well as on <parameter>application/x-shell</parameter>. (Hint: +This differentiation is needed for the syntax highlighting feature of +<parameter>texttops</parameter>). +</para> +</sect2> + +<sect2> +<title>Filtering Overview</title> + + +<para> +<indexterm><primary>MIME</primary></indexterm> +There are many more combinations named in <filename>mime.convs</filename>. However, you +are not limited to use the ones pre-defined there. You can plug in any +filter you like into the CUPS framework. It must meet, or must be made +to meet, some minimal requirements. If you find (or write) a cool +conversion filter of some kind, make sure it complies to what CUPS +needs and put in the right lines in <filename>mime.types</filename> +and <filename>mime.convs</filename>, then it will work seamlessly +inside CUPS. +</para> + +<sect3> +<title>Filter requirements</title> +<para> +The mentioned <quote>CUPS requirements</quote> for filters are simple. Take +filenames or <filename>stdin</filename> as input and write to +<filename>stdout</filename>. They should take these 5 or 6 arguments: +<emphasis>printer job user title copies options [filename]</emphasis> +</para> + +<variablelist> +<varlistentry><term>Printer </term> +<listitem><para>The name of the printer queue (normally this is the +name of the filter being run).</para></listitem> +</varlistentry> + +<varlistentry><term>job </term> +<listitem><para>The numeric job ID for the job being +printed.</para></listitem> +</varlistentry> + +<varlistentry><term>user </term> +<listitem><para>The string from the originating-user-name +attribute.</para></listitem> +</varlistentry> + +<varlistentry><term>title </term> +<listitem><para>The string from the job-name attribute.</para></listitem> +</varlistentry> + +<varlistentry><term>copies </term> +<listitem><para>The numeric value from the number-copies +attribute.</para></listitem> +</varlistentry> + +<varlistentry><term>options </term> +<listitem><para>The job options.</para></listitem> +</varlistentry> + +<varlistentry><term>filename </term> +<listitem><para>(Optionally) The print request file (if missing, +filters expected data fed through <filename>stdin</filename>). In most +cases, it is easy to write a simple wrapper script around existing +filters to make them work with CUPS.</para></listitem> +</varlistentry> +</variablelist> +</sect3> +</sect2> + +<sect2> +<title>Prefilters</title> + + +<para> +<indexterm><primary>PostScript</primary></indexterm> +As previously stated, PostScript is the central file format to any UNIX-based +printing system. From PostScript, CUPS generates raster data to feed +non-PostScript printers. +</para> + +<para> +But what happens if you send one of the supported non-PS formats +to print? Then CUPS runs <quote>pre-filters</quote> on these input formats to +generate PostScript first. There are pre-filters to create PS from +ASCII text, PDF, DVI, or HP-GL. The outcome of these filters is always +of MIME type <parameter>application/postscript</parameter> (meaning that +any device-specific print options are not yet embedded into the +PostScript by CUPS, and that the next filter to be called is +pstops). Another pre-filter is running on all supported image formats, +the <parameter>imagetops</parameter> filter. Its outcome is always of +MIME type <parameter>application/vnd.cups-postscript</parameter> +(not application/postscript), meaning it has the +print options already embedded into the file. +</para> + +<para> + <image> + <imagedescription>Pre-filtering in CUPS to form PostScript.</imagedescription> + <imagefile scale="25">4small</imagefile> + </image> +</para> +</sect2> + +<sect2> +<title>pstops</title> + +<para> +<emphasis>pstops</emphasis> is the filter to convert +<parameter>application/postscript</parameter> to <?latex \linebreak ?> +<parameter>application/vnd.cups-postscript</parameter>. It was said +above that this filter inserts all device-specific print options +(commands to the printer to ask for the duplexing of output, or +stapling and punching it, and so on) into the PostScript file. +</para> + +<para> + <image><imagedescription>Adding device-specific print options.</imagedescription> + <imagefile scale="25">5small</imagefile> + </image> +</para> + +<para> +This is not all. Other tasks performed by it are: +</para> + +<itemizedlist> +<listitem><para> +Selecting the range of pages to be printed (if you choose to +print only pages <quote>3, 6, 8-11, 16, 19-21</quote>, or only the odd numbered +ones). +</para></listitem> + +<listitem><para> +Putting 2 or more logical pages on one sheet of paper (the +so-called <quote>number-up</quote> function). +</para></listitem> + +<listitem><para>Counting the pages of the job to insert the accounting +information into the <filename>/var/log/cups/page_log</filename>. +</para></listitem> +</itemizedlist> +</sect2> + +<sect2> +<title>pstoraster</title> + +<para> +<parameter>pstoraster</parameter> is at the core of the CUPS filtering +system. It is responsible for the first stage of the rasterization +process. Its input is of MIME type application/vnd.cups-postscript; +its output is application/vnd.cups-raster. This output format is not +yet meant to be printable. Its aim is to serve as a general purpose +input format for more specialized <emphasis>raster drivers</emphasis> +that are able to generate device-specific printer data. +</para> + +<para> + <image> + <imagedescription>PostScript to intermediate raster format.</imagedescription> + <imagefile scale="25">6small</imagefile> + </image> +</para> + +<para> +CUPS raster is a generic raster format with powerful features. It is +able to include per-page information, color profiles, and more, to be +used by the following downstream raster drivers. Its MIME type is +registered with IANA and its specification is, of course, completely +open. It is designed to make it quite easy and inexpensive for +manufacturers to develop Linux and UNIX raster drivers for their +printer models, should they choose to do so. CUPS always takes care +for the first stage of rasterization so these vendors do not need to care +about Ghostscript complications (in fact, there is currently more +than one vendor financing the development of CUPS raster drivers). +</para> + +<para> + <image> + <imagedescription>CUPS-raster production using Ghostscript.</imagedescription> + <imagefile>7small</imagefile> + </image> +</para> + +<para> +CUPS versions before version 1.1.15 were shipping a binary (or source +code) standalone filter, named <parameter>pstoraster</parameter>. <parameter>pstoraster</parameter> was derived +from GNU Ghostscript 5.50, and could be installed besides and in +addition to any GNU or AFPL Ghostscript package without conflicting. +</para> + +<para> +>From version 1.1.15, this has changed. The functions for this have been +integrated back into Ghostscript (now based on GNU Ghostscript version +7.05). The <parameter>pstoraster</parameter> filter is now a simple shell script calling +<command>gs</command> with the <command>-sDEVICE=cups</command> +parameter. If your Ghostscript does not show a success on asking for +<command>gs -h |grep cups</command>, you might not be able to +print. Update your Ghostscript. +</para> +</sect2> + +<sect2> +<title>imagetops and imagetoraster</title> + +<para> +In the section about pre-filters, we mentioned the pre-filter +that generates PostScript from image formats. The <parameter>imagetoraster</parameter> +filter is used to convert directly from image to raster, without the +intermediate PostScript stage. It is used more often than the above +mentioned pre-filters. We summarize flowchart of image file +filtering on <link linkend="small8">next picture</link>. +</para> + +<para> + <image id="small8"> + <imagedescription>Image format to CUPS-raster format conversion.</imagedescription> + <imagefile>8small</imagefile> + </image> +</para> + +</sect2> + +<sect2> +<title>rasterto [printers specific]</title> + +<para> +CUPS ships with quite different raster drivers processing CUPS +raster. On my system I find in /usr/lib/cups/filter/ these: +<parameter>rastertoalps</parameter>, <parameter>rastertobj</parameter>, <parameter>rastertoepson</parameter>, <parameter>rastertoescp</parameter>, +<parameter>rastertopcl</parameter>, <parameter>rastertoturboprint</parameter>, <parameter>rastertoapdk</parameter>, <parameter>rastertodymo</parameter>, +<parameter>rastertoescp</parameter>, <parameter>rastertohp</parameter>, and +<parameter>rastertoprinter</parameter>. Don't worry if you have less +than this; some of these are installed by commercial add-ons to CUPS +(like <parameter>rastertoturboprint</parameter>), others (like +<parameter>rastertoprinter</parameter>) by third-party driver +development projects (such as Gimp-Print) wanting to cooperate as +closely as possible with CUPS. +</para> + +<para> + <image id="small9"> + <imagedescription>Raster to printer-specific formats.</imagedescription> + <imagefile>9small</imagefile> + </image> +</para> +</sect2> + +<sect2> +<title>CUPS Backends</title> + +<para> +The last part of any CUPS filtering chain is a backend. Backends +are special programs that send the print-ready file to the final +device. There is a separate backend program for any transfer +protocol of sending print jobs over the network, or for every local +interface. Every CUPS print queue needs to have a CUPS <quote>device-URI</quote> +associated with it. The device URI is the way to encode the backend +used to send the job to its destination. Network device-URIs are using +two slashes in their syntax, local device URIs only one, as you can +see from the following list. Keep in mind that local interface names +may vary much from my examples, if your OS is not Linux: +</para> + +<variablelist> + <varlistentry><term>usb </term> + <listitem><para> + This backend sends print files to USB-connected printers. An + example for the CUPS device-URI to use is: + <filename>usb:/dev/usb/lp0</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>serial </term> + <listitem><para> + This backend sends print files to serially connected printers. + An example for the CUPS device-URI to use is: + <filename>serial:/dev/ttyS0?baud=11500</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>parallel </term> + <listitem><para> + This backend sends print files to printers connected to the + parallel port. An example for the CUPS device-URI to use is: + <filename>parallel:/dev/lp0</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>SCSI </term> + <listitem><para> + This backend sends print files to printers attached to the + SCSI interface. An example for the CUPS device-URI to use is: + <filename>scsi:/dev/sr1</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>lpd </term> + <listitem><para> + This backend sends print files to LPR/LPD connected network + printers. An example for the CUPS device-URI to use is: + <filename>lpd://remote_host_name/remote_queue_name</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>AppSocket/HP JetDirect </term> + <listitem><para> + This backend sends print files to AppSocket (a.k.a. "HP + JetDirect") connected network printers. An example for the CUPS + device-URI to use is: + <filename>socket://10.11.12.13:9100</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>ipp </term> + <listitem><para> + This backend sends print files to IPP connected network + printers (or to other CUPS servers). Examples for CUPS device-URIs + to use are: + <filename>ipp:://192.193.194.195/ipp</filename> + (for many HP printers) or + <filename>ipp://remote_cups_server/printers/remote_printer_name</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>http </term> + <listitem><para> + This backend sends print files to HTTP connected printers. + (The http:// CUPS backend is only a symlink to the ipp:// backend.) + Examples for the CUPS device-URIs to use are: + <filename>http:://192.193.194.195:631/ipp</filename> + (for many HP printers) or + <filename>http://remote_cups_server:631/printers/remote_printer_name</filename>. + </para></listitem></varlistentry> + + <varlistentry><term>smb </term> + <listitem><para> + This backend sends print files to printers shared by a Windows + host. An example for CUPS device-URIs that may be used includes: + </para> + + <para> + <simplelist> + <member><filename>smb://workgroup/server/printersharename</filename></member> + <member><filename>smb://server/printersharename</filename></member> + <member><filename>smb://username:password@workgroup/server/printersharename</filename></member> + <member><filename>smb://username:password@server/printersharename</filename></member> + </simplelist> + </para> + + <para> + The smb:// backend is a symlink to the Samba utility + <parameter>smbspool</parameter> (does not ship with CUPS). If the + symlink is not present in your CUPS backend directory, have your + root user create it: <command>ln -s `which smbspool' + /usr/lib/cups/backend/smb</command>. + </para></listitem></varlistentry> +</variablelist> + +<para> +It is easy to write your own backends as shell or Perl scripts, if you +need any modification or extension to the CUPS print system. One +reason could be that you want to create <quote>special</quote> printers that send +the print-jobs as email (through a <quote>mailto:/</quote> backend), convert them to +PDF (through a <quote>pdfgen:/</quote> backend) or dump them to <quote>/dev/null</quote>. (In +fact I have the system-wide default printer set up to be connected to +a devnull:/ backend: there are just too many people sending jobs +without specifying a printer, or scripts and programs which do not name +a printer. The system-wide default deletes the job and sends a polite +email back to the $USER asking him to always specify the correct +printer name.) +</para> + +<para> +Not all of the mentioned backends may be present on your system or +usable (depending on your hardware configuration). One test for all +available CUPS backends is provided by the <emphasis>lpinfo</emphasis> +utility. Used with the <option>-v</option> parameter, it lists +all available backends: +</para> + +<para><screen> +&prompt;<userinput>lpinfo -v</userinput> +</screen></para> +</sect2> + +<sect2> +<title>The Role of <parameter>cupsomatic/foomatic</parameter></title> + +<para> +<indexterm><primary>cupsomatic</primary></indexterm> +<indexterm><primary>foomatic</primary></indexterm> +<parameter>cupsomatic</parameter> filters may be the most widely used on CUPS +installations. You must be clear about the fact that these were not +developed by the CUPS people. They are a third party add-on to +CUPS. They utilize the traditional Ghostscript devices to render jobs +for CUPS. When troubleshooting, you should know about the +difference. Here the whole rendering process is done in one stage, +inside Ghostscript, using an appropriate device for the target +printer. <parameter>cupsomatic</parameter> uses PPDs that are generated from the Foomatic +Printer & Driver Database at Linuxprinting.org. +</para> + +<para> +You can recognize these PPDs from the line calling the +<parameter>cupsomatic</parameter> filter: + +<programlisting> + *cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" +</programlisting> + +You may find this line among the first 40 or so lines of the PPD +file. If you have such a PPD installed, the printer shows up in the +CUPS Web interface with a <parameter>foomatic</parameter> namepart for +the driver description. <parameter>cupsomatic</parameter> is a Perl script that runs +Ghostscript with all the complicated command line options +auto-constructed from the selected PPD and command line options give to +the print-job. +</para> + +<para> +<indexterm><primary>point 'n' print</primary></indexterm> + However, <parameter>cupsomatic</parameter> is now deprecated. Its PPDs (especially the first +generation of them, still in heavy use out there) are not meeting the +Adobe specifications. You might also suffer difficulties when you try +to download them with <quote>Point'n'Print</quote> to Windows clients. A better +and more powerful successor is now in a stable beta-version: it is called <parameter>foomatic-rip</parameter>. To use +<parameter>foomatic-rip</parameter> as a filter with CUPS, you need the new-type PPDs. These +have a similar but different line: + +<programlisting> + *cupsFilter: "application/vnd.cups-postscript 0 foomatic-rip" +</programlisting> + +The PPD generating engine at Linuxprinting.org has been revamped. +The new PPDs comply to the Adobe spec. On top, they also provide a +new way to specify different quality levels (hi-res photo, normal +color, grayscale, and draft) with a single click, whereas before you +could have required five or more different selections (media type, +resolution, inktype and dithering algorithm). There is support for +custom-size media built in. There is support to switch +print-options from page to page in the middle of a job. And the +best thing is the new foomatic-rip now works seamlessly with all +legacy spoolers too (like LPRng, BSD-LPD, PDQ, PPR and so on), providing +for them access to use PPDs for their printing. +</para> +</sect2> + +<sect2> +<title>The Complete Picture</title> + +<para> +If you want to see an overview of all the filters and how they +relate to each other, the complete picture of the puzzle is at the end +of this document. +</para> +</sect2> + +<sect2> +<title><filename>mime.convs</filename></title> + +<para> +CUPS auto-constructs all possible filtering chain paths for any given +MIME type, and every printer installed. But how does it decide in +favor or against a specific alternative? (There may often be cases +where there is a choice of two or more possible filtering chains for +the same target printer.) Simple. You may have noticed the figures in +the third column of the mime.convs file. They represent virtual costs +assigned to this filter. Every possible filtering chain will sum up to +a total <quote>filter cost.</quote> CUPS decides for the most <quote>inexpensive</quote> route. +</para> + +<tip><para> +The setting of <parameter>FilterLimit 1000</parameter> in +<filename>cupsd.conf</filename> will not allow more filters to +run concurrently than will consume a total of 1000 virtual filter +cost. This is an efficient way to limit the load of any CUPS +server by setting an appropriate <quote>FilterLimit</quote> value. A FilterLimit of +200 allows roughly one job at a time, while a FilterLimit of 1000 allows +approximately five jobs maximum at a time. +</para></tip> +</sect2> + +<sect2> + <title><quote>Raw</quote> Printing</title> + +<para> + You can tell CUPS to print (nearly) any file <quote>raw</quote>. <quote>Raw</quote> means it + will not be filtered. CUPS will send the file to the printer <quote>as is</quote> +without bothering if the printer is able to digest it. Users need to +take care themselves that they send sensible data formats only. Raw +printing can happen on any queue if the <quote><parameter>-o raw</parameter></quote> option is specified +on the command line. You can also set up raw-only queues by simply not +associating any PPD with it. This command: +</para> + +<para><screen> +&prompt;<userinput>lpadmin -P rawprinter -v socket://11.12.13.14:9100 -E</userinput> +</screen></para> + +<para> + sets up a queue named <quote>rawprinter</quote>, connected via the <quote>socket</quote> + protocol (a.k.a. <quote>HP JetDirect</quote>) to the device at IP address +11.12.1.3.14, using port 9100. (If you had added a PPD with +<command>-P /path/to/PPD</command> to this command line, you would +have installed a <quote>normal</quote> print queue. +</para> + +<para> +CUPS will automatically treat each job sent to a queue as a <quote>raw</quote> one, +if it can't find a PPD associated with the queue. However, CUPS will +only send known MIME types (as defined in its own mime.types file) and +refuse others. +</para> +</sect2> + +<sect2> +<title>application/octet-stream Printing</title> + +<para> +Any MIME type with no rule in the +<filename>/etc/cups/mime.types</filename> file is regarded as unknown +or <parameter>application/octet-stream</parameter> and will not be +sent. Because CUPS refuses to print unknown MIME types per default, +you will probably have experienced the fact that print jobs originating +from Windows clients were not printed. You may have found an error +message in your CUPS logs like: +</para> + +<para><computeroutput> + Unable to convert file 0 to printable format for job +</computeroutput></para> + +<para> +To enable the printing of <parameter>application/octet-stream</parameter> files, edit +these two files: +</para> + +<itemizedlist> +<listitem><para><filename>/etc/cups/mime.convs</filename></para></listitem> + +<listitem><para><filename>/etc/cups/mime.types</filename></para></listitem> +</itemizedlist> + +<para> +Both contain entries (at the end of the respective files) which must +be uncommented to allow RAW mode operation for +<parameter>application/octet-stream</parameter>. In <filename>/etc/cups/mime.types</filename> +make sure this line is present: + +<indexterm><primary>application/octet-stream</primary></indexterm> + +<programlisting> +application/octet-stream +</programlisting> + +This line (with no specific auto-typing rule set) makes all files +not otherwise auto-typed a member of <parameter>application/octet-stream</parameter>. In +<filename>/etc/cups/mime.convs</filename>, have this +line: + +<programlisting> +application/octet-stream application/vnd.cups-raw 0 - +</programlisting> + +<indexterm><primary>MIME</primary></indexterm> + +This line tells CUPS to use the <emphasis>Null Filter</emphasis> +(denoted as <quote>-</quote>, doing nothing at all) on +<parameter>application/octet-stream</parameter>, and tag the result as +<parameter>application/vnd.cups-raw</parameter>. This last one is +always a green light to the CUPS scheduler to now hand the file over +to the backend connecting to the printer and sending it over. +</para> + +<note><para>Editing the <filename>mime.convs</filename> and the +<filename>mime.types</filename> file does not +<emphasis>enforce</emphasis> <quote>raw</quote> printing, it only +<emphasis>allows</emphasis> it. +</para></note> + +<formalpara> +<title>Background</title> + +<para> +CUPS being a more security-aware printing system than traditional ones +does not by default allow one to send deliberate (possibly binary) +data to printing devices. (This could be easily abused to launch a +Denial of Service attack on your printer(s), causing at least the loss +of a lot of paper and ink...) <quote>Unknown</quote> data are regarded by CUPS +as <emphasis>MIME type</emphasis> +<emphasis>application/octet-stream</emphasis>. While you +<emphasis>can</emphasis> send data <quote>raw</quote>, the MIME type for these must +be one that is known to CUPS and an allowed one. The file +<filename>/etc/cups/mime.types</filename> defines the <quote>rules</quote> of how CUPS +recognizes MIME types. The file +<filename>/etc/cups/mime.convs</filename> decides which file +conversion filter(s) may be applied to which MIME types. +</para> +</formalpara> +</sect2> + +<sect2> +<title>PostScript Printer Descriptions (PPDs) for Non-PS Printers</title> + + +<para> +<indexterm><primary>PPD</primary></indexterm> +Originally PPDs were meant to be used for PostScript printers +only. Here, they help to send device-specific commands and settings +to the RIP which processes the job file. CUPS has extended this +scope for PPDs to cover non-PostScript printers too. This was not +difficult, because it is a standardized file format. In a way +it was logical too: CUPS handles PostScript and uses a PostScript +RIP (Ghostscript) to process the job files. The only difference is: +a PostScript printer has the RIP built-in, for other types of +printers the Ghostscript RIP runs on the host computer. +</para> + +<para> +PPDs for a non-PS printer have a few lines that are unique to +CUPS. The most important one looks similar to this: + +<indexterm><primary>application/vnd.cups-raster</primary></indexterm> + +<programlisting> + *cupsFilter: application/vnd.cups-raster 66 rastertoprinter +</programlisting> + +It is the last piece in the CUPS filtering puzzle. This line tells the +CUPS daemon to use as a last filter <parameter>rastertoprinter</parameter>. This filter +should be served as input an <parameter>application/vnd.cups-raster</parameter> MIME type +file. Therefore, CUPS should auto-construct a filtering chain, which +delivers as its last output the specified MIME type. This is then +taken as input to the specified <parameter>rastertoprinter</parameter> filter. After this +the last filter has done its work (<parameter>rastertoprinter</parameter> is a Gimp-Print +filter), the file should go to the backend, which sends it to the +output device. +</para> + +<para> +CUPS by default ships only a few generic PPDs, but they are good for +several hundred printer models. You may not be able to control +different paper trays, or you may get larger margins than your +specific model supports. See <link linkend="cups-ppds">PPDs shipped with CUPS</link> for summary information. +</para> + +<table frame="all" id="cups-ppds"> + <title>PPDs shipped with CUPS</title> + <tgroup cols="2" align="left"> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead><row><entry>PPD file</entry><entry>Printer type</entry></row></thead> + <tbody> + <row><entry>deskjet.ppd</entry><entry>older HP inkjet printers and compatible</entry></row> + + <row><entry>deskjet2.ppd</entry> <entry>newer HP inkjet printers and compatible </entry> </row> + + <row><entry>dymo.ppd</entry> <entry>label printers </entry> </row> + + <row><entry>epson9.ppd</entry> <entry>Epson 24pin impact printers and compatible </entry> </row> + + <row><entry>epson24.ppd</entry> <entry>Epson 24pin impact printers and compatible </entry> </row> + + <row><entry>okidata9.ppd</entry> <entry>Okidata 9pin impact printers and compatible </entry> </row> + + <row><entry>okidat24.ppd</entry> <entry>Okidata 24pin impact printers and compatible </entry> </row> + + <row><entry>stcolor.ppd</entry> <entry>older Epson Stylus Color printers </entry> </row> + + <row><entry>stcolor2.ppd</entry> <entry>newer Epson Stylus Color printers </entry> </row> + + <row><entry>stphoto.ppd</entry> <entry>older Epson Stylus Photo printers </entry> </row> + + <row><entry>stphoto2.ppd</entry> <entry>newer Epson Stylus Photo printers </entry> </row> + + <row><entry>laserjet.ppd</entry> <entry>all PCL printers. Further below is a discussion + of several other driver/PPD-packages suitable for use with CUPS. </entry> </row> + + </tbody> + </tgroup> +</table> + +</sect2> + +<sect2> +<title><emphasis>cupsomatic/foomatic-rip</emphasis> Versus <emphasis>native CUPS</emphasis> Printing</title> + + +<para> +<indexterm><primary>cupsomatic</primary></indexterm> +<indexterm><primary>foomatic-rip</primary></indexterm> +Native CUPS rasterization works in two steps: +</para> + +<itemizedlist> +<listitem><para> +First is the <parameter>pstoraster</parameter> step. It uses the special CUPS +<indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm> +device from ESP Ghostscript 7.05.x as its tool. +</para></listitem> + +<listitem><para> +Second comes the <parameter>rasterdriver</parameter> step. It uses various +device-specific filters; there are several vendors who provide good +quality filters for this step. Some are free software, some are +shareware/non-free and some are proprietary.</para></listitem> +</itemizedlist> + +<para> +Often this produces better quality (and has several more +advantages) than other methods. +</para> + +<para> + <image id="cupsomatic-dia"> + <imagedescription>cupsomatic/foomatic Processing versus Native CUPS.</imagedescription> + <imagefile>10small</imagefile> + </image> +</para> + +<para> +One other method is the <parameter>cupsomatic/foomatic-rip</parameter> +way. Note that <parameter>cupsomatic</parameter> is <emphasis>not</emphasis> made by the CUPS +developers. It is an independent contribution to printing development, +made by people from Linuxprinting.org <footnote><para>see also <ulink +noescape="1" url="http://www.cups.org/cups-help.html">http://www.cups.org/cups-help.html</ulink></para></footnote>. +<parameter>cupsomatic</parameter> is no longer developed and maintained and is no longer +supported. It has now been replaced by +<parameter>foomatic-rip</parameter>. <parameter>foomatic-rip</parameter> is a complete re-write +of the old <parameter>cupsomatic</parameter> idea, but very much improved and generalized to +other (non-CUPS) spoolers. An upgrade to foomatic-rip is strongly +advised, especially if you are upgrading to a recent version of CUPS, +too. +</para> + +<para> + <indexterm><primary>cupsomatic</primary></indexterm> + <indexterm><primary>foomatic</primary></indexterm> +Both the <parameter>cupsomatic</parameter> (old) and the <parameter>foomatic-rip</parameter> (new) methods from +Linuxprinting.org use the traditional Ghostscript print file +processing, doing everything in a single step. It therefore relies on +all the other devices built into Ghostscript. The quality is as +good (or bad) as Ghostscript rendering is in other spoolers. The +advantage is that this method supports many printer models not +supported (yet) by the more modern CUPS method. +</para> + +<para> +Of course, you can use both methods side by side on one system (and +even for one printer, if you set up different queues) and find out +which works best for you. +</para> + +<para> +<parameter>cupsomatic</parameter> kidnaps the printfile after the +<parameter>application/vnd.cups-postscript</parameter> stage and +deviates it through the CUPS-external, system-wide Ghostscript +installation. Therefore the printfile bypasses the <parameter>pstoraster</parameter> filter +(and also bypasses the CUPS-raster-drivers +<parameter>rastertosomething</parameter>). After Ghostscript finished its rasterization, +<parameter>cupsomatic</parameter> hands the rendered file directly to the CUPS backend. The +flowchart in <link linkend="cupsomatic-dia">cupsomatic/foomatic processing versus Native CUPS</link> illustrates the difference between native CUPS +rendering and the <parameter>Foomatic/cupsomatic</parameter> method. +</para> +</sect2> + +<sect2> +<title>Examples for Filtering Chains</title> + +<para> +Here are a few examples of commonly occurring filtering chains to +illustrate the workings of CUPS. +</para> + +<para> +Assume you want to print a PDF file to an HP JetDirect-connected +PostScript printer, but you want to print the pages 3-5, 7, 11-13 +only, and you want to print them <quote>two-up</quote> and <quote>duplex</quote>: +</para> + +<itemizedlist> +<listitem><para>Your print options (page selection as required, two-up, +duplex) are passed to CUPS on the command line.</para></listitem> + +<listitem><para>The (complete) PDF file is sent to CUPS and auto-typed as +<parameter>application/pdf</parameter>.</para></listitem> + +<listitem><para>The file therefore must first pass the +<parameter>pdftops</parameter> pre-filter, which produces PostScript +MIME type <parameter>application/postscript</parameter> (a preview here +would still show all pages of the original PDF).</para></listitem> + +<listitem><para>The file then passes the <parameter>pstops</parameter> +filter that applies the command line options: it selects the pages +2-5, 7 and 11-13, creates an imposed layout <quote>2 pages on 1 sheet</quote> and +inserts the correct <quote>duplex</quote> command (as defined in the printer's +PPD) into the new PostScript file; the file is now of PostScript MIME +type +<parameter>application/vnd.cups-postscript</parameter>.</para></listitem> + +<listitem><para>The file goes to the <parameter>socket</parameter> +backend, which transfers the job to the printers.</para></listitem> +</itemizedlist> + +<para> + The resulting filter chain, therefore, is as drawn in <link linkend="pdftosocket">PDF to socket chain</link>. + <image id="pdftosocket"> + <imagedescription>PDF to socket chain.</imagedescription> + <imagefile>pdftosocket</imagefile> + </image> +</para> + + +<para> +Assume you want to print the same filter to an USB-connected +Epson Stylus Photo printer installed with the CUPS +<filename>stphoto2.ppd</filename>. The first few filtering stages +are nearly the same: +</para> + +<itemizedlist> +<listitem><para>Your print options (page selection as required, two-up, +duplex) are passed to CUPS on the command-line.</para></listitem> + +<listitem><para>The (complete) PDF file is sent to CUPS and auto-typed as +<parameter>application/pdf</parameter>.</para></listitem> + +<listitem><para>The file must first pass the +<parameter>pdftops</parameter> pre-filter, which produces PostScript +MIME type <parameter>application/postscript</parameter> (a preview here +would still show all pages of the original PDF).</para></listitem> + +<listitem><para>The file then passes the <quote>pstops</quote> filter that applies +the command-line options: it selects the pages 2-5, 7 and 11-13, +creates an imposed layout <quote>two pages on one sheet</quote> and inserts the +correct <quote>duplex</quote> command... (Oops &smbmdash; this printer and PPD +do not support duplex printing at all &smbmdash; so this option will +be ignored) into the new PostScript file; the file is now of PostScript +MIME type +<parameter>application/vnd.cups-postscript</parameter>.</para></listitem> + +<listitem><para>The file then passes the + <!--FIXME--> +<parameter>pstoraster</parameter> stage and becomes MIME type +<parameter>application/ +cups-raster</parameter>.</para></listitem> + +<listitem><para>Finally, the <parameter>rastertoepson</parameter> filter +does its work (as indicated in the printer's PPD), creating the +printer-specific raster data and embedding any user-selected +print-options into the print data stream.</para></listitem> + +<listitem><para>The file goes to the <parameter>usb</parameter> backend, +which transfers the job to the printers.</para></listitem> +</itemizedlist> + +<para> +The resulting filter chain therefore is as drawn in <link linkend="pdftoepsonusb">this figure</link>. +</para> + +<image id="pdftoepsonusb"> + <imagedescription>PDF to USB chain.</imagedescription> + <imagefile>pdftoepsonusb</imagefile> +</image> +</sect2> + +<sect2> +<title>Sources of CUPS Drivers/PPDs</title> + +<para> +On the Internet you can now find many thousands of CUPS-PPD files +(with their companion filters), in many national languages +supporting more than thousand non-PostScript models. +</para> + +<itemizedlist> +<indexterm><primary>ESP</primary><secondary>Print Pro</secondary></indexterm> +<indexterm><primary>PrintPro</primary><see>ESP Print Pro</see></indexterm> +<listitem><para><ulink url="http://wwwl.easysw.com/printpro/">ESP +PrintPro</ulink> (commercial, +non-free) is packaged with more than three thousand PPDs, ready for +successful use <quote>out of the box</quote> on Linux, Mac OS X, IBM-AIX, +HP-UX, Sun-Solaris, SGI-IRIX, Compaq Tru64, Digital UNIX, and some +more commercial Unices (it is written by the CUPS developers +themselves and its sales help finance the further development of +CUPS, as they feed their creators).</para></listitem> + +<listitem><para>The <ulink +url="http://gimp-print.sourceforge.net/">Gimp-Print-Project +</ulink> (GPL, free software) +provides around 140 PPDs (supporting nearly 400 printers, many driven +to photo quality output), to be used alongside the Gimp-Print CUPS +filters.</para></listitem> + +<listitem><para><ulink url="http://www.turboprint.com/">TurboPrint +</ulink> (shareware, non-free) supports +roughly the same amount of printers in excellent +quality.</para></listitem> + +<listitem><para><ulink +url="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/">OMNI +</ulink> +(LPGL, free) is a package made by IBM, now containing support for more +than 400 printers, stemming from the inheritance of IBM OS/2 Know-How +ported over to Linux (CUPS support is in a beta-stage at +present).</para></listitem> + +<listitem><para><ulink url="http://hpinkjet.sourceforge.net/">HPIJS +</ulink> (BSD-style licenses, free) +supports around 150 of HP's own printers and is also providing +excellent print quality now (currently available only via the Foomatic +path).</para></listitem> + +<listitem><para><ulink url="http://www.linuxprinting.org/">Foomatic/cupsomatic +</ulink> (LPGL, free) from Linuxprinting.org are providing PPDs for practically every Ghostscript +filter known to the world (including Omni, Gimp-Print and HPIJS).</para></listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Printing with Interface Scripts</title> + +<para> +CUPS also supports the usage of <quote>interface scripts</quote> as known from +System V AT&T printing systems. These are often used for PCL +printers, from applications that generate PCL print jobs. Interface +scripts are specific to printer models. They have a similar role as +PPDs for PostScript printers. Interface scripts may inject the Escape +sequences as required into the print data stream, if the user has +chosen to select a certain paper tray, or print landscape, or use A3 +paper, etc. Interfaces scripts are practically unknown in the Linux +realm. On HP-UX platforms they are more often used. You can use any +working interface script on CUPS too. Just install the printer with +the <command>-i</command> option: +</para> + +<para><screen> +&rootprompt;<userinput>lpadmin -p pclprinter -v socket://11.12.13.14:9100 \ + -i /path/to/interface-script</userinput> +</screen></para> + +<para> +Interface scripts might be the <quote>unknown animal</quote> to many. However, +with CUPS they provide the easiest way to plug in your own +custom-written filtering script or program into one specific print +queue (some information about the traditional usage of interface scripts is +to be found at <ulink + noescape="1" url="http://playground.sun.com/printing/documentation/interface.html">http://playground.sun.com/printing/documentation/interface.html</ulink>). +</para> +</sect2> +</sect1> + +<sect1> + <title>Network Printing (Purely Windows)</title> + +<para> +Network printing covers a lot of ground. To understand what exactly +goes on with Samba when it is printing on behalf of its Windows +clients, let's first look at a <quote>purely Windows</quote> setup: Windows clients +with a Windows NT print server. +</para> + +<sect2> +<title>From Windows Clients to an NT Print Server</title> + +<para> +Windows clients printing to an NT-based print server have two +options. They may: +<indexterm><primary>GDI</primary></indexterm> +<indexterm><primary>EMF</primary></indexterm> +</para> + + +<itemizedlist> + <listitem><para>Execute the driver locally and render the GDI output + (EMF) into the printer-specific format on their own. + </para></listitem> + + <listitem><para>Send the GDI output (EMF) to the server, where the +driver is executed to render the printer specific +output.</para></listitem> +</itemizedlist> + +<para> +Both print paths are shown in the flowcharts <link linkend="small11">Print driver +execution on the client</link> and <link linkend="small12">Print driver execution on the server</link>. +</para> +</sect2> + +<sect2> +<title>Driver Execution on the Client</title> + +<para> +In the first case the print server must spool the file as raw, +meaning it shouldn't touch the jobfile and try to convert it in any +way. This is what a traditional UNIX-based print server can do too, and +at a better performance and more reliably than an NT print server. This +is what most Samba administrators probably are familiar with. One +advantage of this setup is that this <quote>spooling-only</quote> print server may +be used even if no driver(s) for UNIX are available it is sufficient +to have the Windows client drivers available; and installed on the +clients. +</para> + +<para> + <image id="small11"> + <imagedescription>Print driver execution on the client.</imagedescription> + <imagefile>11small</imagefile> + </image> +</para> +</sect2> + +<sect2> +<title>Driver Execution on the Server</title> + + +<para> +<indexterm><primary>PostScript</primary></indexterm> +<indexterm><primary>PCL</primary></indexterm> +<indexterm><primary>ESC/P</primary></indexterm> +<indexterm><primary>EMF</primary></indexterm> +<indexterm><primary>GDI</primary></indexterm> +The other path executes the printer driver on the server. The client +transfers print files in EMF format to the server. The server uses the +PostScript, PCL, ESC/P or other driver to convert the EMF file into +the printer-specific language. It is not possible for UNIX to do the +same. Currently, there is no program or method to convert a Windows +client's GDI output on a UNIX server into something a printer could +understand. +</para> + +<para> + <image id="small12"> + <imagedescription>Print driver execution on the server.</imagedescription> + <imagefile>12small</imagefile> + </image> +</para> + +<para> +However, there is something similar possible with CUPS. Read on. +</para> +</sect2> +</sect1> + +<sect1> +<title>Network Printing (Windows Clients &smbmdash; UNIX/Samba Print +Servers)</title> + +<para> +Since UNIX print servers <emphasis>cannot</emphasis> execute the Win32 +program code on their platform, the picture is somewhat +different. However, this does not limit your options all that +much. On the contrary, you may have a way here to implement printing +features that are not possible otherwise. +</para> + +<sect2> +<title>From Windows Clients to a CUPS/Samba Print Server</title> + +<para> +Here is a simple recipe showing how you can take advantage of CUPS' +powerful features for the benefit of your Windows network printing +clients: +</para> + +<itemizedlist> + +<listitem><para>Let the Windows clients send PostScript to the CUPS +server.</para></listitem> + +<listitem><para>Let the CUPS server render the PostScript into device-specific raster format.</para></listitem> +</itemizedlist> + +<para> +This requires the clients to use a PostScript driver (even if the +printer is a non-PostScript model. It also requires that you have a +driver on the CUPS server. +</para> + +<para> +First, to enable CUPS-based printing through Samba the +following options should be set in your &smb.conf; file [global] +section: +</para> + +<smbconfblock> +<smbconfoption name="printing">cups</smbconfoption> +<smbconfoption name="printcap">cups</smbconfoption> +</smbconfblock> + +<para> +When these parameters are specified, all manually set print directives +(like <smbconfoption name="print command"/>, or <smbconfoption name="lppause command"/>) in &smb.conf; (as well as +in Samba itself) will be ignored. Instead, Samba will directly +interface with CUPS through its application program interface (API), +as long as Samba has been compiled with CUPS library (libcups) +support. If Samba has not been compiled with CUPS support, and if no +other print commands are set up, then printing will use the +<emphasis>System V</emphasis> AT&T command set, with the -oraw +option automatically passing through (if you want your own defined +print commands to work with a Samba that has CUPS support compiled in, +simply use <smbconfoption name="printing">sysv</smbconfoption>). +</para> + +<para> + <image> + <imagedescription>Printing via CUPS/Samba server.</imagedescription> + <imagefile>13small</imagefile> + </image> +</para> +</sect2> + +<sect2> +<title>Samba Receiving Job-files and Passing Them to CUPS</title> + +<para> +Samba <emphasis>must</emphasis> use its own spool directory (it is set +by a line similar to <smbconfoption name="path">/var/spool/samba</smbconfoption>, +in the <smbconfsection name="[printers]"/> or +<smbconfsection name="[printername]"/> section of +&smb.conf;). Samba receives the job in its own +spool space and passes it into the spool directory of CUPS (the CUPS +spooling directory is set by the <parameter>RequestRoot</parameter> +directive, in a line that defaults to <parameter>RequestRoot +/var/spool/cups</parameter>). CUPS checks the access rights of its +spool dir and resets it to healthy values with every restart. We have +seen quite a few people who had used a common spooling space for Samba +and CUPS, and were struggling for weeks with this <quote>problem.</quote> +</para> + +<para> +A Windows user authenticates only to Samba (by whatever means is +configured). If Samba runs on the same host as CUPS, you only need to +allow <quote>localhost</quote> to print. If they run on different machines, you +need to make sure the Samba host gets access to printing on CUPS. +</para> +</sect2> +</sect1> + +<sect1> +<title>Network PostScript RIP</title> + +<para> +This section discusses the use of CUPS filters on the server &smbmdash; configuration where +clients make use of a PostScript driver with CUPS-PPDs. +</para> + + +<para> +<indexterm><primary>PostScript</primary></indexterm> +<indexterm><primary>PCL</primary></indexterm> +<indexterm><primary>PJL</primary></indexterm> +PPDs can control all print device options. They are usually provided +by the manufacturer, if you own a PostScript printer, that is. PPD +files (PostScript Printer Descriptions) are always a component of +PostScript printer drivers on MS Windows or Apple Mac OS systems. They +are ASCII files containing user-selectable print options, mapped to +appropriate PostScript, PCL or PJL commands for the target +printer. Printer driver GUI dialogs translate these options +<quote>on-the-fly</quote> into buttons and drop-down lists for the user to select. +</para> + +<para> +CUPS can load, without any conversions, the PPD file from any Windows +(NT is recommended) PostScript driver and handle the options. There is +a Web browser interface to the print options (select <ulink +noescape="1" url="http://localhost:631/printers/">http://localhost:631/printers/</ulink> +and click on one <guibutton>Configure Printer</guibutton> button to see +it), or a command line interface (see <command>man lpoptions</command> +or see if you have <command>lphelp</command> on your system). There are also some +different GUI front-ends on Linux/UNIX, which can present PPD options +to users. PPD options are normally meant to be evaluated by the +PostScript RIP on the real PostScript printer. +</para> + +<sect2> +<title>PPDs for Non-PS Printers on UNIX</title> + + +<para> +<indexterm><primary>PPD</primary></indexterm> +CUPS does not limit itself to <quote>real</quote> PostScript printers in its usage +of PPDs. The CUPS developers have extended the scope of the PPD +concept to also describe available device and driver options for +non-PostScript printers through CUPS-PPDs. +</para> + +<para> +This is logical, as CUPS includes a fully featured PostScript +interpreter (RIP). This RIP is based on Ghostscript. It can process +all received PostScript (and additionally many other file formats) +from clients. All CUPS-PPDs geared to non-PostScript printers contain +an additional line, starting with the keyword +<parameter>*cupsFilter</parameter>. This line tells the CUPS print +system which printer-specific filter to use for the interpretation of +the supplied PostScript. Thus CUPS lets all its printers appear as +PostScript devices to its clients, because it can act as a PostScript +RIP for those printers, processing the received PostScript code into a +proper raster print format. +</para> +</sect2> + +<sect2> +<title>PPDs for Non-PS Printers on Windows</title> + +<para> +<indexterm><primary>PPD</primary></indexterm> +CUPS-PPDs can also be used on Windows-Clients, on top of a +<quote>core</quote> PostScript driver (now recommended is the "CUPS PostScript +Driver for Windows NT/200x/XP"; you can also use the Adobe one, with +limitations). This feature enables CUPS to do a few tricks no other +spooler can do: +</para> + +<itemizedlist> + +<listitem><para>Act as a networked PostScript RIP (Raster Image +Processor), handling print files from all client platforms in a uniform +way.</para></listitem> + +<listitem><para>Act as a central accounting and billing server, since +all files are passed through the pstops filter and are, therefore, +logged in the CUPS <filename>page_log</filename> file. +<emphasis>Note:</emphasis> this cannot happen with <quote>raw</quote> print jobs, +which always remain unfiltered per definition.</para></listitem> + +<listitem><para>Enable clients to consolidate on a single PostScript +driver, even for many different target printers.</para></listitem> +</itemizedlist> + +<para> +Using CUPS PPDs on Windows clients enables these to control +all print job settings just as a UNIX client can do. +</para> +</sect2> +</sect1> + +<sect1> +<title>Windows Terminal Servers (WTS) as CUPS Clients</title> + +<para> +This setup may be of special interest to people experiencing major +problems in WTS environments. WTS often need a multitude of +non-PostScript drivers installed to run their clients' variety of +different printer models. This often imposes the price of much +increased instability. +</para> + +<sect2> +<title>Printer Drivers Running in <quote>Kernel Mode</quote> Cause Many +Problems</title> + +<para> + In Windows NT printer drivers which run in <quote>Kernel +Mode</quote>, introduces a high risk for the stability of the system +if the driver is not really stable and well-tested. And there are a +lot of bad drivers out there! Especially notorious is the example +of the PCL printer driver that had an additional sound module +running, to notify users via sound-card of their finished jobs. Do I +need to say that this one was also reliably causing <quote>blue screens +of death</quote> on a regular basis? +</para> + +<para> +PostScript drivers are generally well tested. They are not known +to cause any problems, even though they also run in kernel mode. This +might be because there have been so far only two different PostScript +drivers: the ones from Adobe and the one from Microsoft. Both are +well tested and are as stable as you can imagine on +Windows. The CUPS driver is derived from the Microsoft one. +</para> +</sect2> + +<sect2> +<title>Workarounds Impose Heavy Limitations</title> + +<para> +In many cases, in an attempt to work around this problem, site +administrators have resorted to restricting the allowed drivers installed +on their WTS to one generic PCL and one PostScript driver. This, +however, restricts the clients in the number of printer options +available for them. Often they can't get out more than simplex +prints from one standard paper tray, while their devices could do much +better, if driven by a different driver! +</para> +</sect2> + +<sect2> +<title>CUPS: A <quote>Magical Stone</quote>?</title> + + +<para> +<indexterm><primary>PPD</primary></indexterm> +<indexterm><primary>PostScript</primary></indexterm> +Using a PostScript driver, enabled with a CUPS-PPD, seems to be a very +elegant way to overcome all these shortcomings. There are, depending +on the version of Windows OS you use, up to three different PostScript +drivers available: Adobe, Microsoft and CUPS PostScript drivers. None +of them is known to cause major stability problems on WTS (even if +used with many different PPDs). The clients will be able to (again) +chose paper trays, duplex printing and other settings. However, there +is a certain price for this too: a CUPS server acting as a PostScript +RIP for its clients requires more CPU and RAM than when just acting as +a <quote>raw spooling</quote> device. Plus, this setup is not yet widely tested, +although the first feedbacks look very promising. +</para> +</sect2> + +<sect2> +<title>PostScript Drivers with No Major Problems &smbmdash; Even in Kernel +Mode</title> + +<para> +<indexterm><primary>DDK</primary></indexterm> +More recent printer drivers on W200x and XP no longer run in kernel mode +(unlike Windows NT). However, both operating systems can still +use the NT drivers, running in kernel mode (you can roughly tell which +is which as the drivers in subdirectory <quote>2</quote> of <quote>W32X86</quote> are <quote>old</quote> +ones). As was said before, the Adobe as well as the Microsoft +PostScript drivers are not known to cause any stability problems. The +CUPS driver is derived from the Microsoft one. There is a simple +reason for this: The MS DDK (Device Development Kit) for Windows NT (which +used to be available at no cost to licensees of Visual Studio) +includes the source code of the Microsoft driver, and licensees of +Visual Studio are allowed to use and modify it for their own driver +development efforts. This is what the CUPS people have done. The +license does not allow them to publish the whole of the source code. +However, they have released the <quote>diff</quote> under the GPL, and if you are +the owner of an <quote>MS DDK for Windows NT,</quote> you can check the driver yourself. +</para> +</sect2> +</sect1> + +<sect1> +<title>Configuring CUPS for Driver Download</title> + +<para> +As we have said before, all previously known methods to prepare client +printer drivers on the Samba server for download and Point'n'Print +convenience of Windows workstations are working with CUPS, too. These +methods were described in the previous chapter. In reality, this is a +pure Samba business and only relates to the Samba/Windows client +relationship. +</para> + +<sect2> +<title><emphasis>cupsaddsmb</emphasis>: The Unknown Utility</title> + + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +The <command>cupsaddsmb</command> utility (shipped with all current CUPS versions) is an +alternate method to transfer printer drivers into the Samba +<smbconfsection name="[print$]"/> share. Remember, this share is where +clients expect drivers deposited and setup for download and +installation. It makes the sharing of any (or all) installed CUPS +printers quite easy. <command>cupsaddsmb</command> can use the Adobe PostScript driver as +well as the newly developed CUPS PostScript Driver for +Windows NT/200x/XP. <parameter>cupsaddsmb</parameter> does +<emphasis>not</emphasis> work with arbitrary vendor printer drivers, +but only with the <emphasis>exact</emphasis> driver files that are +named in its man page. +</para> + +<para> +The CUPS printer driver is available from the CUPS download site. Its +package name is <filename>cups-samba-[version].tar.gz</filename> . It +is preferred over the Adobe drivers since it has a number of +advantages: +</para> + +<itemizedlist> +<listitem><para>It supports a much more accurate page +accounting.</para></listitem> + +<listitem><para>It supports banner pages, and page labels on all +printers.</para></listitem> + +<listitem><para>It supports the setting of a number of job IPP +attributes (such as job-priority, page-label and +job-billing).</para></listitem> +</itemizedlist> + +<para> +However, currently only Windows NT, 2000 and XP are supported by the +CUPS drivers. You will also need to get the respective part of Adobe driver +if you need to support Windows 95, 98 and ME clients. +</para> +</sect2> + +<sect2> + <title>Prepare Your &smb.conf; for <command>cupsaddsmb</command></title> + +<para> +Prior to running <command>cupsaddsmb</command>, you need the settings in +&smb.conf; as shown in <link linkend="cupsadd-ex">the next example</link>: +</para> + +<para><smbconfexample id="cupsadd-ex"> +<title>smb.conf for cupsaddsmb usage</title> +<smbconfsection name="[global]"/> +<smbconfoption name="load printers">yes</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="browseable">no</smbconfoption> +<smbconfoption name="public">yes</smbconfoption> +<smbconfcomment>setting depends on your requirements</smbconfcomment> +<smbconfoption name="guest ok">yes</smbconfoption> +<smbconfoption name="writable">no</smbconfoption> +<smbconfoption name="printable">yes</smbconfoption> +<smbconfoption name="printer admin">root</smbconfoption> + <smbconfsection name="[print$]"/> +<smbconfoption name="comment">Printer Drivers</smbconfoption> +<smbconfoption name="path">/etc/samba/drivers</smbconfoption> +<smbconfoption name="browseable">yes</smbconfoption> +<smbconfoption name="guest ok">no</smbconfoption> +<smbconfoption name="read only">yes</smbconfoption> +<smbconfoption name="write list">root</smbconfoption> +</smbconfexample></para> +</sect2> + +<sect2> +<title>CUPS <quote>PostScript Driver for Windows NT/200x/XP</quote></title> + +<para> +<indexterm><primary>PostScript</primary></indexterm> +CUPS users may get the exact same packages from <ulink +noescape="1" url="http://www.cups.org/software.html">http://www.cups.org/software.html</ulink>. +It is a separate package from the CUPS base software files, tagged as +CUPS 1.1.x Windows NT/200x/XP Printer Driver for Samba +(tar.gz, 192k). The filename to download is +<filename>cups-samba-1.1.x.tar.gz</filename>. Upon untar and unzipping, +it will reveal these files: +</para> + +<para><screen> +&rootprompt;<userinput>tar xvzf cups-samba-1.1.19.tar.gz</userinput> +cups-samba.install +cups-samba.license +cups-samba.readme +cups-samba.remove +cups-samba.ss +</screen></para> + +<para> +<indexterm><primary>ESP</primary><secondary>meta packager</secondary></indexterm> +<indexterm><primary>EPM</primary><see>ESP meta packager</see></indexterm> +These have been packaged with the ESP meta packager software +EPM. The <filename>*.install</filename> and +<filename>*.remove</filename> files are simple shell scripts, which +untars the <filename>*.ss</filename> (the <filename>*.ss</filename> is +nothing else but a tar-archive, which can be untarred by <quote>tar</quote> +too). Then it puts the content into +<filename>/usr/share/cups/drivers/</filename>. This content includes three +files: +</para> + +<para><screen> +&rootprompt;<userinput>tar tv cups-samba.ss</userinput> +cupsdrvr.dll +cupsui.dll +cups.hlp +</screen></para> + +<para> +The <parameter>cups-samba.install</parameter> shell scripts are easy to +handle: +</para> + +<para><screen> +&rootprompt;<userinput>./cups-samba.install</userinput> +[....] +Installing software... +Updating file permissions... +Running post-install commands... +Installation is complete. +</screen></para> + +<para> +The script should automatically put the driver files into the +<filename>/usr/share/cups/drivers/</filename> directory. +</para> + +<warning><para> +Due to a bug, one recent CUPS release puts the +<filename>cups.hlp</filename> driver file +into<filename>/usr/share/drivers/</filename> instead of +<filename>/usr/share/cups/drivers/</filename>. To work around this, +copy/move the file (after running the +<command>./cups-samba.install</command> script) manually to the +correct place. +</para></warning> + +<para><screen> +&rootprompt;<userinput>cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/</userinput> +</screen></para> + + +<para> +<indexterm><primary>DDK</primary></indexterm> +This new CUPS PostScript driver is currently binary-only, but free of +charge. No complete source code is provided (yet). The reason is that +it has been developed with the help of the Microsoft Driver +Developer Kit (DDK) and compiled with Microsoft Visual +Studio 6. Driver developers are not allowed to distribute the whole of +the source code as free software. However, CUPS developers released +the <quote>diff</quote> in source code under the GPL, so anybody with a license of +Visual Studio and a DDK will be able to compile for him/herself. +</para> +</sect2> + +<sect2> +<title>Recognizing Different Driver Files</title> + +<para> +The CUPS drivers do not support the older Windows 95/98/Me, but only +the Windows NT/2000/XP client. +</para> + +<para>Windows NT, 2000 and XP are supported by:</para> + +<para> + <itemizedlist> + <listitem><para>cups.hlp</para></listitem> + <listitem><para>cupsdrvr.dll</para></listitem> + <listitem><para>cupsui.dll</para></listitem> + </itemizedlist> +</para> + +<para> +Adobe drivers are available for the older Windows 95/98/Me as well as +the Windows NT/2000/XP clients. The set of files is different from the +different platforms. +</para> + +<para>Windows 95, 98 and ME are supported by:</para> + +<para> + <itemizedlist> + <listitem><para>ADFONTS.MFM</para></listitem> + <listitem><para>ADOBEPS4.DRV</para></listitem> + <listitem><para>ADOBEPS4.HLP</para></listitem> + <listitem><para>DEFPRTR2.PPD</para></listitem> + <listitem><para>ICONLIB.DLL</para></listitem> + <listitem><para>PSMON.DLL</para></listitem> +</itemizedlist> +</para> + +<para>Windows NT, 2000 and XP are supported by:</para> + +<para> +<itemizedlist> + <listitem><para>ADOBEPS5.DLL</para></listitem> + <listitem><para>ADOBEPSU.DLL</para></listitem> + <listitem><para>ADOBEPSU.HLP</para></listitem> +</itemizedlist> + +</para> + +<note><para> +If both the Adobe driver files and the CUPS driver files for the +support of Windows NT/200x/XP are present in FIXME, the Adobe ones will be ignored +and the CUPS ones will be used. If you prefer &smbmdash; for whatever reason +&smbmdash; to use Adobe-only drivers, move away the three CUPS driver files. The +Windows 9x/Me clients use the Adobe drivers in any case. +</para></note> +</sect2> + +<sect2> +<title>Acquiring the Adobe Driver Files</title> + +<para> +Acquiring the Adobe driver files seems to be unexpectedly difficult +for many users. They are not available on the Adobe Web site as single +files and the self-extracting and/or self-installing Windows-.exe is +not easy to locate either. Probably you need to use the included +native installer and run the installation process on one client +once. This will install the drivers (and one Generic PostScript +printer) locally on the client. When they are installed, share the +Generic PostScript printer. After this, the client's +<smbconfsection name="[print$]"/> share holds the Adobe files, from +where you can get them with smbclient from the CUPS host. +</para> +</sect2> + +<sect2> +<title>ESP Print Pro PostScript Driver for Windows NT/200x/XP</title> + + + +<para> +<indexterm><primary>ESP</primary><secondary>Print Pro</secondary></indexterm> +Users of the ESP Print Pro software are able to install their Samba +drivers package for this purpose with no problem. Retrieve the driver +files from the normal download area of the ESP Print Pro software +at <ulink + noescape="1" url="http://www.easysw.com/software.html">http://www.easysw.com/software.html</ulink>. +You need to locate the link labeled <quote>SAMBA</quote> among the +<guilabel>Download Printer Drivers for ESP Print Pro 4.x</guilabel> +area and download the package. Once installed, you can prepare any +driver by simply highlighting the printer in the Printer Manager GUI +and select <guilabel>Export Driver...</guilabel> from the menu. Of +course you need to have prepared Samba beforehand to handle the +driver files; i.e., setup the <smbconfsection name="[print$]"/> +share, and so on. The ESP Print Pro package includes the CUPS driver files +as well as a (licensed) set of Adobe drivers for the Windows 95/98/Me +client family. +</para> +</sect2> + +<sect2> +<title>Caveats to be Considered</title> + + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +Once you have run the install script (and possibly manually +moved the <filename>cups.hlp</filename> file to +<filename>/usr/share/cups/drivers/</filename>), the driver is +ready to be put into Samba's <smbconfsection name="[print$]"/> share (which often maps to +<filename>/etc/samba/drivers/</filename> and contains a subdirectory +tree with <emphasis>WIN40</emphasis> and +<emphasis>W32X86</emphasis> branches). You do this by running +<command>cupsaddsmb</command> (see also <command>man cupsaddsmb</command> for +CUPS since release 1.1.16). +</para> + +<tip><para> +<indexterm><primary>Single Sign On</primary></indexterm> +You may need to put root into the smbpasswd file by running +<command>smbpasswd</command>; this is especially important if you +should run this whole procedure for the first time, and are not +working in an environment where everything is configured for +<emphasis>single sign on</emphasis> to a Windows Domain Controller. +</para></tip> + +<para> +Once the driver files are in the <smbconfsection name="[print$]"/> share +and are initialized, they are ready to be downloaded and installed by +the Windows NT/200x/XP clients. +</para> + +<note><para> +Win 9x/Me clients will not work with the CUPS PostScript driver. For +these you still need to use the <filename>ADOBE*.*</filename> +drivers as previously stated. +</para></note> + +<note> +<para> +It is not harmful if you still have the +<filename>ADOBE*.*</filename> driver files from previous +installations in the <filename>/usr/share/cups/drivers/</filename> +directory. The new <command>cupsaddsmb</command> (from 1.1.16) will +automatically prefer its own drivers if it finds both. +</para></note> + +<note><para> +<indexterm><primary>"Printers" folder</primary></indexterm> +Should your Windows clients have had the old <filename>ADOBE*.*</filename> +files for the Adobe PostScript driver installed, the download and +installation of the new CUPS PostScript driver for Windows NT/200x/XP +will fail at first. You need to wipe the old driver from the clients +first. It is not enough to <quote>delete</quote> the printer, as the driver files +will still be kept by the clients and re-used if you try to re-install +the printer. To really get rid of the Adobe driver files on the +clients, open the <guilabel>Printers</guilabel> folder (possibly via <guilabel>Start > Settings > Control Panel > Printers</guilabel>), +right-click on the folder background and select <guimenuitem>Server +Properties</guimenuitem>. When the new dialog opens, select the +<guilabel>Drivers</guilabel> tab. On the list select the driver you +want to delete and click the <guilabel>Delete</guilabel> +button. This will only work if there is not one single printer left +that uses that particular driver. You need to <quote>delete</quote> all printers +using this driver in the <guilabel>Printers</guilabel> folder first. You will need +Administrator privileges to do this. +</para></note> + +<note><para> +<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> +Once you have successfully downloaded the CUPS PostScript driver to a +client, you can easily switch all printers to this one by proceeding +as described in <link linkend="printing">Classical Printing Support</link>. Either change +a driver for an existing printer by running the <guilabel>Printer Properties</guilabel> +dialog, or use <command>rpcclient</command> with the +<command>setdriver</command> subcommand. +</para></note> +</sect2> + +<sect2> +<title>Windows CUPS PostScript Driver Versus Adobe Driver</title> + +<para> +Are you interested in a comparison between the CUPS and the Adobe +PostScript drivers? For our purposes these are the most important +items that weigh in favor of the CUPS ones: +</para> + +<itemizedlist> +<listitem><para>No hassle with the Adobe EULA.</para></listitem> + +<listitem><para>No hassle with the question <quote>Where do I +get the ADOBE*.* driver files from?</quote></para></listitem> + +<listitem><para> +<indexterm><primary>PJL</primary></indexterm> +The Adobe drivers (on request of the printer PPD +associated with them) often put a PJL header in front of the main +PostScript part of the print file. Thus, the printfile starts with +<parameter><1B >%-12345X</parameter> or +<parameter><escape>%-12345X</parameter> instead +of <parameter>%!PS</parameter>). This leads to the +CUPS daemon auto-typing the incoming file as a print-ready file, +not initiating a pass through the <parameter>pstops</parameter> filter (to speak more +technically, it is not regarded as the generic MIME-type +<indexterm><primary>application/postscript</primary></indexterm> +<parameter>application/postscript</parameter>, but as +the more special MIME type +<indexterm><primary>application/cups.vnd-postscript</primary></indexterm> +<parameter>application/cups.vnd-postscript</parameter>), +which therefore also leads to the page accounting in +<parameter>/var/log/cups/page_log</parameter> not +receiving the exact number of pages; instead the dummy page number +of <quote>1</quote> is logged in a standard setup).</para></listitem> + +<listitem><para>The Adobe driver has more options to mis-configure the +PostScript generated by it (like setting it inadvertently to +<guilabel>Optimize for Speed</guilabel>, instead of +<guilabel>Optimize for Portability</guilabel>, which +could lead to CUPS being unable to process it).</para></listitem> + +<listitem><para>The CUPS PostScript driver output sent by Windows +clients to the CUPS server is guaranteed to auto-type +as the generic MIME type <parameter>application/postscript</parameter>, +thus passing through the CUPS <parameter>pstops</parameter> filter and logging the +correct number of pages in the <filename>page_log</filename> for +accounting and quota purposes.</para></listitem> + +<listitem><para>The CUPS PostScript driver supports the sending of +additional standard (IPP) print options by Windows NT/200x/XP clients. Such +additional print options are: naming the CUPS standard +<emphasis>banner pages</emphasis> (or the custom ones, should they be +installed at the time of driver download), using the CUPS +page-label option, setting a +job-priority, and setting the scheduled +time of printing (with the option to support additional +useful IPP job attributes in the future).</para></listitem> + +<listitem><para>The CUPS PostScript driver supports the inclusion of +the new <parameter>*cupsJobTicket</parameter> comments at the +beginning of the PostScript file (which could be used in the future +for all sort of beneficial extensions on the CUPS side, but which will +not disturb any other applications as they will regard it as a comment +and simply ignore it).</para></listitem> + +<listitem><para>The CUPS PostScript driver will be the heart of the +fully fledged CUPS IPP client for Windows NT/200x/XP to be released soon +(probably alongside the first beta release for CUPS +1.2).</para></listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Run cupsaddsmb (Quiet Mode)</title> + + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +<indexterm><primary>point 'n' print</primary></indexterm> +The <command>cupsaddsmb</command> command copies the needed files into your +<smbconfsection name="[print$]"/> share. Additionally, the PPD +associated with this printer is copied from +<filename>/etc/cups/ppd/</filename> to +<smbconfsection name="[print$]"/>. There the files wait for convenient +Windows client installations via Point'n'Print. Before we can run the +command successfully, we need to be sure that we can authenticate +toward Samba. If you have a small network, you are probably using user-level +security (<smbconfoption name="security">user</smbconfoption>). +</para> + +<para> +Here is an example of a successfully run <command>cupsaddsmb</command> command: +</para> + +<para><screen> +&rootprompt;<userinput>cupsaddsmb -U root infotec_IS2027</userinput> +Password for root required to access localhost via Samba: <userinput>['secret']</userinput> +</screen></para> + +<para> +To share <emphasis>all</emphasis> printers and drivers, use the +<option>-a</option> parameter instead of a printer name. Since +<command>cupsaddsmb</command> <quote>exports</quote> the printer drivers to Samba, it should be +obvious that it only works for queues with a CUPS driver associated. +</para> +</sect2> + +<sect2> +<title>Run cupsaddsmb with Verbose Output</title> + + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +Probably you want to see what's going on. Use the +<option>-v</option> parameter to get a more verbose output. The +output below was edited for better readability: all <quote>\</quote> at the end of +a line indicate that I inserted an artificial line break plus some +indentation here: +</para> + +<warning><para> +You will see the root password for the Samba account printed on +screen. +</para></warning> + +<para> + +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> + <screen> +&rootprompt;<userinput>cupsaddsmb -U root -v infotec_2105</userinput> +Password for root required to access localhost via &example.server.samba;: +Running command: smbclient //localhost/print\$ -N -U'root%secret' \ + -c 'mkdir W32X86; \ + put /var/spool/cups/tmp/3e98bf2d333b5 W32X86/infotec_2105.ppd; \ + put /usr/share/cups/drivers/cupsdrvr.dll W32X86/cupsdrvr.dll; \ + put /usr/share/cups/drivers/cupsui.dll W32X86/cupsui.dll; \ + put /usr/share/cups/drivers/cups.hlp W32X86/cups.hlp' +added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 +Domain=[CUPS-PRINT] OS=[UNIX] Server=[Samba 2.2.7a] +NT_STATUS_OBJECT_NAME_COLLISION making remote directory \W32X86 +putting file /var/spool/cups/tmp/3e98bf2d333b5 as \W32X86/infotec_2105.ppd +putting file /usr/share/cups/drivers/cupsdrvr.dll as \W32X86/cupsdrvr.dll +putting file /usr/share/cups/drivers/cupsui.dll as \W32X86/cupsui.dll +putting file /usr/share/cups/drivers/cups.hlp as \W32X86/cups.hlp + +Running command: rpcclient localhost -N -U'root%secret' + -c 'adddriver "Windows NT x86" \ + "infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL: \ + RAW:NULL"' +cmd = adddriver "Windows NT x86" \ + "infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL: \ + RAW:NULL" +Printer Driver infotec_2105 successfully installed. + +Running command: smbclient //localhost/print\$ -N -U'root%secret' \ +-c 'mkdir WIN40; \ + put /var/spool/cups/tmp/3e98bf2d333b5 WIN40/infotec_2105.PPD; \ + put /usr/share/cups/drivers/ADFONTS.MFM WIN40/ADFONTS.MFM; \ + put /usr/share/cups/drivers/ADOBEPS4.DRV WIN40/ADOBEPS4.DRV; \ + put /usr/share/cups/drivers/ADOBEPS4.HLP WIN40/ADOBEPS4.HLP; \ + put /usr/share/cups/drivers/DEFPRTR2.PPD WIN40/DEFPRTR2.PPD; \ + put /usr/share/cups/drivers/ICONLIB.DLL WIN40/ICONLIB.DLL; \ + put /usr/share/cups/drivers/PSMON.DLL WIN40/PSMON.DLL;' + added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 + Domain=[CUPS-PRINT] OS=[UNIX] Server=[Samba 2.2.7a] + NT_STATUS_OBJECT_NAME_COLLISION making remote directory \WIN40 + putting file /var/spool/cups/tmp/3e98bf2d333b5 as \WIN40/infotec_2105.PPD + putting file /usr/share/cups/drivers/ADFONTS.MFM as \WIN40/ADFONTS.MFM + putting file /usr/share/cups/drivers/ADOBEPS4.DRV as \WIN40/ADOBEPS4.DRV + putting file /usr/share/cups/drivers/ADOBEPS4.HLP as \WIN40/ADOBEPS4.HLP + putting file /usr/share/cups/drivers/DEFPRTR2.PPD as \WIN40/DEFPRTR2.PPD + putting file /usr/share/cups/drivers/ICONLIB.DLL as \WIN40/ICONLIB.DLL + putting file /usr/share/cups/drivers/PSMON.DLL as \WIN40/PSMON.DLL + + Running command: rpcclient localhost -N -U'root%secret' \ + -c 'adddriver "Windows 4.0" \ + "infotec_2105:ADOBEPS4.DRV:infotec_2105.PPD:NULL:ADOBEPS4.HLP: \ + PSMON.DLL:RAW:ADOBEPS4.DRV,infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL, \ + ADFONTS.MFM,DEFPRTR2.PPD,ICONLIB.DLL"' + cmd = adddriver "Windows 4.0" "infotec_2105:ADOBEPS4.DRV:\ + infotec_2105.PPD:NULL:ADOBEPS4.HLP:PSMON.DLL:RAW:ADOBEPS4.DRV,\ + infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL,ADFONTS.MFM,DEFPRTR2.PPD,\ + ICONLIB.DLL" + Printer Driver infotec_2105 successfully installed. + + Running command: rpcclient localhost -N -U'root%secret' \ + -c 'setdriver infotec_2105 infotec_2105' + cmd = setdriver infotec_2105 infotec_2105 + Successfully set infotec_2105 to driver infotec_2105. + +</screen></para> + +<para> +If you look closely, you'll discover your root password was transferred +unencrypted over the wire, so beware! Also, if you look further, +you'll discover error messages like <?latex \linebreak ?>NT_STATUS_OBJECT_NAME_COLLISION in between. They occur, because the directories WIN40 and W32X86 already existed in the <smbconfsection name="[print$]"/> driver download share (from a previous driver installation). They are harmless here. +</para> +</sect2> + +<sect2> +<title>Understanding cupsaddsmb</title> + + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +What has happened? What did <command>cupsaddsmb</command> do? There are five stages of +the procedure: +</para> + +<orderedlist> + <listitem><para> + <indexterm><primary>IPP</primary></indexterm> + Call the CUPS server via IPP and request the +driver files and the PPD file for the named printer.</para></listitem> + +<listitem><para>Store the files temporarily in the local +TEMPDIR (as defined in +<filename>cupsd.conf</filename>).</para></listitem> + +<listitem><para>Connect via smbclient to the Samba server's + <smbconfsection name="[print$]"/> share and put the files into the + share's WIN40 (for Windows 9x/Me) and W32X86/ (for Windows NT/200x/XP) subdirectories.</para></listitem> + +<listitem><para> +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> + Connect via rpcclient to the Samba server and +execute the <command>adddriver</command> command with the correct +parameters.</para></listitem> + +<listitem><para> +<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> + Connect via rpcclient to the Samba server a second +time and execute the <command>setdriver</command> command.</para></listitem> +</orderedlist> + +<note> +<para> +You can run the <command>cupsaddsmb</command> utility with parameters to +specify one remote host as Samba host and a second remote host as CUPS +host. Especially if you want to get a deeper understanding, it is a +good idea to try it and see more clearly what is going on (though in real +life most people will have their CUPS and Samba servers run on the +same host): +</para> + +<para><screen> +&rootprompt;<userinput>cupsaddsmb -H sambaserver -h cupsserver -v printer</userinput> +</screen></para> +</note> +</sect2> + +<sect2> +<title>How to Recognize If cupsaddsmb Completed Successfully</title> + +<para> +You <emphasis>must</emphasis> always check if the utility completed +successfully in all fields. You need as a minimum these three messages +among the output: +</para> + +<orderedlist> + +<listitem><para><emphasis>Printer Driver infotec_2105 successfully +installed.</emphasis> # (for the W32X86 == Windows NT/200x/XP +architecture).</para></listitem> + +<listitem><para><emphasis>Printer Driver infotec_2105 successfully +installed.</emphasis> # (for the WIN40 == Windows 9x/Me +architecture).</para></listitem> + +<listitem><para><emphasis>Successfully set [printerXPZ] to driver +[printerXYZ].</emphasis></para></listitem> +</orderedlist> + +<para> +These messages are probably not easily recognized in the general +output. If you run <command>cupsaddsmb</command> with the <option>-a</option> +parameter (which tries to prepare <emphasis>all</emphasis> active CUPS +printer drivers for download), you might miss if individual printers +drivers had problems installing properly. Here a redirection of the +output will help you analyze the results in retrospective. +</para> + +<para> +If you get: +<screen> +SetPrinter call failed! +result was WERR_ACCESS_DENIED +</screen> +It means that you might have set <smbconfoption name="use client driver">yes</smbconfoption> for this printer. +Set it to <quote>no</quote> will solve the problem. Refer to man samba(5) for explanantion on +<parameter>use client driver</parameter>. +</para> + +<note><para> +It is impossible to see any diagnostic output if you do not run +<command>cupsaddsmb</command> in verbose mode. Therefore, we strongly recommend to not +use the default quiet mode. It will hide any problems from you that +might occur. +</para></note> +</sect2> + +<sect2> +<title>cupsaddsmb with a Samba PDC</title> + + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +Can't get the standard <command>cupsaddsmb</command> command to run on a Samba PDC? +Are you asked for the password credential all over again and again and +the command just will not take off at all? Try one of these +variations: +</para> + +<para><screen> +&rootprompt;<userinput>cupsaddsmb -U &example.workgroup;\\root -v printername</userinput> +&rootprompt;<userinput>cupsaddsmb -H &example.pdc.samba; -U &example.workgroup;\\root -v printername</userinput> +&rootprompt;<userinput>cupsaddsmb -H &example.pdc.samba; -U &example.workgroup;\\root -h cups-server -v printername</userinput> +</screen></para> + +<para> +(Note the two backslashes: the first one is required to +<quote>escape</quote> the second one). +</para> +</sect2> + +<sect2> +<title>cupsaddsmb Flowchart</title> + +<para> +<indexterm><primary>cupsaddsmb</primary></indexterm> +<link linkend="small14">cupsaddsmb flowchart</link> shows a chart about the procedures, command-flows and +data-flows of the <command>cupaddsmb</command> command. Note again: cupsaddsmb is +not intended to, and does not work with, raw queues! +</para> + +<para> + <image id="small14"> + <imagedescription>cupsaddsmb flowchart.</imagedescription> + <imagefile>14small</imagefile></image> +</para> +</sect2> + +<sect2> +<title>Installing the PostScript Driver on a Client</title> + +<para> +<indexterm><primary>point 'n' print</primary></indexterm> +After <command>cupsaddsmb</command> is completed, your driver is prepared for the clients to +use. Here are the steps you must perform to download and install it +via Point'n'Print. From a Windows client, browse to the CUPS/Samba +server: +</para> + +<itemizedlist> + + +<listitem><para> +<indexterm><primary>"Printers" folder</primary></indexterm> +Open the <guilabel>Printers</guilabel> +share of Samba in Network Neighborhood.</para></listitem> + +<listitem><para>Right-click on the printer in +question.</para></listitem> + +<listitem><para>From the opening context-menu select +<guimenuitem>Install...</guimenuitem> or +<guimenuitem>Connect...</guimenuitem> (depending on the Windows version you +use).</para></listitem> +</itemizedlist> + +<para> +After a few seconds, there should be a new printer in your +client's <emphasis>local</emphasis> <guilabel>Printers</guilabel> folder. On Windows +XP it will follow a naming convention of <emphasis>PrinterName on +SambaServer</emphasis>. (In my current case it is "infotec_2105 on +kde-bitshop"). If you want to test it and send your first job from +an application like Winword, the new printer appears in a +<filename>\\SambaServer\PrinterName</filename> entry in the +drop-down list of available printers. +</para> + +<para> +<indexterm><primary>PPD</primary></indexterm> +<command>cupsaddsmb</command> will only reliably work with CUPS version 1.1.15 or higher +and Samba from 2.2.4. If it does not work, or if the automatic printer +driver download to the clients does not succeed, you can still manually +install the CUPS printer PPD on top of the Adobe PostScript driver on +clients. Then point the client's printer queue to the Samba printer +share for a UNC type of connection: +</para> + +<para><screen> +&dosprompt;<userinput>net use lpt1: \\sambaserver\printershare /user:ntadmin</userinput> +</screen></para> + +<para> +should you desire to use the CUPS networked PostScript RIP +functions. (Note that user <quote>ntadmin</quote> needs to be a valid Samba user +with the required privileges to access the printershare.) This +sets up the printer connection in the traditional +<emphasis>LanMan</emphasis> way (not using MS-RPC). +</para> +</sect2> + +<sect2> +<title>Avoiding Critical PostScript Driver Settings on the Client</title> + +<para> +Printing works, but there are still problems. Most jobs print +well, some do not print at all. Some jobs have problems with fonts, +which do not look very good. Some jobs print fast and some are +dead-slow. Many of these problems can be greatly reduced or even +completely eliminated if you follow a few guidelines. Remember, if +your print device is not PostScript-enabled, you are treating your +Ghostscript installation on your CUPS host with the output your client +driver settings produce. Treat it well: +</para> + +<itemizedlist> +<listitem><para>Avoid the PostScript Output Option: Optimize +for Speed setting. Use the Optimize for +Portability instead (Adobe PostScript +driver).</para></listitem> + +<listitem><para>Don't use the Page Independence: +NO setting. Instead, use Page Independence +YES (CUPS PostScript Driver).</para></listitem> + +<listitem><para>Recommended is the True Type Font +Downloading Option: Native True Type over +Automatic and Outline; you +should by all means avoid Bitmap (Adobe +PostScript Driver).</para></listitem> + +<listitem><para>Choose True Type Font: Download as Softfont +into Printer over the default Replace by Device +Font (for exotic fonts, you may need to change it back to +get a printout at all) (Adobe).</para></listitem> + +<listitem><para>Sometimes you can choose PostScript Language +Level: In case of problems try 2 +instead of 3 (the latest ESP Ghostscript package +handles Level 3 PostScript very well) (Adobe).</para></listitem> + +<listitem><para>Say Yes to PostScript +Error Handler (Adobe).</para></listitem> +</itemizedlist> +</sect2> +</sect1> + +<sect1> +<title>Installing PostScript Driver Files Manually Using rpcclient</title> + +<para> +Of course, you can run all the commands that are embedded into the +cupsaddsmb convenience utility yourself, one by one, and hereby upload +and prepare the driver files for future client downloads. +</para> + +<orderedlist> +<listitem><para>Prepare Samba (A CUPS print queue with the name of the +printer should be there. We are providing the driver +now).</para></listitem> + +<listitem><para>Copy all files to + <smbconfsection name="[print$]"/>.</para></listitem> + +<listitem><para> +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> +Run <command>rpcclient adddriver</command> +(for each client architecture you want to support).</para></listitem> + +<listitem><para> +<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> +Run <command>rpcclient +setdriver.</command></para></listitem> +</orderedlist> + +<para> +<indexterm><primary>rpcclient</primary><secondary>enumports</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>enumdrivers</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> +We are going to do this now. First, read the man page on <parameter>rpcclient</parameter> +to get a first idea. Look at all the printing related +subcommands. <command>enumprinters</command>, +<command>enumdrivers</command>, <command>enumports</command>, +<command>adddriver</command>, <command>setdriver</command> are among +the most interesting ones. <parameter>rpcclient</parameter> implements an important part of +the MS-RPC protocol. You can use it to query (and command) a Windows NT +(or 200x/XP) PC, too. MS-RPC is used by Windows clients, among other +things, to benefit from the Point'n'Print features. Samba can now +mimic this as well. +</para> + +<sect2> +<title>A Check of the rpcclient man Page</title> + +<para> + First let's check the <parameter>rpcclient</parameter> man page. Here are +two relevant passages: +</para> + +<para> +<command>adddriver <arch> <config></command> Execute an +<command>AddPrinterDriver()</command> RPC to install the printer driver information on +the server. The driver files should already exist in the +directory returned by <command>getdriverdir</command>. Possible +values for <parameter>arch</parameter> are the same as those for the +<command>getdriverdir</command> command. The +<parameter>config</parameter> parameter is defined as follows: +</para> + +<para><screen> +Long Printer Name:\ +Driver File Name:\ +Data File Name:\ +Config File Name:\ +Help File Name:\ +Language Monitor Name:\ +Default Data Type:\ +Comma Separated list of Files +</screen></para> + +<para>Any empty fields should be enter as the string <quote>NULL</quote>. </para> + +<para>Samba does not need to support the concept of Print Monitors +since these only apply to local printers whose driver can make use of +a bi-directional link for communication. This field should be <quote>NULL</quote>. +On a remote NT print server, the Print Monitor for a driver must +already be installed prior to adding the driver or else the RPC will +fail. +</para> + +<para> +<command>setdriver <printername> <drivername></command> +Execute a <command>SetPrinter()</command> command to update the +printer driver associated with an installed printer. The printer +driver must already be correctly installed on the print server. +</para> + +<para>See also the <command>enumprinters</command> and <command>enumdrivers</command> commands for +obtaining a list of installed printers and drivers. +</para> + +</sect2> + +<sect2> +<title>Understanding the rpcclient man Page</title> + +<para> +The <emphasis>exact</emphasis> format isn't made too clear by the man +page, since you have to deal with some parameters containing +spaces. Here is a better description for it. We have line-broken the +command and indicated the breaks with <quote>\</quote>. Usually you would type the +command in one line without the line-breaks: +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> +</para> + +<para><screen> + adddriver "Architecture" \ + "LongPrinterName:DriverFile:DataFile:ConfigFile:HelpFile:\ + LanguageMonitorFile:DataType:ListOfFiles,Comma-separated" +</screen></para> + +<para> +What the man pages denote as a simple <parameter><config></parameter> +keyword, in reality consists of eight colon-separated fields. The +last field may take multiple (in some very insane cases, even +20 different additional) files. This might sound confusing at first. +What the man pages names the <quote>LongPrinterName</quote> in +reality should be called the <quote>Driver Name</quote>. You can name it +anything you want, as long as you use this name later in the +<command>rpcclient ... setdriver</command> command. For +practical reasons, many name the driver the same as the +printer. +</para> + +<para> +It isn't simple at all. I hear you asking: +<quote>How do I know which files are "Driver +File</quote>, <quote>Data File</quote>, <quote>Config File</quote>, <quote>Help File</quote> and <quote>Language +Monitor File" in each case?</quote> &smbmdash; For an answer, you may +want to have a look at how a Windows NT box with a shared printer +presents the files to us. Remember, that this whole procedure has +to be developed by the Samba team by overhearing the traffic caused +by Windows computers on the wire. We may as well turn to a Windows +box now and access it from a UNIX workstation. We will query it +with <command>rpcclient</command> to see what it tells us and +try to understand the man page more clearly that we've read just +now. +</para> +</sect2> + +<sect2> +<title>Producing an Example by Querying a Windows Box</title> + +<para> + <indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> + <indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> +We could run <command>rpcclient</command> with a +<command>getdriver</command> or a <command>getprinter</command> +subcommand (in level 3 verbosity) against it. Just sit down at a UNIX or +Linux workstation with the Samba utilities installed, then type the +following command: +</para> + +<para><screen> +&rootprompt;<userinput>rpcclient -U'user%secret' NT-SERVER -c 'getdriver printername 3'</userinput> +</screen></para> + +<para> +From the result it should become clear which is which. Here is an example from my installation: +</para> + +<para> +<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> + <screen> +&rootprompt;<userinput>rpcclient -U'Danka%xxxx' W200xSERVER \ + -c'getdriver "DANKA InfoStream Virtual Printer" 3'</userinput> + cmd = getdriver "DANKA InfoStream Virtual Printer" 3 + + [Windows NT x86] + Printer Driver Info 3: + Version: [2] + Driver Name: [DANKA InfoStream] + Architecture: [Windows NT x86] + Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.DLL] + Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\INFOSTRM.PPD] + Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRPTUI.DLL] + Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.HLP] + + Dependentfiles: [] + Dependentfiles: [] + Dependentfiles: [] + Dependentfiles: [] + Dependentfiles: [] + Dependentfiles: [] + Dependentfiles: [] + + Monitorname: [] + Defaultdatatype: [] + +</screen></para> + +<para> +Some printer drivers list additional files under the label +<parameter>Dependentfiles</parameter> and these would go into the last field +<parameter>ListOfFiles,Comma-separated</parameter>. For the CUPS +PostScript drivers, we do not need any (nor would we for the Adobe +PostScript driver), therefore, the field will get a <quote>NULL</quote> entry. +</para> +</sect2> + +<sect2> +<title>Requirements for adddriver and setdriver to Succeed</title> + +<para> +>From the man page (and from the quoted output +of <command>cupsaddsmb</command> above) it becomes clear that you +need to have certain conditions in order to make the manual uploading +and initializing of the driver files succeed. The two <command>rpcclient</command> +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> +subcommands (<command>adddriver</command> and +<command>setdriver</command>) need to encounter the following +preconditions to complete successfully: +</para> +<itemizedlist> + +<listitem><para>You are connected as <smbconfoption name="printer admin"/> or root (this is <emphasis>not</emphasis> the <quote>Printer Operators</quote> group in +NT, but the <emphasis>printer admin</emphasis> group as defined in +the <smbconfsection name="[global]"/> section of +&smb.conf;).</para></listitem> + +<listitem><para>Copy all required driver files to +<filename>\\SAMBA\print$\w32x86</filename> and +<filename>\\SAMBA\print$\win40</filename> as appropriate. They +will end up in the <quote>0</quote> respective <quote>2</quote> subdirectories later. For now, +<emphasis>do not</emphasis> put them there, they'll be automatically +used by the <command>adddriver</command> subcommand. (If you use +<command>smbclient</command> to put the driver files into the share, note that you need +to escape the <quote>$</quote>: <command>smbclient //sambaserver/print\$ -U +root.</command>)</para></listitem> + +<listitem><para>The user you're connecting as must be able to write to +the <smbconfsection name="[print$]"/> share and create +subdirectories.</para></listitem> + +<listitem><para>The printer you are going to setup for the Windows +clients needs to be installed in CUPS already.</para></listitem> + +<listitem><para> + <indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> + <indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> + The CUPS printer must be known to Samba, otherwise the +<command>setdriver</command> subcommand fails with an +NT_STATUS_UNSUCCESSFUL error. To check if the printer is known by +Samba, you may use the <command>enumprinters</command> subcommand to +<command>rpcclient</command>. A long-standing bug prevented a proper update of the +printer list until every smbd process had received a SIGHUP or was +restarted. Remember this in case you've created the CUPS printer just +recently and encounter problems: try restarting +Samba.</para></listitem> +</itemizedlist> +</sect2> + +<sect2> +<title>Manual Driver Installation in 15 Steps</title> + +<para> +We are going to install a printer driver now by manually executing all +required commands. As this may seem a rather complicated process at +first, we go through the procedure step by step, explaining every +single action item as it comes up. +</para> + +<procedure> + <title>Manual Driver Installation</title> + +<step> +<title>Install the printer on CUPS.</title> + +<para><screen> +&rootprompt;<userinput>lpadmin -p mysmbtstprn -v socket://10.160.51.131:9100 -E \ + -P canonIR85.ppd</userinput> +</screen></para> + +<para> +This installs a printer with the name <parameter>mysmbtstprn</parameter> +to the CUPS system. The printer is accessed via a socket +(a.k.a. JetDirect or Direct TCP/IP) connection. You need to be root +for this step. +</para> +</step> + +<step> +<title>(Optional) Check if the printer is recognized by Samba.</title> + +<para> +<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> +<screen> + &rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumprinters' localhost \ + | grep -C2 mysmbtstprn</userinput> +flags:[0x800000] +name:[\\kde-bitshop\mysmbtstprn] +description:[\\kde-bitshop\mysmbtstprn,,mysmbtstprn] +comment:[mysmbtstprn] +</screen></para> + +<para> +This should show the printer in the list. If not, stop and restart +the Samba daemon (smbd), or send a HUP signal: +<screen> +&rootprompt;<userinput>kill -HUP `pidof smbd`</userinput> +</screen>Check again. Troubleshoot and repeat until +successful. Note the <quote>empty</quote> field between the two commas in the +<quote>description</quote> line. The driver name would appear here if there was one already. You need to know root's Samba password (as set by the +<command>smbpasswd</command> command) for this step and most of the +following steps. Alternately, you can authenticate as one of the +users from the <quote>write list</quote> as defined in &smb.conf; for +<smbconfsection name="[print$]"/>. +</para> +</step> + +<step> +<title>(Optional) Check if Samba knows a driver for the printer.</title> + +<para> + <indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> + <indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> + <screen> +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ + | grep driver </userinput> +drivername:[] + +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ + | grep -C4 driv</userinput> +servername:[\\kde-bitshop] +printername:[\\kde-bitshop\mysmbtstprn] +sharename:[mysmbtstprn] +portname:[Samba Printer Port] +drivername:[] +comment:[mysmbtstprn] +location:[] +sepfile:[] +printprocessor:[winprint] + +&rootprompt;<userinput>rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost</userinput> + result was WERR_UNKNOWN_PRINTER_DRIVER + +</screen></para> + +<para> +None of the three commands shown above should show a driver. +This step was done for the purpose of demonstrating this condition. An +attempt to connect to the printer at this stage will prompt the +message along the lines of: <quote>The server does not have the required printer +driver installed.</quote> +</para> +</step> + +<step> +<title>Put all required driver files into Samba's +[print$].</title> + +<para><screen> +&rootprompt;<userinput>smbclient //localhost/print\$ -U 'root%xxxx' \ + -c 'cd W32X86; \ + put /etc/cups/ppd/mysmbtstprn.ppd mysmbtstprn.PPD; \ + put /usr/share/cups/drivers/cupsui.dll cupsui.dll; \ + put /usr/share/cups/drivers/cupsdrvr.dll cupsdrvr.dll; \ + put /usr/share/cups/drivers/cups.hlp cups.hlp'</userinput> +</screen></para> + +<para> +(This command should be entered in one long single +line. Line-breaks and the line-end indicated by <quote>\</quote> have been inserted +for readability reasons.) This step is <emphasis>required</emphasis> +for the next one to succeed. It makes the driver files physically +present in the <smbconfsection name="[print$]"/> share. However, clients +would still not be able to install them, because Samba does not yet +treat them as driver files. A client asking for the driver would still +be presented with a <quote>not installed here</quote> message. +</para> +</step> + +<step> +<title>Verify where the driver files are now.</title> + +<para><screen> +&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/</userinput> +total 669 +drwxr-sr-x 2 root ntadmin 532 May 25 23:08 2 +drwxr-sr-x 2 root ntadmin 670 May 16 03:15 3 +-rwxr--r-- 1 root ntadmin 14234 May 25 23:21 cups.hlp +-rwxr--r-- 1 root ntadmin 278380 May 25 23:21 cupsdrvr.dll +-rwxr--r-- 1 root ntadmin 215848 May 25 23:21 cupsui.dll +-rwxr--r-- 1 root ntadmin 169458 May 25 23:21 mysmbtstprn.PPD +</screen></para> + +<para> +The driver files now are in the W32X86 architecture <quote>root</quote> of +<smbconfsection name="[print$]"/>. +</para> +</step> + +<step> +<title>Tell Samba that these are driver files (<command>adddriver</command>).</title> + +<para> +<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> +<screen> +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'adddriver "Windows NT x86" \ + "mydrivername:cupsdrvr.dll:mysmbtstprn.PPD: \ + cupsui.dll:cups.hlp:NULL:RAW:NULL"' \ + localhost</userinput> +Printer Driver mydrivername successfully installed. +</screen></para> + +<para> +You cannot repeat this step if it fails. It could fail even +as a result of a simple typo. It will most likely have moved a part of +the driver files into the <quote>2</quote> subdirectory. If this step fails, you +need to go back to the fourth step and repeat it before you can try +this one again. In this step, you need to choose a name for your +driver. It is normally a good idea to use the same name as is used for +the printer name; however, in big installations you may use this driver +for a number of printers that obviously have different names, so the +name of the driver is not fixed. +</para> +</step> + +<step> +<title>Verify where the driver files are now.</title> + +<para><screen> +&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/</userinput> +total 1 +drwxr-sr-x 2 root ntadmin 532 May 25 23:22 2 +drwxr-sr-x 2 root ntadmin 670 May 16 03:15 3 + +&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/2</userinput> +total 5039 +[....] +-rwxr--r-- 1 root ntadmin 14234 May 25 23:21 cups.hlp +-rwxr--r-- 1 root ntadmin 278380 May 13 13:53 cupsdrvr.dll +-rwxr--r-- 1 root ntadmin 215848 May 13 13:53 cupsui.dll +-rwxr--r-- 1 root ntadmin 169458 May 25 23:21 mysmbtstprn.PPD +</screen></para> + +<para> +Notice how step 6 also moved the driver files to the appropriate +subdirectory. Compare this with the situation after step 5. +</para> +</step> + +<step> +<title>(Optional) Verify if Samba now recognizes the driver.</title> + +<para> +<indexterm><primary>rpcclient</primary><secondary>enumdrivers</secondary></indexterm> +<screen> +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumdrivers 3' \ + localhost | grep -B2 -A5 mydrivername</userinput> +Printer Driver Info 3: +Version: [2] +Driver Name: [mydrivername] +Architecture: [Windows NT x86] +Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll] +Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD] +Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll] +Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp] +</screen></para> + +<para> +Remember, this command greps for the name you chose for the +driver in step 6. This command must succeed before you can proceed. +</para> +</step> + +<step> +<para>Tell Samba which printer should use these driver files (<command>setdriver</command>).</para> + + +<para> +<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> +<screen> +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'setdriver mysmbtstprn mydrivername' \ + localhost</userinput> +Successfully set mysmbtstprn to driver mydrivername +</screen></para> + +<para> +Since you can bind any printername (print queue) to any driver, this +is a convenient way to setup many queues that use the same +driver. You do not need to repeat all the previous steps for the +setdriver command to succeed. The only preconditions are: +<command>enumdrivers</command> must find the driver and +<command>enumprinters</command> must find the printer. +</para> +</step> + +<step> + <title>(Optional) Verify if Samba has recognized this association.</title> + +<para> +<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> +<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> +<screen> +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ + | grep driver</userinput> +drivername:[mydrivername] + +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ + | grep -C4 driv</userinput> +servername:[\\kde-bitshop] +printername:[\\kde-bitshop\mysmbtstprn] +sharename:[mysmbtstprn] +portname:[Done] +drivername:[mydrivername] +comment:[mysmbtstprn] +location:[] +sepfile:[] +printprocessor:[winprint] + +&rootprompt;<userinput>rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost</userinput> +[Windows NT x86] +Printer Driver Info 3: + Version: [2] + Driver Name: [mydrivername] + Architecture: [Windows NT x86] + Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll] + Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD] + Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll] + Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp] + Monitorname: [] + Defaultdatatype: [RAW] + Monitorname: [] + Defaultdatatype: [RAW] + +&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumprinters' localhost \ + | grep mysmbtstprn</userinput> + name:[\\kde-bitshop\mysmbtstprn] + description:[\\kde-bitshop\mysmbtstprn,mydrivername,mysmbtstprn] + comment:[mysmbtstprn] + +</screen></para> + +<para> +<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> +Compare these results with the ones from steps 2 and 3. Every one of these commands show the driver is installed. Even +the <command>enumprinters</command> command now lists the driver +on the <quote>description</quote> line. +</para> +</step> + +<step> +<title>(Optional) Tickle the driver into a correct +device mode.</title> + +<para> +<indexterm><primary>"Printers" folder</primary></indexterm> +You certainly know how to install the driver on the client. In case +you are not particularly familiar with Windows, here is a short +recipe: Browse the Network Neighborhood, go to the Samba server, and look +for the shares. You should see all shared Samba printers. +Double-click on the one in question. The driver should get +installed and the network connection set up. An alternate way is to +open the <guilabel>Printers (and Faxes)</guilabel> folder, right-click on the printer in +question and select <guilabel>Connect</guilabel> or <guilabel>Install</guilabel>. As a result, a new printer +should have appeared in your client's local <guilabel>Printers (and Faxes)</guilabel> +folder, named something like <guilabel>printersharename on Sambahostname</guilabel>. +</para> + +<para> +It is important that you execute this step as a Samba printer admin +(as defined in &smb.conf;). Here is another method +to do this on Windows XP. It uses a command line, which you may type +into the <quote>DOS box</quote> (type root's smbpassword when prompted): +</para> + +<para><screen> +&dosprompt;<userinput>runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry \ + /in /n \\sambaserver\mysmbtstprn"</userinput> +</screen></para> + +<para> +Change any printer setting once (like changing <emphasis><guilabel>portrait</guilabel> to + <guilabel>landscape</guilabel></emphasis>), click on <guibutton>Apply</guibutton>; change the setting +back. +</para> +</step> + +<step> +<title>Install the printer on a client +(Point'n'Print).</title> + + +<para> +<indexterm significance="preferred"><primary>point 'n' print</primary></indexterm> + <screen> +&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /in /n "\\sambaserver\mysmbtstprn"</userinput> +</screen></para> + +<para> +If it does not work it could be a permission problem with the +<smbconfsection name="[print$]"/> share. +</para> +</step> + +<step> +<title>(Optional) Print a test page.</title> + +<para><screen> +&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /p /n "\\sambaserver\mysmbtstprn"</userinput> +</screen></para> + +<para> +Then hit [TAB] five times, [ENTER] twice, [TAB] once and [ENTER] again +and march to the printer. +</para> +</step> + +<step> +<title>(Recommended) Study the test page.</title> + +<para> +Hmmm.... just kidding! By now you know everything about printer +installations and you do not need to read a word. Just put it in a +frame and bolt it to the wall with the heading "MY FIRST +RPCCLIENT-INSTALLED PRINTER" &smbmdash; why not just throw it away! +</para> +</step> + +<step> +<title>(Obligatory) Enjoy. Jump. Celebrate your +success.</title> + +<para><screen> +&rootprompt;<userinput>echo "Cheeeeerioooooo! Success..." >> /var/log/samba/log.smbd</userinput> +</screen></para> +</step> +</procedure> +</sect2> + +<sect2> +<title>Troubleshooting Revisited</title> + +<para> +The setdriver command will fail, if in Samba's mind the queue is not +already there. You had promising messages about the: +</para> + +<para><screen> + Printer Driver ABC successfully installed. +</screen></para> + +<para> +after the <command>adddriver</command> parts of the procedure? But you are also seeing +a disappointing message like this one? +</para> + +<para><computeroutput> + result was NT_STATUS_UNSUCCESSFUL +</computeroutput></para> + +<para> +<indexterm><primary>lpstat</primary></indexterm> +It is not good enough that you +can see the queue in CUPS, using +the <command>lpstat -p ir85wm</command> command. A +bug in most recent versions of Samba prevents the proper update of +the queue-list. The recognition of newly installed CUPS printers +fails unless you restart Samba or send a HUP to all smbd +processes. To verify if this is the reason why Samba does not +execute the <command>setdriver</command> command successfully, check if Samba <quote>sees</quote> +the printer: +</para> + +<para> +<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> + <screen> +&rootprompt;<userinput>rpcclient transmeta -N -U'root%xxxx' -c 'enumprinters 0'|grep ir85wm</userinput> + printername:[ir85wm] +</screen></para> + +<para> +An alternate command could be this: +</para> + +<para> +<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> + <screen> +&rootprompt;<userinput>rpcclient transmeta -N -U'root%secret' -c 'getprinter ir85wm' </userinput> + cmd = getprinter ir85wm + flags:[0x800000] + name:[\\transmeta\ir85wm] + description:[\\transmeta\ir85wm,ir85wm,DPD] + comment:[CUPS PostScript-Treiber for Windows NT/200x/XP] +</screen></para> + +<para> +By the way, you can use these commands, plus a few more, of course, +to install drivers on remote Windows NT print servers too! +</para> +</sect2> +</sect1> + +<sect1> +<title>The Printing <filename>*.tdb</filename> Files</title> + +<para> +<indexterm><primary>TDB</primary></indexterm> +<indexterm><primary>connections.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>printing.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>share_info.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>ntdrivers.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>unexpected.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>brlock.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>locking.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>ntforms.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>messages.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>ntprinters.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>sessionid.tdb</primary><seealso>TDB</seealso></indexterm> +<indexterm><primary>secrets.tdb</primary><seealso>TDB</seealso></indexterm> +Some mystery is associated with the series of files with a +tdb suffix appearing in every Samba installation. They are +<filename>connections.tdb</filename>, +<filename>printing.tdb</filename>, +<filename>share_info.tdb</filename>, +<filename>ntdrivers.tdb</filename>, +<filename>unexpected.tdb</filename>, +<filename>brlock.tdb</filename>, +<filename>locking.tdb</filename>, +<filename>ntforms.tdb</filename>, +<filename>messages.tdb</filename> , +<filename>ntprinters.tdb</filename>, +<filename>sessionid.tdb</filename> and +<filename>secrets.tdb</filename>. What is their purpose? +</para> + +<sect2> +<title>Trivial Database Files</title> + +<para> +<indexterm><primary>TDB</primary></indexterm> +A Windows NT (print) server keeps track of all information needed to serve +its duty toward its clients by storing entries in the Windows +registry. Client queries are answered by reading from the registry, +Administrator or user configuration settings that are saved by writing into +the registry. Samba and UNIX obviously do not have such a +Registry. Samba instead keeps track of all client related information in a +series of <filename>*.tdb</filename> files. (TDB = Trivial Data +Base). These are often located in <filename>/var/lib/samba/</filename> +or <filename>/var/lock/samba/</filename>. The printing related files +are <filename>ntprinters.tdb</filename>, +<filename>printing.tdb</filename>,<filename>ntforms.tdb</filename> and +<filename>ntdrivers.tdb</filename>. +</para> +</sect2> + +<sect2> +<title>Binary Format</title> + +<para> +<filename>*.tdb</filename> files are not human readable. They are +written in a binary format. <quote>Why not ASCII?</quote>, you may ask. <quote>After all, +ASCII configuration files are a good and proven tradition on UNIX.</quote> +The reason for this design decision by the Samba team is mainly +performance. Samba needs to be fast; it runs a separate +<command>smbd</command> process for each client connection, in some +environments many thousands of them. Some of these smbds might need to +write-access the same <filename>*.tdb</filename> file <emphasis>at the +same time</emphasis>. The file format of Samba's +<filename>*.tdb</filename> files allows for this provision. Many smbd +processes may write to the same <filename>*.tdb</filename> file at the +same time. This wouldn't be possible with pure ASCII files. +</para> +</sect2> + +<sect2> +<title>Losing <filename>*.tdb</filename> Files</title> + +<para> +It is very important that all <filename>*.tdb</filename> files remain +consistent over all write and read accesses. However, it may happen +that these files <emphasis>do</emphasis> get corrupted. (A +<command>kill -9 `pidof smbd'</command> while a write access is in +progress could do the damage as well as a power interruption, +etc.). In cases of trouble, a deletion of the old printing-related +<filename>*.tdb</filename> files may be the only option. After that you need to +re-create all print-related setup or you have made a +backup of the <filename>*.tdb</filename> files in time. +</para> +</sect2> + +<sect2> +<title>Using <command>tdbbackup</command></title> + + +<para> +<indexterm><primary>TDB</primary><secondary>backing up</secondary><see>tdbbackup</see></indexterm> +<indexterm><primary>tdbbackup</primary></indexterm> +Samba ships with a little utility that helps the root user of your +system to backup your <filename>*.tdb</filename> files. If you run it +with no argument, it prints a usage message: +</para> + +<para><screen> +&rootprompt;<userinput>tdbbackup</userinput> + Usage: tdbbackup [options] <fname...> + + Version:3.0a + -h this help message + -s suffix set the backup suffix + -v verify mode (restore if corrupt) + +</screen></para> + +<para> +Here is how I backed up my <filename>printing.tdb</filename> file: +</para> + +<para><screen> +&rootprompt;<userinput>ls</userinput> +. browse.dat locking.tdb ntdrivers.tdb printing.tdb +.. share_info.tdb connections.tdb messages.tdb ntforms.tdb +printing.tdbkp unexpected.tdb brlock.tdb gmon.out namelist.debug +ntprinters.tdb sessionid.tdb + +&rootprompt;<userinput>tdbbackup -s .bak printing.tdb</userinput> + printing.tdb : 135 records + +&rootprompt;<userinput>ls -l printing.tdb*</userinput> + -rw------- 1 root root 40960 May 2 03:44 printing.tdb + -rw------- 1 root root 40960 May 2 03:44 printing.tdb.bak + +</screen></para> +</sect2> +</sect1> + +<sect1> +<title>CUPS Print Drivers from Linuxprinting.org</title> + + +<para> +<indexterm><primary>Linuxprinting.org</primary></indexterm> +CUPS ships with good support for HP LaserJet-type printers. You can +install the generic driver as follows: +</para> + + +<para> +<indexterm><primary>lpadmin</primary></indexterm> + <screen> +&rootprompt;<userinput>lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd</userinput> +</screen></para> + +<para> +The <option>-m</option> switch will retrieve the +<filename>laserjet.ppd</filename> from the standard repository for +not-yet-installed-PPDs, which CUPS typically stores in +<filename>/usr/share/cups/model</filename>. Alternately, you may use +<option>-P /path/to/your.ppd</option>. +</para> + +<para> +The generic <filename>laserjet.ppd,</filename> however, does not support every special option +for every LaserJet-compatible model. It constitutes a sort of <quote>least common +denominator</quote> of all the models. If for some reason +you must pay for the commercially available ESP Print Pro drivers, your +first move should be to consult the database on the +<ulink noescape="1" url="http://www.linuxprinting.org/printer_list.cgi">Linuxprinting</ulink> web site. +Linuxprinting.org has excellent recommendations about which driver is +best used for each printer. Its database is kept current by the +tireless work of Till Kamppeter from MandrakeSoft, who is also the +principal author of the <command>foomatic-rip</command> utility. +</para> + +<note><para> +<indexterm><primary>foomatic-rip</primary></indexterm> +The former <command>cupsomatic</command> concept is now being replaced by the new +successor, a much +more powerful <command>foomatic-rip</command>. +<command>cupsomatic</command> is no longer maintained. Here is the new URL +to the <ulink noescape="1" url="http://www.linuxprinting.org/driver_list.cgi">Foomatic-3.0</ulink> database. +If you upgrade to <command>foomatic-rip</command>, remember to also upgrade to the +new-style PPDs for your Foomatic-driven printers. foomatic-rip will +not work with PPDs generated for the old <command>cupsomatic</command>. The new-style +PPDs are 100% compliant to the Adobe PPD specification. They are +also intended to be used by Samba and the cupsaddsmb utility, to +provide the driver files for the Windows clients! +</para></note> + +<sect2> +<title>foomatic-rip and Foomatic Explained</title> + + +<para> +<indexterm significance="preferred"><primary>foomatic</primary></indexterm> +<indexterm significance="preferred"><primary>foomatic-rip</primary></indexterm> +Nowadays, most Linux distributions rely on the utilities of Linuxprinting.org +to create their printing-related software (which, by the way, works on all +UNIXes and on Mac OS X or Darwin, too). It is not known as well as it +should be, that it also has a very end-user-friendly interface that +allows for an easy update of drivers and PPDs for all supported +models, all spoolers, all operating systems, and all package formats +(because there is none). Its history goes back a few years. +</para> + +<para> +Recently, Foomatic has achieved the astonishing milestone of <ulink +url="http://www.linuxprinting.org/printer_list.cgi?make=Anyone">1000 +listed</ulink> printer models. Linuxprinting.org keeps all the +important facts about printer drivers, supported models and which +options are available for the various driver/printer combinations in +its <ulink +url="http://www.linuxprinting.org/foomatic.html">Foomatic</ulink> +database. Currently there are <ulink +url="http://www.linuxprinting.org/driver_list.cgi">245 drivers</ulink> +in the database. Many drivers support various models, and many models +may be driven by different drivers &smbmdash; its your choice! +</para> + +<sect3> +<title>690 <quote>Perfect</quote> Printers</title> + +<para> +At present, there are 690 devices dubbed as working perfectly, 181 +mostly, 96 partially, and 46 are paperweights. Keeping in mind +that most of these are non-PostScript models (PostScript printers are +automatically supported by CUPS to perfection, by using +their own manufacturer-provided Windows-PPD), and that a +multi-functional device never qualifies as working perfectly if it +does not also scan and copy and fax under GNU/Linux &smbmdash; then this is a +truly astonishing achievement! Three years ago the number was not +more than 500, and Linux or UNIX printing at the time wasn't +anywhere near the quality it is today. +</para> +</sect3> + +<sect3> +<title>How the Printing HOWTO Started It All</title> + +<para> +A few years ago <ulink url="http://www2.picante.com:81/~gtaylor/">Grant Taylor</ulink> +started it all. The roots of today's Linuxprinting.org are in the +first <ulink url="http://www.linuxprinting.org/foomatic2.9/howto/">Linux Printing +HOWTO</ulink> that he authored. As a side-project to this document, +which served many Linux users and Admins to guide their first steps in +this complicated and delicate setup (to a scientist, printing is +<quote>applying a structured deposition of distinct patterns of ink or toner +particles on paper substrates</quote>, he started to +build in a little Postgres database with information about the +hardware and driver zoo that made up Linux printing of the time. This +database became the core component of today's Foomatic collection of +tools and data. In the meantime, it has moved to an XML representation +of the data. +</para> +</sect3> + +<sect3> +<title>Foomatic's Strange Name</title> + + +<para> +<indexterm><primary>foomatic</primary></indexterm> +<quote>Why the funny name?</quote> you ask. When it really took off, around spring +2000, CUPS was far less popular than today, and most systems used LPD, +LPRng or even PDQ to print. CUPS shipped with a few generic drivers +(good for a few hundred different printer models). These didn't +support many device-specific options. CUPS also shipped with its own +built-in rasterization filter (<parameter>pstoraster</parameter>, derived from +Ghostscript). On the other hand, CUPS provided brilliant support for +<emphasis>controlling</emphasis> all printer options through +standardized and well-defined PPD files (PostScript Printers +Description files). Plus, CUPS was designed to be easily extensible. +</para> + +<para> +Taylor already had in his database a respectable compilation +of facts about many more printers and the Ghostscript <quote>drivers</quote> +they run with. His idea, to generate PPDs from the database information +and use them to make standard Ghostscript filters work within CUPS, +proved to work very well. It also killed several birds with one +stone: +</para> + +<itemizedlist> +<listitem><para>It made all current and future Ghostscript filter +developments available for CUPS.</para></listitem> + +<listitem><para>It made available a lot of additional printer models +to CUPS users (because often the traditional Ghostscript way of +printing was the only one available).</para></listitem> + +<listitem><para>It gave all the advanced CUPS options (Web interface, +GUI driver configurations) to users wanting (or needing) to use +Ghostscript filters.</para></listitem> +</itemizedlist> +</sect3> + +<sect3> +<title>cupsomatic, pdqomatic, lpdomatic, directomatic</title> + + +<para> +<indexterm><primary>cupsomatic</primary></indexterm> +<indexterm><primary>CUPS-PPD</primary></indexterm> +<indexterm><primary>PPD</primary><secondary>CUPS</secondary><see>CUPS-PPD</see></indexterm> +CUPS worked through a quickly-hacked up filter script named <ulink +url="http://www.linuxprinting.org/download.cgi?filename=cupsomatic&show=0">cupsomatic.</ulink> +cupsomatic ran the printfile through Ghostscript, constructing +automatically the rather complicated command line needed. It just +needed to be copied into the CUPS system to make it work. To +configure the way cupsomatic controls the Ghostscript rendering +process, it needs a CUPS-PPD. This PPD is generated directly from the +contents of the database. For CUPS and the respective printer/filter +combo, another Perl script named CUPS-O-Matic did the PPD +generation. After that was working, Taylor implemented within a few +days a similar thing for two other spoolers. Names chosen for the +config-generator scripts were <ulink +url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&show=0">PDQ-O-Matic</ulink> +(for PDQ) and <ulink +url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&show=0">LPD-O-Matic</ulink> +(for &smbmdash; you guessed it &smbmdash; LPD); the configuration here didn't use PPDs +but other spooler-specific files. +</para> + +<para> +From late summer of that year, <ulink url="http://www.linuxprinting.org/till/">Till Kamppeter</ulink> +started to put work into the database. Kamppeter had been newly employed by +<ulink url="http://www.mandrakesoft.com/">MandrakeSoft</ulink> to +convert its printing system over to CUPS, after they had seen his +<ulink url="http://www.fltk.org/">FLTK</ulink>-based <ulink +url="http://cups.sourceforge.net/xpp/">XPP</ulink> (a GUI front-end to +the CUPS lp-command). He added a huge amount of new information and new +printers. He also developed the support for other spoolers, like +<ulink url="http://ppr.sourceforge.net/">PPR</ulink> (via ppromatic), +<ulink url="http://sourceforge.net/projects/lpr/">GNUlpr</ulink> and +<ulink url="http://www.lprng.org/">LPRng</ulink> (both via an extended +lpdomatic) and spooler-less printing (<ulink +url="http://www.linuxprinting.org/download.cgi?filename=directomatic&show=0">directomatic</ulink>). +</para> + +<para> +So, to answer your question: <quote>Foomatic</quote> is the general name for all +the overlapping code and data behind the <quote>*omatic</quote> scripts. +Foomatic, up to versions 2.0.x, required (ugly) Perl data structures +attached to Linuxprinting.org PPDs for CUPS. It had a different +<quote>*omatic</quote> script for every spooler, as well as different printer +configuration files. +</para> +</sect3> + +<sect3> +<title>The <emphasis>Grand Unification</emphasis> Achieved</title> + + +<para> +<indexterm><primary>foomatic-rip</primary></indexterm> +This has all changed in Foomatic versions 2.9 (beta) and released as +<quote>stable</quote> 3.0. It has now achieved the convergence of all *omatic +scripts and is called the <ulink +url="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&show=0">foomatic-rip.</ulink> +This single script is the unification of the previously different +spooler-specific *omatic scripts. foomatic-rip is used by all the +different spoolers alike and because it can read PPDs (both the +original PostScript printer PPDs and the Linuxprinting.org-generated +ones), all of a sudden all supported spoolers can have the power of +PPDs at their disposal. Users only need to plug foomatic-rip into +their system. For users there is improved media type and source +support &smbmdash; paper sizes and trays are easier to configure. +</para> + +<para> +Also, the New Generation of Linuxprinting.org PPDs no longer contains +Perl data structures. If you are a distro maintainer and have +used the previous version of Foomatic, you may want to give the new +one a spin, but remember to generate a new-version set of PPDs +via the new <ulink +url="http://www.linuxprinting.org/download/foomatic/foomatic-db-engine-3.0.0beta1.tar.gz">foomatic-db-engine!</ulink> +Individual users just need to generate a single new PPD specific to +their model by <ulink +url="http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/II.Foomatic-User/II.tutorial-handout-foomatic-user.html">following +the steps</ulink> outlined in the Foomatic tutorial or in this chapter. This new development is truly amazing. +</para> + +<para> +foomatic-rip is a very clever wrapper around the need to run +Ghostscript with a different syntax, options, device selections, and/or filters for each different printer +or spooler. At the same time it can read the PPD associated +with a print queue and modify the print job according to the user +selections. Together with this comes the 100% compliance of the new +Foomatic PPDs with the Adobe spec. Some innovative features of +the Foomatic concept may surprise users. It will support custom paper +sizes for many printers and will support printing on media drawn +from different paper trays within the same job (in both cases, even +where there is no support for this from Windows-based vendor printer +drivers). +</para> +</sect3> + +<sect3> +<title>Driver Development Outside</title> + +<para> +Most driver development itself does not happen within +Linuxprinting.org. Drivers are written by independent maintainers. +Linuxprinting.org just pools all the information and stores it in its +database. In addition, it also provides the Foomatic glue to integrate +the many drivers into any modern (or legacy) printing system known to +the world. +</para> + +<para> +Speaking of the different driver development groups, most of +the work is currently done in three projects. These are: +</para> + +<itemizedlist> +<listitem><para><ulink +url="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/">Omni</ulink> +&smbmdash; a free software project by IBM that tries to convert their printer +driver knowledge from good-ol' OS/2 times into a modern, modular, +universal driver architecture for Linux/UNIX (still beta). This +currently supports 437 models.</para></listitem> + +<listitem><para><ulink url="http://hpinkjet.sf.net/">HPIJS</ulink> &smbmdash; +a free software project by HP to provide the support for their own +range of models (very mature, printing in most cases is perfect and +provides true photo quality). This currently supports 369 +models.</para></listitem> + +<listitem><para><ulink +url="http://gimp-print.sf.net/">Gimp-Print</ulink> &smbmdash; a free software +effort, started by Michael Sweet (also lead developer for CUPS), now +directed by Robert Krawitz, which has achieved an amazing level of +photo print quality (many Epson users swear that its quality is +better than the vendor drivers provided by Epson for the Microsoft +platforms). This currently supports 522 models.</para></listitem> +</itemizedlist> +</sect3> + +<sect3> +<title>Forums, Downloads, Tutorials, Howtos &smbmdash; also for Mac OS X and Commercial UNIX</title> + +<para> +Linuxprinting.org today is the one-stop shop to download printer +drivers. Look for printer information and <ulink +url="http://www.linuxprinting.org//kpfeifle/LinuxKongress2002/Tutorial/">tutorials</ulink> +or solve printing problems in its popular <ulink +url="http://www.linuxprinting.org/newsportal/">forums.</ulink> This forum +it's not just for GNU/Linux users, but admins of <ulink +url="http://www.linuxprinting.org/macosx/">commercial UNIX +systems</ulink> are also going there, and the relatively new <ulink +url="http://www.linuxprinting.org/newsportal/thread.php3?name=linuxprinting.macosx.general">Mac +OS X forum</ulink> has turned out to be one of the most frequented +forums after only a few weeks. +</para> + +<para> +Linuxprinting.org and the Foomatic driver wrappers around Ghostscript +are now a standard tool-chain for printing on all the important +distros. Most of them also have CUPS underneath. While in recent years +most printer data had been added by Kamppeter (who works at Mandrake), many +additional contributions came from engineers with SuSE, Red Hat, +Conectiva, Debian, and others. Vendor-neutrality is an important goal +of the Foomatic project. +</para> + +<note><para> +Till Kamppeter from MandrakeSoft is doing an excellent job in his +spare time to maintain Linuxprinting.org and Foomatic. So if you use +it often, please send him a note showing your appreciation. +</para></note> +</sect3> + +<sect3> +<title>Foomatic Database-Generated PPDs</title> + +<para> +The Foomatic database is an amazing piece of ingenuity in itself. Not +only does it keep the printer and driver information, but it is +organized in a way that it can generate PPD files on the fly from +its internal XML-based datasets. While these PPDs are modeled to the +Adobe specification of PostScript Printer Descriptions (PPDs), the +Linuxprinting.org/Foomatic-PPDs do not normally drive PostScript +printers. They are used to describe all the bells and whistles you +could ring or blow on an Epson Stylus inkjet, or a HP Photosmart, or +what-have-you. The main trick is one little additional line, not +envisaged by the PPD specification, starting with the <parameter>*cupsFilter</parameter> +keyword. It tells the CUPS daemon how to proceed with the PostScript +print file (old-style Foomatic-PPDs named the +cupsomatic filter script, while the new-style +PPDs are now call foomatic-rip). This filter +script calls Ghostscript on the host system (the recommended variant +is ESP Ghostscript) to do the rendering work. foomatic-rip knows which +filter or internal device setting it should ask from Ghostscript to +convert the PostScript print job into a raster format ready for the +target device. This usage of PPDs to describe the options of non-PS +printers was the invention of the CUPS developers. The rest is easy. +GUI tools (like KDE's marvelous <ulink +url="http://printing.kde.org/overview/kprinter.phtml">kprinter,</ulink> +or the GNOME <ulink +url="http://gtklp.sourceforge.net/">gtklp,</ulink> xpp and the CUPS +Web interface) read the PPD as well and use this information to present +the available settings to the user as an intuitive menu selection. +</para> +</sect3> +</sect2> + +<sect2> +<title>foomatic-rip and Foomatic-PPD Download and Installation</title> + +<para> +Here are the steps to install a foomatic-rip driven LaserJet 4 Plus-compatible +printer in CUPS (note that recent distributions of SuSE, UnitedLinux and +Mandrake may ship with a complete package of Foomatic-PPDs plus the +<command>foomatic-rip</command> utility. Going directly to +Linuxprinting.org ensures that you get the latest driver/PPD files): +</para> + +<itemizedlist> +<listitem><para>Open your browser at the Linuxprinting.org printer list<ulink url="http://www.linuxprinting.org/printer_list.cgi">page.</ulink> +</para></listitem> + +<listitem><para>Check the complete list of printers in the +<ulink url="http://www.linuxprinting.org/printer_list.cgi?make=Anyone">database.</ulink>. +</para></listitem> + +<listitem><para>Select your model and click on the link. +</para></listitem> + +<listitem><para>You'll arrive at a page listing all drivers working with this +model (for all printers, there will always be <emphasis>one</emphasis> +recommended driver. Try this one first). +</para></listitem> + +<listitem><para>In our case (HP LaserJet 4 Plus), we'll arrive at the default driver for the +<ulink url="http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_4_Plus">HP-LaserJet 4 Plus.</ulink> +</para></listitem> + +<listitem><para>The recommended driver is ljet4.</para></listitem> + +<listitem><para>Several links are provided here. You should visit them all if you +are not familiar with the Linuxprinting.org database. +</para></listitem> + +<listitem><para>There is a link to the database page for the +<ulink url="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4">ljet4.</ulink> +On the driver's page, you'll find important and detailed information +about how to use that driver within the various available +spoolers.</para></listitem> + +<listitem><para>Another link may lead you to the home-page of the +driver author or the driver.</para></listitem> + +<listitem><para>Important links are the ones that provide hints with +setup instructions for <ulink noescape="1" url="http://www.linuxprinting.org/cups-doc.html">CUPS</ulink>, +<ulink url="http://www.linuxprinting.org/pdq-doc.html">PDQ</ulink>, +<ulink url="http://www.linuxprinting.org/lpd-doc.html">LPD, LPRng and GNUlpr</ulink>) +as well as <ulink url="http://www.linuxprinting.org/ppr-doc.html">PPR</ulink> +or <quote>spooler-less</quote> <ulink url="http://www.linuxprinting.org/direct-doc.html">printing.</ulink> +</para></listitem> + +<listitem><para>You can view the PPD in your browser through this link: +<ulink noescape="1" url="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=1">http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=1</ulink> +</para></listitem> <listitem><para>Most importantly, you can also generate and download +the <ulink url="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=0">PPD.</ulink> +</para></listitem> + +<listitem><para>The PPD contains all the information needed to use our +model and the driver; once installed, this works transparently +for the user. Later you'll only need to choose resolution, paper size, +and so on from the Web-based menu, or from the print dialog GUI, or from +the command line.</para></listitem> + +<listitem><para>If you ended up on the drivers +<ulink url="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4">page</ulink> +you can choose to use the <quote>PPD-O-Matic</quote> online PPD generator +program.</para></listitem> + +<listitem><para>Select the exact model and check either <guilabel>Download</guilabel> or +<guilabel>Display PPD file</guilabel> and click <guilabel>Generate PPD file</guilabel>.</para></listitem> + +<listitem><para>If you save the PPD file from the browser view, please +do not use cut and paste (since it could possibly damage line endings +and tabs, which makes the PPD likely to fail its duty), but use <guimenuitem>Save +as...</guimenuitem> in your browsers menu. (It is best to use the <guilabel>Download</guilabel> option +directly from the Web page).</para></listitem> + +<listitem><para>Another interesting part on each driver page is +the <guimenuitem>Show execution details</guimenuitem> button. If you +select your printer model and click on that button, +a complete Ghostscript command line will be displayed, enumerating all options +available for that combination of driver and printer model. This is a great way to +<quote>learn Ghostscript by doing</quote>. It is also an excellent cheat sheet +for all experienced users who need to re-construct a good command line +for that damn printing script, but can't remember the exact +syntax. </para></listitem> + +<listitem><para>Some time during your visit to Linuxprinting.org, save +the PPD to a suitable place on your hard-disk, say +<filename>/path/to/my-printer.ppd</filename> (if you prefer to install +your printers with the help of the CUPS Web interface, save the PPD to +the <filename>/usr/share/cups/model/</filename> path and restart +cupsd).</para></listitem> + +<listitem><para>Then install the printer with a suitable command line, +like this: +</para> + +<para><screen> +&rootprompt;<userinput>lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E \ + -P path/to/my-printer.ppd</userinput> +</screen></para></listitem> + +<listitem><para>For all the new-style <quote>Foomatic-PPDs</quote> +from Linuxprinting.org, you also need a special CUPS filter named +foomatic-rip. +</para></listitem> + +<listitem><para>The foomatic-rip Perl script itself also makes some +interesting <ulink url="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&show=1">reading</ulink> +because it is well documented by Kamppeter's in-line comments (even +non-Perl hackers will learn quite a bit about printing by reading +it).</para></listitem> + +<listitem><para>Save foomatic-rip either directly in +<filename>/usr/lib/cups/filter/foomatic-rip</filename> or somewhere in +your $PATH (and remember to make it world-executable). Again, +do not save by copy and paste but use the appropriate link or the +<guimenuitem>Save as...</guimenuitem> menu item in your browser.</para></listitem> + +<listitem><para>If you save foomatic-rip in your $PATH, create a symlink: +<screen> +&rootprompt;<userinput>cd /usr/lib/cups/filter/ ; ln -s `which foomatic-rip'</userinput> +</screen> +</para> + +<para> +CUPS will discover this new available filter at startup after restarting +cupsd.</para></listitem> +</itemizedlist> + +<para> +Once you print to a print queue set up with the Foomatic-PPD, CUPS will +insert the appropriate commands and comments into the resulting +PostScript jobfile. foomatic-rip is able to read and act upon +these and uses some specially encoded Foomatic comments +embedded in the jobfile. These in turn are used to construct +(transparently for you, the user) the complicated Ghostscript command +line telling the printer driver exactly how the resulting raster +data should look and which printer commands to embed into the +data stream. You need: +</para> + +<itemizedlist> + +<listitem><para>A <quote>foomatic+something</quote> PPD &smbmdash; but this is not enough +to print with CUPS (it is only <emphasis>one</emphasis> important +component).</para></listitem> + +<listitem><para>The <parameter>foomatic-rip</parameter> filter script (Perl) in +<filename>/usr/lib/cups/filters/</filename>.</para></listitem> + +<listitem><para>Perl to make foomatic-rip run.</para></listitem> + +<listitem><para>Ghostscript (because it is doing the main work, +controlled by the PPD/foomatic-rip combo) to produce the raster data +fit for your printer model's consumption.</para></listitem> + +<listitem><para>Ghostscript <emphasis>must</emphasis> (depending on +the driver/model) contain support for a certain device representing +the selected driver for your model (as shown by <command>gs + -h</command>).</para></listitem> + +<listitem><para>foomatic-rip needs a new version of PPDs (PPD versions +produced for cupsomatic do not work with +foomatic-rip).</para></listitem> +</itemizedlist> +</sect2> +</sect1> + +<sect1> +<title>Page Accounting with CUPS</title> + + +<para> +<indexterm><primary>CUPS</primary><secondary>Page Accounting</secondary></indexterm> +Often there are questions regarding print quotas where Samba users +(that is, Windows clients) should not be able to print beyond a +certain number of pages or data volume per day, week or month. This +feature is dependent on the real print subsystem you're using. +Samba's part is always to receive the job files from the clients +(filtered <emphasis>or</emphasis> unfiltered) and hand it over to this +printing subsystem. +</para> + +<para> +Of course one could hack things with one's own scripts. But then +there is CUPS. CUPS supports quotas that can be based on the size of +jobs or on the number of pages or both, and span any time +period you want. +</para> + +<sect2> +<title>Setting Up Quotas</title> + +<para> +<indexterm><primary>CUPS</primary><secondary>quotas</secondary></indexterm> +This is an example command of how root would set a print quota in CUPS, +assuming an existing printer named <quote>quotaprinter</quote>: +</para> + + +<para> +<indexterm><primary>lpadmin</primary></indexterm> + <screen> +&rootprompt;<userinput>lpadmin -p quotaprinter -o job-quota-period=604800 \ + -o job-k-limit=1024 -o job-page-limit=100</userinput> +</screen></para> + +<para> +This would limit every single user to print 100 pages or 1024 KB of +data (whichever comes first) within the last 604,800 seconds ( = 1 +week). +</para> +</sect2> + +<sect2> +<title>Correct and Incorrect Accounting</title> + +<para> +For CUPS to count correctly, the printfile needs to pass the CUPS +pstops filter, otherwise it uses a dummy count of <quote>one</quote>. Some +print files do not pass it (e.g., image files) but then those are mostly one- +page jobs anyway. This also means that proprietary drivers for the +target printer running on the client computers and CUPS/Samba, which +then spool these files as <quote>raw</quote> (i.e., leaving them untouched, not +filtering them), will be counted as one-pagers too! +</para> + +<para> +You need to send PostScript from the clients (i.e., run a PostScript +driver there) to have the chance to get accounting done. If the +printer is a non-PostScript model, you need to let CUPS do the job to +convert the file to a print-ready format for the target printer. This +is currently working for about a thousand different printer models. +Linuxprinting has a driver +<ulink url="http://www.linuxprinting.org/printer_list.cgi">list.</ulink> +</para> +</sect2> + +<sect2> +<title>Adobe and CUPS PostScript Drivers for Windows Clients</title> + +<para> +Before CUPS 1.1.16, your only option was to use the Adobe PostScript +Driver on the Windows clients. The output of this driver was not +always passed through the <command>pstops</command> filter on the CUPS/Samba side, and +therefore was not counted correctly (the reason is that it often, +depending on the PPD being used, wrote a PJL-header in front of +the real PostScript which caused CUPS to skip <command>pstops</command> and go directly +to the <command>pstoraster</command> stage). +</para> + +<para> +From CUPS 1.1.16 onward, you can use the CUPS PostScript Driver for +Windows <?latex \linebreak ?>NT/200x/XP clients (which is tagged in the download area of +<filename>http://www.cups.org/</filename> as the <filename>cups-samba-1.1.16.tar.gz</filename> +package). It does <emphasis>not</emphasis> work for Windows 9x/ME clients, but it guarantees: +</para> + +<itemizedlist> + +<listitem><para> <indexterm><primary>PJL</primary></indexterm> To not write a PJL-header.</para></listitem> + +<listitem><para>To still read and support all PJL-options named in the +driver PPD with its own means.</para></listitem> + +<listitem><para>That the file will pass through the <command>pstops</command> filter +on the CUPS/Samba server.</para></listitem> + +<listitem><para>To page-count correctly the print file.</para></listitem> +</itemizedlist> + +<para> +You can read more about the setup of this combination in the man page +for <command>cupsaddsmb</command> (which is only present with CUPS installed, and only +current from CUPS 1.1.16). +</para> +</sect2> + +<sect2> +<title>The page_log File Syntax</title> + +<para> +<indexterm><primary>page_log</primary></indexterm> +These are the items CUPS logs in the <filename>page_log</filename> for every +page of a job: +</para> + +<itemizedlist> +<listitem><para>Printer name</para></listitem> + +<listitem><para>User name</para></listitem> + +<listitem><para>Job ID</para></listitem> + +<listitem><para>Time of printing</para></listitem> + +<listitem><para>The page number</para></listitem> + +<listitem><para>The number of copies</para></listitem> + +<listitem><para>A billing information string (optional)</para></listitem> + +<listitem><para>The host that sent the job (included since version 1.1.19)</para></listitem> +</itemizedlist> + +<para> +Here is an extract of my CUPS server's <filename>page_log</filename> file to illustrate the +format and included items: +</para> + +<para><screen> +tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 1 3 #marketing 10.160.50.13 +tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 2 3 #marketing 10.160.50.13 +tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 3 3 #marketing 10.160.50.13 +tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 4 3 #marketing 10.160.50.13 +Dig9110 boss 402 [22/Apr/2003:10:33:22 +0100] 1 440 finance-dep 10.160.51.33 +</screen></para> + +<para> +This was job ID <parameter>401</parameter>, printed on <parameter>tec_IS2027</parameter> +by user <parameter>kurt</parameter>, a 64-page job printed in three copies and billed to +<parameter>#marketing</parameter>, sent from IP address <constant>10.160.50.13.</constant> + The next job had ID <parameter>402</parameter>, was sent by user <parameter>boss</parameter> +from IP address <constant>10.160.51.33</constant>, printed from one page 440 copies and +is set to be billed to <parameter>finance-dep</parameter>. +</para> +</sect2> + +<sect2> +<title>Possible Shortcomings</title> + +<para> +What flaws or shortcomings are there with this quota system? +</para> + +<itemizedlist> +<listitem><para>The ones named above (wrongly logged job in case of +printer hardware failure, and so on).</para></listitem> + +<listitem><para>In reality, CUPS counts the job pages that are being +processed in <emphasis>software</emphasis> (that is, going through the +RIP) rather than the physical sheets successfully leaving the +printing device. Thus if there is a jam while printing the fifth sheet out +of a thousand and the job is aborted by the printer, the page count will +still show the figure of a thousand for that job.</para></listitem> + +<listitem><para>All quotas are the same for all users (no flexibility +to give the boss a higher quota than the clerk) and no support for +groups.</para></listitem> + +<listitem><para>No means to read out the current balance or the +<quote>used-up</quote> number of current quota.</para></listitem> + +<listitem><para>A user having used up 99 sheets of a 100 quota will +still be able to send and print a thousand sheet job.</para></listitem> + +<listitem><para>A user being denied a job because of a filled-up quota +does not get a meaningful error message from CUPS other than +<quote>client-error-not-possible</quote>.</para></listitem> +</itemizedlist> +</sect2> + +<sect2> +<title>Future Developments</title> + +<para> +This is the best system currently available, and there are huge +improvements under development for CUPS 1.2: +</para> + +<itemizedlist> +<listitem><para>Page counting will go into the backends (these talk +directly to the printer and will increase the count in sync with the +actual printing process; thus, a jam at the fifth sheet will lead to a +stop in the counting).</para></listitem> + +<listitem><para>Quotas will be handled more flexibly.</para></listitem> + +<listitem><para>Probably there will be support for users to inquire +about their accounts in advance.</para></listitem> + +<listitem><para>Probably there will be support for some other tools +around this topic.</para></listitem> +</itemizedlist> +</sect2> + +<!-- FIXME +<sect2> +<title>Other Accounting Tools</title> + +<para> +PrintAnalyzer, pyKota, printbill, LogReport. +</para> +</sect2> +--> +</sect1> + +<sect1> +<title>Additional Material</title> + +<para> +A printer queue with <emphasis>no</emphasis> PPD associated to it is a +<quote>raw</quote> printer and all files will go directly there as received by the +spooler. The exceptions are file types <parameter>application/octet-stream</parameter> +that need pass-through feature enabled. <quote>Raw</quote> queues do not do any +filtering at all, they hand the file directly to the CUPS backend. +This backend is responsible for sending the data to the device +(as in the <quote>device URI</quote> notation: <filename>lpd://, socket://, +smb://, ipp://, http://, parallel:/, serial:/, usb:/</filename>, and so on). +</para> + +<para> +cupsomatic/Foomatic are <emphasis>not</emphasis> native CUPS drivers +and they do not ship with CUPS. They are a third party add-on +developed at Linuxprinting.org. As such, they are a brilliant hack to +make all models (driven by Ghostscript drivers/filters in traditional +spoolers) also work via CUPS, with the same (good or bad!) quality as +in these other spoolers. <parameter>cupsomatic</parameter> is only a vehicle to execute a +Ghostscript command-line at that stage in the CUPS filtering chain, +where normally the native CUPS <parameter>pstoraster</parameter> filter would kick +in. cupsomatic bypasses pstoraster, kidnaps the printfile from CUPS +away and redirects it to go through Ghostscript. CUPS accepts this, +because the associated cupsomatic/foomatic-PPD specifies: + +<programlisting> + *cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" +</programlisting> + +This line persuades CUPS to hand the file to cupsomatic, once it has +successfully converted it to the MIME type +<parameter>application/vnd.cups-postscript</parameter>. This conversion will not happen for +Jobs arriving from Windows that are auto-typed +<parameter>application/octet-stream</parameter>, with the according changes in +<filename>/etc/cups/mime.types</filename> in place. +</para> + +<para> +CUPS is widely configurable and flexible, even regarding its filtering +mechanism. Another workaround in some situations would be to have in +<filename>/etc/cups/mime.types</filename> entries as follows: + +<programlisting> + application/postscript application/vnd.cups-raw 0 - + application/vnd.cups-postscript application/vnd.cups-raw 0 - +</programlisting> + +This would prevent all PostScript files from being filtered (rather, +they will through the virtual <emphasis>nullfilter</emphasis> +denoted with <quote>-</quote>). This could only be useful for PS printers. If you +want to print PS code on non-PS printers (provided they support ASCII +text printing), an entry as follows could be useful: + +<programlisting> + */* application/vnd.cups-raw 0 - +</programlisting> + +and would effectively send <emphasis>all</emphasis> files to the +backend without further processing. +</para> + +<para> +You could have the following entry: + +<programlisting> +application/vnd.cups-postscript application/vnd.cups-raw 0 \ + my_PJL_stripping_filter +</programlisting> + +You will need to write a <parameter>my_PJL_stripping_filter</parameter> +(which could be a shell script) that parses the PostScript and removes the +unwanted PJL. This needs to conform to CUPS filter design +(mainly, receive and pass the parameters printername, job-id, +username, jobtitle, copies, print options and possibly the +filename). It is installed as world executable into +<filename>/usr/lib/cups/filters/</filename> and is called by CUPS +if it encounters a MIME type <parameter>application/vnd.cups-postscript</parameter>. +</para> + +<para> +CUPS can handle <parameter>-o job-hold-until=indefinite</parameter>. +This keeps the job in the queue on hold. It will only be printed +upon manual release by the printer operator. This is a requirement in +many central reproduction departments, where a few operators manage +the jobs of hundreds of users on some big machine, where no user is +allowed to have direct access (such as when the operators often need +to load the proper paper type before running the 10,000 page job +requested by marketing for the mailing, and so on). +</para> +</sect1> + +<sect1> +<title>Auto-Deletion or Preservation of CUPS Spool Files</title> + +<para> +Samba print files pass through two spool directories. One is the +incoming directory managed by Samba, (set in the +<smbconfoption name="path">/var/spool/samba</smbconfoption> +directive in the <smbconfsection name="[printers]"/> section of +&smb.conf;). The other is the spool directory of +your UNIX print subsystem. For CUPS it is normally +<filename>/var/spool/cups/</filename>, as set by the <filename>cupsd.conf</filename> +directive <filename>RequestRoot /var/spool/cups</filename>. +</para> + +<sect2> +<title>CUPS Configuration Settings Explained</title> + +<para> +Some important parameter settings in the CUPS configuration file +<filename>cupsd.conf</filename> are: +</para> + +<variablelist> + +<varlistentry><term>PreserveJobHistory Yes</term> +<listitem><para> +This keeps some details of jobs in cupsd's mind (well it keeps the +c12345, c12346, and so on, files in the CUPS spool directory, which do a +similar job as the old-fashioned BSD-LPD control files). This is set +to <quote>Yes</quote> as a default. +</para></listitem></varlistentry> + +<varlistentry><term>PreserveJobFiles Yes</term> +<listitem><para> +This keeps the job files themselves in cupsd's mind +(it keeps the d12345, d12346 etc. files in the CUPS spool +directory). This is set to <quote>No</quote> as the CUPS +default. +</para></listitem></varlistentry> + +<varlistentry><term><emphasis><quote>MaxJobs 500</quote></emphasis></term> +<listitem><para> +This directive controls the maximum number of jobs +that are kept in memory. Once the number of jobs reaches the limit, +the oldest completed job is automatically purged from the system to +make room for the new one. If all of the known jobs are still +pending or active, then the new job will be rejected. Setting the +maximum to 0 disables this functionality. The default setting is +0. +</para></listitem></varlistentry> +</variablelist> + +<para> +(There are also additional settings for <parameter>MaxJobsPerUser</parameter> and +<parameter>MaxJobsPerPrinter</parameter>...) +</para> +</sect2> + +<sect2> +<title>Pre-Conditions</title> + +<para> +For everything to work as announced, you need to have three +things: +</para> + +<itemizedlist> +<listitem><para>A Samba-smbd that is compiled against <filename>libcups</filename> (check +on Linux by running <userinput>ldd `which smbd'</userinput>).</para></listitem> + +<listitem><para>A Samba-&smb.conf; setting of + <smbconfoption name="printing">cups</smbconfoption>.</para></listitem> + +<listitem><para>Another Samba-&smb.conf; setting of + <smbconfoption name="printcap">cups</smbconfoption>.</para></listitem> +</itemizedlist> + +<note><para> +In this case, all other manually set printing-related commands (like +<smbconfoption name="print command"/>, +<smbconfoption name="lpq command"/>, +<smbconfoption name="lprm command"/>, +<smbconfoption name="lppause command"/> or +<smbconfoption name="lpresume command"/>) are ignored and they should normally have no +influence whatsoever on your printing. +</para></note> +</sect2> + +<sect2> +<title>Manual Configuration</title> + +<para> +If you want to do things manually, replace the <smbconfoption name="printing">cups</smbconfoption> +by <smbconfoption name="printing">bsd</smbconfoption>. Then your manually set commands may work +(I haven't tested this), and a <smbconfoption name="print command">lp -d %P %s; rm %s"</smbconfoption> +may do what you need. +</para> +</sect2> +</sect1> + +<sect1> +<title>Printing from CUPS to Windows Attached Printers</title> + +<para> +>From time to time the question arises, how can you print +<emphasis>to</emphasis> a Windows attached printer +<emphasis>from</emphasis> Samba? Normally the local connection +from Windows host to printer would be done by USB or parallel +cable, but this does not matter to Samba. From here only an SMB +connection needs to be opened to the Windows host. Of course, this +printer must be shared first. As you have learned by now, CUPS uses +<emphasis>backends</emphasis> to talk to printers and other +servers. To talk to Windows shared printers, you need to use the +<filename>smb</filename> (surprise, surprise!) backend. Check if this +is in the CUPS backend directory. This usually resides in +<filename>/usr/lib/cups/backend/</filename>. You need to find an <filename>smb</filename> +file there. It should be a symlink to <filename>smbspool</filename> +and the file must exist and be executable: +</para> + +<para><screen> +&rootprompt;<userinput>ls -l /usr/lib/cups/backend/</userinput> +total 253 +drwxr-xr-x 3 root root 720 Apr 30 19:04 . +drwxr-xr-x 6 root root 125 Dec 19 17:13 .. +-rwxr-xr-x 1 root root 10692 Feb 16 21:29 canon +-rwxr-xr-x 1 root root 10692 Feb 16 21:29 epson +lrwxrwxrwx 1 root root 3 Apr 17 22:50 http -> ipp +-rwxr-xr-x 1 root root 17316 Apr 17 22:50 ipp +-rwxr-xr-x 1 root root 15420 Apr 20 17:01 lpd +-rwxr-xr-x 1 root root 8656 Apr 20 17:01 parallel +-rwxr-xr-x 1 root root 2162 Mar 31 23:15 pdfdistiller +lrwxrwxrwx 1 root root 25 Apr 30 19:04 ptal -> /usr/sbin/ptal-cups +-rwxr-xr-x 1 root root 6284 Apr 20 17:01 scsi +lrwxrwxrwx 1 root root 17 Apr 2 03:11 smb -> /usr/bin/smbspool +-rwxr-xr-x 1 root root 7912 Apr 20 17:01 socket +-rwxr-xr-x 1 root root 9012 Apr 20 17:01 usb + +&rootprompt;<userinput>ls -l `which smbspool`</userinput> +-rwxr-xr-x 1 root root 563245 Dec 28 14:49 /usr/bin/smbspool +</screen></para> + +<para> +If this symlink does not exist, create it: +</para> + +<para><screen> +&rootprompt;<userinput>ln -s `which smbspool` /usr/lib/cups/backend/smb</userinput> +</screen></para> + +<para> +<command>smbspool</command> has been written by Mike Sweet from the CUPS folks. It is +included and ships with Samba. It may also be used with print +subsystems other than CUPS, to spool jobs to Windows printer shares. To +set up printer <replaceable>winprinter</replaceable> on CUPS, you need to have a driver for +it. Essentially this means to convert the print data on the CUPS/Samba +host to a format that the printer can digest (the Windows host is +unable to convert any files you may send). This also means you should +be able to print to the printer if it were hooked directly at your +Samba/CUPS host. For troubleshooting purposes, this is what you +should do to determine if that part of the process chain is in +order. Then proceed to fix the network connection/authentication to +the Windows host, and so on. +</para> + +<para> +To install a printer with the <parameter>smb</parameter> backend on CUPS, use this command: +</para> + +<para><screen> +&rootprompt;<userinput>lpadmin -p winprinter -v smb://WINDOWSNETBIOSNAME/printersharename \ + -P /path/to/PPD</userinput> +</screen></para> + +<para> +The PPD must be able to direct CUPS to generate +the print data for the target model. For PostScript printers, just use +the PPD that would be used with the Windows NT PostScript driver. But +what can you do if the printer is only accessible with a password? Or +if the printer's host is part of another workgroup? This is provided +for: You can include the required parameters as part of the +<filename>smb://</filename> device-URI like this: +</para> + +<itemizedlist> + <listitem><para><filename>smb://WORKGROUP/WINDOWSNETBIOSNAME/printersharename</filename></para></listitem> + <listitem><para><filename>smb://username:password@WORKGROUP/WINDOWSNETBIOSNAME/printersharename</filename></para></listitem> + <listitem><para><filename>smb://username:password@WINDOWSNETBIOSNAME/printersharename</filename></para></listitem> +</itemizedlist> + +<para> +Note that the device-URI will be visible in the process list of the +Samba server (e.g., when someone uses the <command>ps -aux</command> +command on Linux), even if the username and passwords are sanitized +before they get written into the log files. So this is an inherently +insecure option, however, it is the only one. Don't use it if you want +to protect your passwords. Better share the printer in a way that +does not require a password! Printing will only work if you have a +working netbios name resolution up and running. Note that this is a +feature of CUPS and you do not necessarily need to have smbd running. + +</para> +</sect1> + +<sect1> +<title>More CUPS-Filtering Chains</title> + +<para> +The following diagrams reveal how CUPS handles print jobs. +</para> + +<image id="cups1"> + <imagedescription>Filtering chain 1.</imagedescription> + <imagefile>cups1</imagefile> +</image> + +<image id="cups2"> + <imagedescription>Filtering chain with cupsomatic</imagedescription> + <imagefile>cups2</imagefile> +</image> + +</sect1> + +<sect1> + <title>Common Errors</title> + + <sect2> + <title>Windows 9x/ME Client Can't Install Driver</title> + + <para>For Windows 9x/ME, clients require the printer names to be eight +characters (or <quote>8 plus 3 chars suffix</quote>) max; otherwise, the driver files +will not get transferred when you want to download them from +Samba.</para> + + </sect2> + + <sect2 id="root-ask-loop"> + <title><quote>cupsaddsmb</quote> Keeps Asking for Root Password in Never-ending Loop</title> + + <para>Have you <smbconfoption name="security">user</smbconfoption>? Have + you used <command>smbpasswd</command> to give root a Samba account? + You can do two things: open another terminal and execute + <command>smbpasswd -a root</command> to create the account and + continue entering the password into the first terminal. Or break + out of the loop by pressing ENTER twice (without trying to type a + password).</para> + + <para> + If the error is: <quote>tree connect failed: NT_STATUS_BAD_NETWORK_NAME</quote>, + you may have forgotten to create the <filename>/etc/samba/drivers</filename> directory. + </para> + </sect2> + + <sect2> + <title><quote>cupsaddsmb</quote> or <quote>rpcclient addriver</quote> Keeps Giving WERR_BAD_PASSWORD</title> + + <para>See <link linkend="root-ask-loop">the previous common error</link>.</para> + </sect2> + + <sect2> + <title><quote>cupsaddsmb</quote> Errors</title> + + <para> + The use of <quote>cupsaddsmb</quote> gives <quote>No PPD file for printer...</quote> + Message While PPD File Is Present. What might the problem be? + </para> + + <para>Have you enabled printer sharing on CUPS? This means: + Do you have a <parameter><Location + /printers>....</Location></parameter> section in CUPS + server's <filename>cupsd.conf</filename> that does not deny access to + the host you run <quote>cupsaddsmb</quote> from? It <emphasis>could</emphasis> be + an issue if you use cupsaddsmb remotely, or if you use it with a + <option>-h</option> parameter: <userinput>cupsaddsmb -H + sambaserver -h cupsserver -v printername</userinput>. + </para> + + <para>Is your <parameter>TempDir</parameter> directive in + <filename>cupsd.conf</filename> set to a valid value and is it writable? + </para> + + </sect2> + + <sect2> + <title>Client Can't Connect to Samba Printer</title> + + <para>Use <command>smbstatus</command> to check which user + you are from Samba's point of view. Do you have the privileges to + write into the <smbconfsection name="[print$]"/> + share?</para> + + </sect2> + + <sect2> + <title>New Account Reconnection from Windows 200x/XP Troubles</title> + +<para>Once you are connected as the wrong user (for +example, as <constant>nobody</constant>, which often occurs if you have +<smbconfoption name="map to guest">bad user</smbconfoption>), Windows Explorer will not accept an +attempt to connect again as a different user. There will not be any byte +transfered on the wire to Samba, but still you'll see a stupid error +message that makes you think Samba has denied access. Use +<command>smbstatus</command> to check for active connections. Kill the +PIDs. You still can't re-connect and you get the dreaded +<computeroutput>You can't connect with a second account from the same +machine</computeroutput> message, as soon as you are trying. And you +do not see any single byte arriving at Samba (see logs; use <quote>ethereal</quote>) +indicating a renewed connection attempt. Shut all Explorer Windows. +This makes Windows forget what it has cached in its memory as +established connections. Then reconnect as the right user. The best +method is to use a DOS terminal window and <emphasis>first</emphasis> +do <userinput>net use z: \\&example.server.samba;\print$ /user:root</userinput>. Check +with <command>smbstatus</command> that you are connected under a +different account. Now open the <guilabel>Printers</guilabel> folder (on the Samba server +in the <guilabel>Network Neighborhood</guilabel>), right-click on the +printer in question and select +<guibutton>Connect...</guibutton></para></sect2> + +<sect2> +<title>Avoid Being Connected to the Samba Server as the Wrong User</title> + +<para>You see per <command>smbstatus</command> that you are +connected as user nobody; while you want to be root or +printer admin. This is probably due to +<smbconfoption name="map to guest">bad user</smbconfoption>, which silently connects you under the guest account +when you gave (maybe by accident) an incorrect username. Remove +<smbconfoption name="map to guest"/>, if you want to prevent +this.</para></sect2> + +<sect2> +<title>Upgrading to CUPS Drivers from Adobe Drivers</title> + +<para> +This information came from a mailing list posting regarding problems experienced when +upgrading from Adobe drivers to CUPS drivers on Microsoft Windows NT/200x/XP Clients. +</para> + +<para>First delete all old Adobe-using printers. Then +delete all old Adobe drivers. (On Windows 200x/XP, right-click in +the background of <guilabel>Printers</guilabel> folder, select <guimenuitem>Server Properties...</guimenuitem>, select +tab <guilabel>Drivers</guilabel> and delete here).</para></sect2> + +<sect2><title>Can't Use <quote>cupsaddsmb</quote> on Samba Server Which Is a PDC</title> +<para>Do you use the <quote>naked</quote> root user name? Try to do it +this way: <userinput>cupsaddsmb -U <replaceable>DOMAINNAME</replaceable>\\root -v +<replaceable>printername</replaceable></userinput>> (note the two backslashes: the first one is +required to <quote>escape</quote> the second one).</para></sect2> + +<sect2><title>Deleted Windows 200x Printer Driver Is Still Shown</title> +<para>Deleting a printer on the client will not delete the +driver too (to verify, right-click on the white background of the +<guilabel>Printers</guilabel> folder, select <guimenuitem>Server Properties</guimenuitem> and click on the +<guilabel>Drivers</guilabel> tab). These same old drivers will be re-used when you try to +install a printer with the same name. If you want to update to a new +driver, delete the old ones first. Deletion is only possible if no +other printer uses the same driver.</para></sect2> + +<sect2><title>Windows 200x/XP "Local Security Policies"</title> +<para>Local Security Policies may not +allow the installation of unsigned drivers. <quote>Local Security Policies</quote> +may not allow the installation of printer drivers at +all.</para></sect2> + +<sect2><title>Administrator Cannot Install Printers for All Local Users</title> +<para>Windows XP handles SMB printers on a <quote>per-user</quote> basis. +This means every user needs to install the printer himself. To have a +printer available for everybody, you might want to use the built-in +IPP client capabilities of Win XP. Add a printer with the print path of +<parameter>http://cupsserver:631/printers/printername</parameter>. +We're still looking into this one. Maybe a logon script could +automatically install printers for all +users.</para></sect2> + +<sect2><title>Print Change Notify Functions on NT-clients</title> +<para>For print change, notify functions on NT++ clients. +These need to run the <command>Server</command> service first (renamed to +<command>File & Print Sharing for MS Networks</command> in +XP).</para></sect2> + +<sect2> +<title>Win XP-SP1</title> + +<para>Win XP-SP1 introduced a Point and Print Restriction Policy (this restriction does not apply to +<quote>Administrator</quote> or <quote>Power User</quote> groups of users). In Group Policy +Object Editor, go to <guimenu>User Configuration -> Administrative Templates -> + Control Panel -> Printers</guimenu>. The policy is automatically set to +<constant>Enabled</constant> and the <constant>Users can only Point +and Print to machines in their Forest</constant> . You probably need +to change it to <constant>Disabled</constant> or <constant>Users can +only Point and Print to these servers</constant> to make +driver downloads from Samba possible. +</para> +</sect2> + +<sect2> +<title>Print Options for All Users Can't Be Set on Windows 200x/XP</title> + +<para>How are you doing it? I bet the wrong way (it is not +easy to find out, though). There are three different ways to bring +you to a dialog that <emphasis>seems</emphasis> to set everything. All +three dialogs <emphasis>look</emphasis> the same, yet only one of them +does what you intend. You need to be +Administrator or Print Administrator to do this for all users. Here +is how I do in on XP: +</para> + +<orderedlist numeration="upperalpha"> + +<listitem><para>The first wrong way: + +<orderedlist> +<listitem><para>Open the <guilabel>Printers</guilabel> +folder.</para></listitem> + +<listitem><para>Right-click on the printer +(<guilabel>remoteprinter on cupshost</guilabel>) and +select in context menu <guimenuitem>Printing +Preferences...</guimenuitem></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> +<listitem><para>Open the <guilabel>Printers</guilabel> +folder.</para></listitem> + +<listitem><para>Right-click on the printer (<guilabel>remoteprinter on +cupshost</guilabel>) and select the context menu +<guimenuitem>Properties</guimenuitem>.</para></listitem> + +<listitem><para>Click on the <guilabel>General</guilabel> +tab.</para></listitem> + +<listitem><para>Click on the button <guibutton>Printing +Preferences...</guibutton></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, and the correct way: + +<orderedlist> + +<listitem><para>Open the <guilabel>Printers</guilabel> +folder.</para></listitem> + +<listitem><para>Click on the <guilabel>Advanced</guilabel> +tab. (If everything is <quote>grayed out,</quote> then you are not logged +in as a user with enough privileges).</para></listitem> + +<listitem><para>Click on the <guibutton>Printing +Defaults...</guibutton> button.</para></listitem> + +<listitem><para>On any of the two new tabs, click on the +<guibutton>Advanced...</guibutton> +button.</para></listitem> + +<listitem><para>A new dialog opens. Compare this one to the other +identical looking one from <quote>B.5</quote> or A.3".</para></listitem> +</orderedlist> +</para> +</listitem> +</orderedlist> + +<para> +Do you see any difference? I don't either. However, only the last +one, which you arrived at with steps <quote>C.1.-6.</quote>, will save any settings +permanently and be the defaults for new users. If you want all clients +to get the same defaults, you need to conduct these steps <emphasis>as +Administrator</emphasis> (<smbconfoption name="printer admin"/> in +&smb.conf;) <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).</para></sect2> + +<sect2><title>Most Common Blunders in Driver Settings on Windows Clients</title> +<para>Don't use <parameter>Optimize for +Speed</parameter>, but use <parameter>Optimize for +Portability</parameter> instead (Adobe PS Driver). Don't use +<parameter>Page Independence: No</parameter>: always +settle with <parameter>Page Independence: +Yes</parameter> (Microsoft PS Driver and CUPS PS Driver for +Windows NT/200x/XP). If there are problems with fonts, use +<parameter>Download as Softfont into +printer</parameter> (Adobe PS Driver). For +<guilabel>TrueType Download Options</guilabel> +choose <constant>Outline</constant>. Use PostScript +Level 2, if you are having trouble with a non-PS printer and if +there is a choice.</para></sect2> + +<sect2><title><command>cupsaddsmb</command> Does Not Work with Newly Installed Printer</title> +<para>Symptom: The last command of +<command>cupsaddsmb</command> does not complete successfully: +<command>cmd = setdriver printername printername</command> result was +NT_STATUS_UNSUCCESSFUL then possibly the printer was not yet +recognized by Samba. Did it show up in Network +Neighborhood? Did it show up i n <command>rpcclient +hostname -c `enumprinters'</command>? Restart smbd (or send a +<command>kill -HUP</command> to all processes listed by +<command>smbstatus</command> and try +again.</para></sect2> + +<sect2> +<title>Permissions on <filename>/var/spool/samba/</filename> Get Reset After Each Reboot</title> +<para>Have you ever by accident set the CUPS spool directory to +the same location? (<parameter>RequestRoot /var/spool/samba/</parameter> in <filename>cupsd.conf</filename> or +the other way round: <filename>/var/spool/cups/</filename> is set as +<smbconfoption name="path"/>> in the <smbconfsection name="[printers]"/> +section). These <parameter>must</parameter> be different. Set +<!--FIXME--> +<parameter>RequestRoot /var/spool/cups/</parameter> in +<filename>cupsd.conf</filename> and <smbconfoption name="path"> +/var/spool/samba</smbconfoption> in the <smbconfsection name="[printers]"/> +section of &smb.conf;. Otherwise cupsd will +sanitize permissions to its spool directory with each restart and +printing will not work reliably.</para></sect2> + +<sect2> +<title>Print Queue Called <quote>lp</quote> Mis-handles Print Jobs</title> + +<para> +In this case a print queue called <quote>lp</quote> intermittently swallows jobs and +spits out completely different ones from what was sent. +</para> + +<para>It is a bad idea to name any printer <quote>lp</quote>. This +is the traditional UNIX name for the default printer. CUPS may be set +up to do an automatic creation of Implicit Classes. This means, to +group all printers with the same name to a pool of devices, and +load-balancing the jobs across them in a round-robin fashion. Chances +are high that someone else has a printer named <quote>lp</quote> too. You may +receive his jobs and send your own to his device unwittingly. To have +tight control over the printer names, set <parameter>BrowseShortNames +No</parameter>. It will present any printer as <replaceable>printername@cupshost</replaceable> +and then gives you better control over what may happen in a large +networked environment.</para></sect2> + +<sect2><title>Location of Adobe PostScript Driver Files for <quote>cupsaddsmb</quote></title> +<para>Use <command>smbclient</command> to connect to any +Windows box with a shared PostScript printer: <command>smbclient +//windowsbox/print\$ -U guest</command>. You can navigate to the +<filename>W32X86/2</filename> subdir to <command>mget ADOBE*</command> +and other files or to <filename>WIN40/0</filename> to do the same. +Another option is to download the <filename>*.exe</filename> packaged +files from the Adobe Web site.</para></sect2> + +</sect1> + +<sect1> +<title>Overview of the CUPS Printing Processes</title> + +<para>A complete overview of the CUPS printing processes can be found in <link linkend="a_small">the next flowchart</link>.</para> + +<image id="a_small"> + <imagedescription>CUPS printing overview.</imagedescription> + <imagefile>a_small</imagefile> +</image> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Compiling.xml b/docs/Samba3-HOWTO/TOSHARG-Compiling.xml new file mode 100644 index 0000000000..4473e60fbf --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Compiling.xml @@ -0,0 +1,530 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="compiling"> +<chapterinfo> + &author.jelmer; + &author.jht; + &author.tridge; + + <pubdate> 22 May 2001 </pubdate> + <pubdate> 18 March 2003 </pubdate> +</chapterinfo> + +<title>How to Compile Samba</title> + +<para> +You can obtain the Samba source file from the +<ulink url="http://samba.org/">Samba Website.</ulink> To obtain a development version, +you can download Samba from Subversion or using <command>rsync</command>. +</para> + +<sect1> +<title>Access Samba Source Code via Subversion</title> + + +<sect2> +<title>Introduction</title> + +<para> +<indexterm><primary>Subversion</primary></indexterm> +Samba is developed in an open environment. Developers use a +Subversion to <quote>checkin</quote> (also known as +<quote>commit</quote>) new source code. Samba's various Subversion branches can +be accessed via anonymous Subversion using the instructions +detailed in this chapter. +</para> + +<para> +This chapter is a modified version of the instructions found at the +<ulink noescape="1" url="http://samba.org/samba/subversion.html">Samba</ulink> web site. +</para> + +</sect2> + +<sect2> +<title>Subversion Access to samba.org</title> + +<para> +The machine samba.org runs a publicly accessible Subversion +repository for access to the source code of several packages, +including Samba, rsync, distcc, ccache, and jitterbug. There are two main ways +of accessing the Subversion server on this host: +</para> + +<sect3> +<title>Access via SVNweb</title> + + +<para> +<indexterm><primary>SVN</primary><secondary>web</secondary></indexterm> +You can access the source code via your favorite WWW browser. This allows you to access +the contents of individual files in the repository and also to look at the revision +history and commit logs of individual files. You can also ask for a diff +listing between any two versions on the repository. +</para> + +<para> +Use the URL: +<ulink noescape="1" url="http://svnweb.samba.org/">http://svnweb.samba.org/</ulink> +</para> +</sect3> + +<sect3> +<title>Access via Subversion</title> + +<para> +You can also access the source code via a +normal Subversion client. This gives you much more control over what you can +do with the repository and allows you to checkout whole source trees +and keep them up-to-date via normal Subversion commands. This is the +preferred method of access if you are a developer and not +just a casual browser. +</para> + +<para>In order to be able to download the Samba sources off Subversion, you need +a Subversion client. Your distribution might include one, or you can download the +sources from <ulink noescape="1" url="http://subversion.tigris.org/">http://subversion.tigris.org/</ulink>. +</para> + +<para> +To gain access via anonymous Subversion, use the following steps. +</para> + +<procedure> + <title>Retrieving Samba using Subversion</title> + + <step> + <para> + Install a recent copy of Subversion. All you really need is a + copy of the Subversion client binary. + </para> + </step> + + <step> + <para> + Run the command + </para> + + <para> + <userinput>svn co svn://svnanon.samba.org/samba/trunk samba</userinput>. + </para> + + <para> + This will create a directory called <filename>samba</filename> containing the + latest Samba source code (usually the branch that is going to be the next major release). This + currently corresponds to the 3.1 development tree. + </para> + + <para> + Subversion branches other then trunk can be obtained by adding branches/BRANCH_NAME + to the URL you check out. A list of branch names + can be found on the <quote>Development</quote> 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 command: + </para> + + <para> + <userinput>svn co svn://svnanon.samba.org/samba/branches/SAMBA_3_0 samba_3</userinput>. + </para> + </step> + + <step> + <para> + Whenever you want to merge in the latest code changes, use + the following command from within the Samba directory: + </para> + + <para> + <userinput>svn update</userinput> + </para> + </step> +</procedure> + +</sect3> +</sect2> + +</sect1> + +<sect1> + <title>Accessing the Samba Sources via rsync and ftp</title> + + + <para> + <indexterm><primary>rsync</primary></indexterm> + <indexterm><primary>ftp</primary></indexterm> + <parameter>pserver.samba.org</parameter> also exports unpacked copies of most parts of the Subversion + tree at the Samba <ulink noescape="1" url="ftp://pserver.samba.org/pub/unpacked">pserver</ulink> + location and also via anonymous rsync at the Samba + <ulink noescape="1" url="rsync://pserver.samba.org/ftp/unpacked/">rsync</ulink> server location. + I recommend using rsync rather than ftp. + See <ulink noescape="1" url="http://rsync.samba.org/">the rsync home-page</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 Subversion does. <command>rsync</command> access is most convenient + for an initial install. + </para> +</sect1> + +<sect1> +<title>Verifying Samba's PGP Signature</title> + +<para> +<indexterm><primary>GPG</primary></indexterm> +It is 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. Many people today use the GNU GPG tool-set in place of PGP. +GPG can substitute for PGP. +</para> + + +<para> +With that said, go ahead and download the following files: +</para> + +<para><screen> +&prompt;<userinput>wget http://us1.samba.org/samba/ftp/samba-3.0.20.tar.asc</userinput> +&prompt;<userinput>wget http://us1.samba.org/samba/ftp/samba-pubkey.asc</userinput> +</screen></para> + + +<para> +<indexterm><primary>PGP</primary></indexterm> +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> + +<screen> +&prompt;<userinput>gpg --import samba-pubkey.asc</userinput> +</screen> + +<para> +and verify the Samba source code integrity with: +</para> + +<screen> +&prompt;<userinput>gzip -d samba-3.0.20.tar.gz</userinput> +&prompt;<userinput>gpg --verify samba-3.0.20.tar.asc</userinput> +</screen> + +<para> +If you receive a message like, <quote>Good signature from Samba Distribution Verification Key...</quote> +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> + +<para><screen> + gpg: BAD signature from <quote>Samba Distribution Verification Key</quote> +</screen></para> + +</sect1> + +<sect1> + <title>Building the Binaries</title> + + <para> + <indexterm><primary>autogen.sh</primary></indexterm> + After the source tarball has been unpacked, the next step involves + configuration to match Samba to your operating system platform. + If your source directory does not contain the <command>configure</command> script + it is necessary to build it before you can continue. Building of + the configure script requires the correct version of the autoconf + tool kit. Where the necessary version of autoconf is present, + the configure script can be generated by executing the following: +<screen> +&rootprompt; cd samba-3.0.20 +&rootprompt; ./autogen.sh +</screen> + </para> + + + <para> + <indexterm><primary>configure</primary></indexterm> + To build the binaries, run the program <userinput>./configure + </userinput> in the source directory. This should automatically + configure Samba for your operating system. If you have unusual + needs, then you may wish to run: +<screen> +&rootprompt;<userinput>./configure --help</userinput> +</screen> +</para> + + <para> + This will help you to see what special options can be enabled. Now execute + <userinput>./configure</userinput> with any arguments it might need: +<screen> +&rootprompt;<userinput>./configure <replaceable>[... arguments ...]</replaceable></userinput> +</screen> + </para> + + <para> + <indexterm><primary>make</primary></indexterm> + Execute the following create the binaries: +<screen> +&rootprompt; <userinput>make</userinput> +</screen> + Once it is successfully compiled you can execute the command shown here to + install the binaries and manual pages: +<screen> +&rootprompt; <userinput>make install</userinput> +</screen> + </para> + + <para> + Some people prefer to install binary files and man pages separately. If this is + your wish, the binary files can be installed by executing: +<screen> +&rootprompt; <userinput>make installbin</userinput> +</screen> + The man pages can be installed using this command: +<screen> +&rootprompt; <userinput>make installman</userinput> +</screen> + </para> + + <para> + Note that if you are upgrading from a previous version of Samba the old + versions of the binaries will be renamed with an <quote>.old</quote> extension. + You can go back to the previous version by executing: +<screen> +&rootprompt; <userinput>make revert</userinput> +</screen> + As you can see from this, building and installing Samba does not need to + result in disaster! + </para> + + + <sect2> + <title>Compiling Samba with Active Directory Support</title> + + <para> + In order to compile Samba with ADS support, you need to have installed + on your system: + </para> + + <itemizedlist> + + <listitem><para> + The MIT or Heimdal Kerberos development libraries + (either install from the sources or use a package). + </para></listitem> + + <listitem><para> + The OpenLDAP development libraries. + </para></listitem> + + </itemizedlist> + + <para> + If your Kerberos libraries are in a non-standard location, then + 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 contain lines like this: +<programlisting> +#define HAVE_KRB5 1 +#define HAVE_LDAP 1 +</programlisting> + </para> + + <para> + If it does not, 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><para>libkrb5-dev</para></listitem> + <listitem><para>krb5-user</para></listitem> + </itemizedlist> + </para> + </sect3> + + <sect3> + <title>Installing the Required Packages for Red Hat Linux</title> + + <para>On Red Hat Linux, this means you should have at least: </para> + <para> + <itemizedlist> + <listitem><para>krb5-workstation (for kinit)</para></listitem> + <listitem><para>krb5-libs (for linking with)</para></listitem> + <listitem><para>krb5-devel (because you are compiling from source)</para></listitem> + </itemizedlist> + </para> + + <para>in addition to the standard development environment.</para> + + <para>If these files are not installed on your system, you should check the installation + CDs to find which has them and install the files using your tool of choice. If in doubt + about what tool to use, refer to the Red Hat Linux documentation.</para> + + </sect3> + + <sect3> + <title>SuSE Linux Package Requirements</title> + + <para> + SuSE Linux installs Heimdal packages that may be required to allow you to build + binary packages. You should verify that the development libraries have been installed on + your system. + </para> + + <para> + SuSE Linux Samba RPMs support Kerberos. Please refer to the documentation for + your SuSE Linux system for information regarding SuSE Linux specific configuration. + Additionally, SuSE are very active in the maintenance of Samba packages that provide + the maximum capabilities that are available. You should consider using SuSE provided + packages where they are available. + </para> + + </sect3> + + </sect2> + +</sect1> + +<sect1> + <title>Starting the &smbd; &nmbd; and &winbindd;</title> + + + <para> + <indexterm><primary>inetd</primary></indexterm> + You must choose to start &smbd;, &winbindd; 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 by + <application>inetd</application> or <application>xinetd</application>, or you + can start them as daemons either from the command line or in + <filename>/etc/rc.local</filename>. See the man pages for details on the + command line options. Take particular care to read the bit about what user + you need to have to start Samba. In many cases, you must be root. + </para> + + <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> + + <indexterm><primary>inetd</primary></indexterm> + + <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><programlisting>netbios-ssn 139/tcp</programlisting></para> + + <para>Similarly for 137/udp, you should have an entry like:</para> + + <para><programlisting>netbios-ns 137/udp</programlisting></para> + + <para> + Next, edit your <filename>/etc/inetd.conf</filename> and add two lines like this: +<programlisting> +netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd +netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd +</programlisting> + </para> + + <para> + The exact syntax of <filename>/etc/inetd.conf</filename> + varies between UNIXes. Look at the other entries in inetd.conf + for a guide. + </para> + + <para> + <indexterm><primary>xinetd</primary></indexterm> + Some distributions use xinetd instead of inetd. Consult the + xinetd manual for configuration information. + </para> + + <note><para>Some UNIXes already have entries like netbios_ns + (note the underscore) in <filename>/etc/services</filename>. + You must edit <filename>/etc/services</filename> or + <filename>/etc/inetd.conf</filename> to make them consistent. + </para></note> + + <note><para> + <indexterm><primary>ifconfig</primary></indexterm> + On many systems you may need to use the + <smbconfoption name="interfaces"/> option in &smb.conf; to specify + the IP address and netmask of your interfaces. Run + <application>ifconfig</application> as root if you do + not know what the broadcast is for your net. &nmbd; tries + to determine it at run time, but fails on some UNIXes. + </para></note> + + <warning><para> + Many UNIXes only accept about five parameters on the command + line in <filename>inetd.conf</filename>. This means you shouldn't + use spaces between the options and arguments, or you should use + a script and start the script from <command>inetd</command>. + </para></warning> + + <para> + Restart <application>inetd</application>, perhaps just send it a HUP, + like this: +<screen> +&rootprompt;<userinput>killall -HUP inetd</userinput> +</screen> + </para> + + </sect2> + + <sect2> + <title>Alternative: Starting &smbd; as a Daemon</title> + + <para> + <indexterm><primary>daemon</primary></indexterm> + To start the server as a daemon, you should create a script something + like this one, perhaps calling it <filename>startsmb</filename>. + </para> + +<smbfile name="startsmb.sh"> +<para><programlisting> +#!/bin/sh +/usr/local/samba/bin/smbd -D +/usr/local/samba/bin/winbindd +/usr/local/samba/bin/nmbd -D +</programlisting></para> +</smbfile> + + <para> + Make it executable with <command>chmod +x startsmb</command> + </para> + + <para> + You can then run <command>startsmb</command> by hand or execute + it from <filename>/etc/rc.local</filename>. + </para> + + <para> + To kill it, send a kill signal to the processes &nmbd; and &smbd;. + </para> + + <note><para> + If you use the SVR4 style init system, you may like to look at the + <filename>examples/svr4-startup</filename> script to make Samba fit + into that system. + </para></note> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml b/docs/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml new file mode 100644 index 0000000000..d693c7edf6 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml @@ -0,0 +1,340 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="DNSDHCP"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>DNS and DHCP Configuration Guide</title> + +<sect1> +<title>Features and Benefits</title> + +<para> +There are few subjects in the UNIX world that might raise as much contention as +Domain Name System (DNS) and Dynamic Host Configuration Protocol (DHCP). +Not all opinions held for or against particular implementations of DNS and DHCP +are valid. +</para> + +<para> +We live in a modern age where many information technology users demand mobility +and freedom. Microsoft Windows users in particular expect to be able to plug their +notebook computer into a network port and have things <quote>just work.</quote> +</para> + +<para> +UNIX administrators have a point. Many of the normative practices in the Microsoft +Windows world at best border on bad practice from a security perspective. +Microsoft Windows networking protocols allow workstations to arbitrarily register +themselves on a network. Windows 2000 Active Directory registers entries in the DNS name space +that are equally perplexing to UNIX administrators. Welcome to the new world! +</para> + + +<para> +<indexterm><primary>ISC</primary><secondary>DNS</secondary></indexterm> +<indexterm><primary>ISC</primary><secondary>DHCP</secondary></indexterm> +The purpose of this chapter is to demonstrate the configuration of the Internet +Software Consortium (ISC) DNS and DHCP servers to provide dynamic services that are +compatible with their equivalents in the Microsoft Windows 2000 Server products. +</para> + +<para> +The purpose of this chapter is to provide no more than a working example of +configuration files for both DNS and DHCP servers. The examples used match +configuration examples used elsewhere in this document. +</para> + +<para> +This chapter explicitly does not provide a tutorial, nor does it pretend to be +a reference guide on DNS and DHCP, as this is well beyond the scope and intent +of this document as a whole. Anyone who wants more detailed reference materials +on DNS or DHCP should visit the ISC Web sites at <ulink noescape="1" url="http://www.isc.org"> +http://www.isc.org</ulink>. Those wanting a written text might also be interested +in the O'Reilly publications on these two subjects. +</para> + +</sect1> + +<sect1> +<title>Example Configuration</title> + +<para> +The domain name system is to the Internet what water is to life. By it nearly all +information resources (host names) are resolved to their Internet protocol (IP) address. +Windows networking tried hard to avoid the complexities of DNS, but alas, DNS won. +<indexterm><primary>WINS</primary></indexterm> +The alternative to DNS, the Windows Internet Name Service (WINS) an artifact of +NetBIOS networking over the TCP/IP protocols, has demonstrated scalability problems as +well as a flat non-hierarchical name space that became unmanageable as the size and +complexity of information technology networks grew. +</para> + +<para> +WINS is a Microsoft implementation of the RFC1001/1002 NetBIOS Name Service (NBNS). +It allows NetBIOS clients (like Microsoft Windows Machines) to register an arbitrary +machine name that the administrator or user has chosen together with the IP +address that the machine has been given. Through the use of WINS, network client machines +could resolve machine names to their IP address. +</para> + +<para> +The demand for an alternative to the limitations of NetBIOS networking finally drove +Microsoft to use DNS and Active Directory. Microsoft's new implementation attempts +to use DNS in a manner similar to the way that WINS is used for NetBIOS networking. +Both WINS and Microsoft DNS rely on dynamic name registration. +</para> + +<para> +Microsoft Windows clients can perform dynamic name registration to the DNS server +on start-up. Alternately, where DHCP is used to assign workstation IP addresses, +it is possible to register host names and their IP address by the DHCP server as +soon as a client acknowledges an IP address lease. Lastly, Microsoft DNS can resolve +hostnames via Microsoft WINS. +</para> + +<para> +The following configurations demonstrate a simple insecure Dynamic DNS server and +a simple DHCP server that matches the DNS configuration. +</para> + + <sect2> + <title>Dynamic DNS</title> + + <para> + <indexterm><primary>DNS</primary><secondary>Dynamic</secondary></indexterm> + The example DNS configuration is for a private network in the IP address + space for network 192.168.1.0/24. The private class network address space + is set forth in RFC1918. + </para> + + + <para> + <indexterm><primary>BIND</primary></indexterm> + It is assumed that this network will be situated behind a secure firewall. + The files that follow work with ISC BIND version 9. BIND is the Berkeley + Internet Name Daemon. The following configuration files are offered: + </para> + + <para> + The master configuration file <filename>/etc/named.conf</filename> + determines the location of all further configuration files used. + The location and name of this file is specified in the start-up script + that is part of the operating system. + <smbfile name="named.conf"> +<programlisting> +# Quenya.Org configuration file + +acl mynet { + 192.168.1.0/24; + 127.0.0.1; +}; + +options { + + directory "/var/named"; + listen-on-v6 { any; }; + notify no; + forward first; + forwarders { + 192.168.1.1; + }; + auth-nxdomain yes; + multiple-cnames yes; + listen-on { + mynet; + }; +}; + +# The following three zone definitions do not need any modification. +# The first one defines localhost while the second defines the +# reverse lookup for localhost. The last zone "." is the +# definition of the root name servers. + +zone "localhost" in { + type master; + file "localhost.zone"; +}; + +zone "0.0.127.in-addr.arpa" in { + type master; + file "127.0.0.zone"; +}; + +zone "." in { + type hint; + file "root.hint"; +}; + +# You can insert further zone records for your own domains below. + +zone "quenya.org" { + type master; + file "/var/named/quenya.org.hosts"; + allow-query { + mynet; + }; + allow-transfer { + mynet; + }; + allow-update { + mynet; + }; + }; + +zone "1.168.192.in-addr.arpa" { + type master; + file "/var/named/192.168.1.0.rev"; + allow-query { + mynet; + }; + allow-transfer { + mynet; + }; + allow-update { + mynet; + }; +}; +</programlisting> +</smbfile> + </para> + + <para> + The following files are all located in the directory <filename>/var/named</filename>. + This is the <filename>/var/named/localhost.zone</filename> file: + <smbfile name="localhost.zone"> +<programlisting> +$TTL 1W +@ IN SOA @ root ( + 42 ; serial (d. adams) + 2D ; refresh + 4H ; retry + 6W ; expiry + 1W ) ; minimum + + IN NS @ + IN A 127.0.0.1 + </programlisting> +</smbfile> + </para> + + <para> + The <filename>/var/named/127.0.0.zone</filename> file: + <smbfile name="127.0.0.0.zone"> +<programlisting> +$TTL 1W +@ IN SOA localhost. root.localhost. ( + 42 ; serial (d. adams) + 2D ; refresh + 4H ; retry + 6W ; expiry + 1W ) ; minimum + + IN NS localhost. +1 IN PTR localhost. +</programlisting> +</smbfile> + </para> + + <para> + The <filename>/var/named/quenya.org.host</filename> file: + <smbfile name="quenya.org.host"> +<programlisting> +$ORIGIN . +$TTL 38400 ; 10 hours 40 minutes +quenya.org IN SOA marvel.quenya.org. root.quenya.org. ( + 2003021832 ; serial + 10800 ; refresh (3 hours) + 3600 ; retry (1 hour) + 604800 ; expire (1 week) + 38400 ; minimum (10 hours 40 minutes) + ) + NS marvel.quenya.org. + MX 10 mail.quenya.org. +$ORIGIN quenya.org. +frodo A 192.168.1.1 +marvel A 192.168.1.2 +; +mail CNAME marvel +www CNAME marvel +</programlisting> +</smbfile> +</para> + +<para> + The <filename>/var/named/192.168.1.0.rev</filename> file: + <smbfile name="192.168.1.0.rev"> +<programlisting> +$ORIGIN . +$TTL 38400 ; 10 hours 40 minutes +1.168.192.in-addr.arpa IN SOA marvel.quenya.org. root.quenya.org. ( + 2003021824 ; serial + 10800 ; refresh (3 hours) + 3600 ; retry (1 hour) + 604800 ; expire (1 week) + 38400 ; minimum (10 hours 40 minutes) + ) + NS marvel.quenya.org. +$ORIGIN 1.168.192.in-addr.arpa. +1 PTR frodo.quenya.org. +2 PTR marvel.quenya.org. +</programlisting> +</smbfile> + </para> + + <para> + The above were copied from a fully working system. All dynamically registered + entries have been removed. In addition to these files, BIND version 9 will + create for each of the dynamic registration files a file that has a + <filename>.jnl</filename> extension. Do not edit or tamper with the configuration + files or with the <filename>.jnl</filename> files that are created. + </para> + + </sect2> + + <sect2 id="DHCP"> + <title>DHCP Server</title> + + <para> + The following file is used with the ISC DHCP Server version 3. + The file is located in <filename>/etc/dhcpd.conf</filename>: + </para> + + <para> + <smbfile name="dhcpd.conf"> + <programlisting> +ddns-updates on; +ddns-domainname "quenya.org"; +option ntp-servers 192.168.1.2; +ddns-update-style ad-hoc; +allow unknown-clients; +default-lease-time 86400; +max-lease-time 172800; + +option domain-name "quenya.org"; +option domain-name-servers 192.168.1.2; +option netbios-name-servers 192.168.1.2; +option netbios-dd-server 192.168.1.2; +option netbios-node-type 8; + +subnet 192.168.1.0 netmask 255.255.255.0 { + range dynamic-bootp 192.168.1.60 192.168.1.254; + option subnet-mask 255.255.255.0; + option routers 192.168.1.2; + allow unknown-clients; +} +</programlisting> +</smbfile> + </para> + + <para> + In the above example, IP addresses between 192.168.1.1 and 192.168.1.59 are + reserved for fixed address (commonly called <constant>hard-wired</constant>) IP addresses. The + addresses between 192.168.1.60 and 192.168.1.254 are allocated for dynamic use. + </para> + + </sect2> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Diagnosis.xml b/docs/Samba3-HOWTO/TOSHARG-Diagnosis.xml new file mode 100644 index 0000000000..9f4f3dd2c0 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Diagnosis.xml @@ -0,0 +1,559 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="diagnosis"> +<chapterinfo> + &author.tridge; + &author.jelmer; + &author.danshearer; + <pubdate>Wed Jan 15</pubdate> +</chapterinfo> + +<title>The Samba Checklist</title> + +<sect1> +<title>Introduction</title> + +<para> +This file contains a list of tests you can perform to validate your +Samba server. It also tells you what the likely cause of the problem +is if it fails any one of these steps. If it passes all these tests, +then it is probably working fine. +</para> + +<para> +You should do all the tests, in the order shown. We have tried to +carefully choose them so later tests only use capabilities verified in +the earlier tests. However, do not stop at the first error as there +have been some instances when continuing with the tests has helped +to solve a problem. +</para> + +<para> +If you send one of the Samba mailing lists an email saying, <quote>it does not work</quote> +and you have not followed this test procedure, you should not be surprised +if your email is ignored. +</para> + +</sect1> + +<sect1> +<title>Assumptions</title> + +<para> +In all of the tests, it is assumed you have a Samba server called +BIGSERVER and a PC called ACLIENT both in workgroup TESTGROUP. +</para> + +<para> +The procedure is similar for other types of clients. +</para> + +<para> +It is also assumed you know the name of an available share in your +&smb.conf;. I will assume this share is called <smbconfsection name="tmp"/>. +You can add a <smbconfsection name="tmp"/> share like this by adding the +lines shown in <link linkend="tmpshare">the next example</link>. +</para> + +<para><smbconfexample id="tmpshare"> +<title>smb.conf with [tmp] share</title> +<smbconfsection name="[tmp]"/> +<smbconfoption name="comment">temporary files </smbconfoption> +<smbconfoption name="path">/tmp</smbconfoption> +<smbconfoption name="read only">yes</smbconfoption> +</smbconfexample> +</para> + +<note><para> +These tests assume version 3.0.0 or later of the Samba suite. +Some commands shown did not exist in earlier versions. +</para></note> + +<para> +Please pay attention to the error messages you receive. If any error message +reports that your server is being unfriendly, you should first check that your +IP name resolution is correctly set up. Make sure your <filename>/etc/resolv.conf</filename> +file points to name servers that really do exist. +</para> + +<para> +Also, if you do not have DNS server access for name resolution, please check +that the settings for your &smb.conf; file results in <command>dns proxy = no</command>. The +best way to check this is with <command>testparm smb.conf</command>. +</para> + + +<para> +<indexterm><primary>log files</primary><secondary>monitoring</secondary></indexterm> +It is helpful to monitor the log files during testing by using the +<command>tail -F log_file_name</command> in a separate +terminal console (use ctrl-alt-F1 through F6 or multiple terminals in X). +Relevant log files can be found (for default installations) in +<filename>/usr/local/samba/var</filename>. Also, connection logs from +machines can be found here or possibly in <filename>/var/log/samba</filename>, +depending on how or if you specified logging in your &smb.conf; file. +</para> + +<para> +If you make changes to your &smb.conf; file while going through these test, +remember to restart &smbd; and &nmbd;. +</para> + +</sect1> + +<sect1> +<title>The Tests</title> +<procedure> +<title>Diagnosing your Samba server</title> + + +<step performance="required"> +<para> +<indexterm><primary>testparm</primary></indexterm> +In the directory in which you store your &smb.conf; file, run the command +<command>testparm smb.conf</command>. If it reports any errors, then your &smb.conf; +configuration file is faulty. +</para> + +<note><para> +Your &smb.conf; file may be located in: <filename>/etc/samba</filename> +or in <filename>/usr/local/samba/lib</filename>. +</para></note> +</step> + +<step performance="required"> +<para> +Run the command <command>ping BIGSERVER</command> from the PC and +<command>ping ACLIENT</command> from the UNIX box. If you do not get a valid response, +then your TCP/IP software is not correctly installed. +</para> + +<para> +You will need to start a <quote>dos prompt</quote> window on the PC to run ping. +</para> + +<para> +If you get a message saying <quote><errorname>host not found</errorname></quote> 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 it is assumed +you do have correct entries for the remainder of these tests. +</para> + +<para> +Another reason why ping might fail is if your host is running firewall +software. You will need to relax the rules to let in the workstation +in question, perhaps by allowing access from another subnet (on Linux +this is done via the appropriate firewall maintenance commands <command>ipchains</command> +or <command>iptables</command>). +</para> + +<note> +<para> +Modern Linux distributions install ipchains/iptables by default. +This is a common problem that is often overlooked. +</para> +</note> + +<para> +If you wish to check what firewall rules may be present in a system under test, simply run +<command>iptables -L -v</command> or if <parameter>ipchains</parameter>-based firewall rules are in use, +<command>ipchains -L -v</command>. +</para> + +<para> +Here is a sample listing from a system that has an external ethernet interface (eth1) on which Samba +is not active, and an internal (private network) interface (eth0) on which Samba is active: +<screen> +frodo:~ # iptables -L -v +Chain INPUT (policy DROP 98496 packets, 12M bytes) + pkts bytes target prot opt in out source destination + 187K 109M ACCEPT all -- lo any anywhere anywhere + 892K 125M ACCEPT all -- eth0 any anywhere anywhere +1399K 1380M ACCEPT all -- eth1 any anywhere anywhere \ + state RELATED,ESTABLISHED + +Chain FORWARD (policy DROP 0 packets, 0 bytes) + pkts bytes target prot opt in out source destination + 978K 1177M ACCEPT all -- eth1 eth0 anywhere anywhere \ + state RELATED,ESTABLISHED + 658K 40M ACCEPT all -- eth0 eth1 anywhere anywhere + 0 0 LOG all -- any any anywhere anywhere \ + LOG level warning + +Chain OUTPUT (policy ACCEPT 2875K packets, 1508M bytes) + pkts bytes target prot opt in out source destination + +Chain reject_func (0 references) + pkts bytes target prot opt in out source destination +</screen> +</para> + +</step> + +<step performance="required"> +<para> +Run the command: <command>smbclient -L BIGSERVER</command> +on the UNIX box. You should get back a list of available shares. +</para> + +<para> +If you get an error message containing the string <quote>Bad password</quote>, then +you probably have either an incorrect <parameter>hosts allow</parameter>, +<parameter>hosts deny</parameter> or <parameter>valid users</parameter> line in your +&smb.conf;, or your guest account is not valid. Check what your guest account is using &testparm; and +temporarily remove any <parameter>hosts allow</parameter>, <parameter>hosts deny</parameter>, +<parameter>valid users</parameter> or <parameter>invalid users</parameter> lines. +</para> + +<para> +If you get a message <quote><errorname>connection refused</errorname></quote> response, then the <command>smbd</command> server may +not be running. If you installed it in <filename>inetd.conf</filename>, 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 +state using <command>netstat -a</command>. +</para> + +<note><para> +<indexterm><primary>inetd</primary></indexterm> +<indexterm><primary>xinetd</primary><see>inetd</see></indexterm> +Some UNIX/Linux systems use <command>xinetd</command> in place of +<command>inetd</command>. Check your system documentation for the location +of the control files for your particular system implementation of +the network super daemon. +</para></note> + +<para> +If you get a message saying <quote><errorname>session request failed</errorname></quote>, the server refused the +connection. If it says <quote>Your server software is being unfriendly</quote>, then +it's probably because you have invalid command line parameters to &smbd;, +or a similar fatal problem with the initial startup of &smbd;. Also +check your config file (&smb.conf;) for syntax errors with &testparm; +and that the various directories where Samba keeps its log and lock +files exist. +</para> + +<para> +There are a number of reasons for which smbd may refuse or decline +a session request. The most common of these involve one or more of +the &smb.conf; file entries as shown in <link linkend="modif1">the next example</link>. +</para> + + +<para> +<smbconfexample id="modif1"> + <title>Configuration for only allowing connections from a certain subnet</title> +<smbconfsection name="[globals]"/> +<member>...</member> +<smbconfoption name="hosts deny">ALL</smbconfoption> +<smbconfoption name="hosts allow">xxx.xxx.xxx.xxx/yy</smbconfoption> +<smbconfoption name="interfaces">eth0</smbconfoption> +<smbconfoption name="bind interfaces only">Yes</smbconfoption> +<member>...</member> +</smbconfexample> +</para> + +<para> +In the above, no allowance has been made for any session requests that +will automatically translate to the loopback adapter address 127.0.0.1. +To solve this problem, change these lines as shown in <link linkend="modif2">the following example</link>. +</para> + +<para> +<smbconfexample id="modif2"> + <title>Configuration for allowing connections from a certain subnet and localhost</title> +<smbconfsection name="[globals]"/> +<member>...</member> +<smbconfoption name="hosts deny">ALL</smbconfoption> +<smbconfoption name="hosts allow">xxx.xxx.xxx.xxx/yy 127.</smbconfoption> +<smbconfoption name="interfaces">eth0 lo</smbconfoption> +<member>...</member> +</smbconfexample> +</para> + +<para> +<indexterm><primary>inetd</primary></indexterm> +Another common cause of these two errors is having something already running +<indexterm><primary>smbclient</primary></indexterm> +on port <constant>139</constant>, such as Samba (&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 &smbmdash; it can avoid a lot of frustration! +</para> + +<para> +And yet another possible cause for failure of this test is when the subnet mask +and/or broadcast address settings are incorrect. Please check that the +network interface IP Address/Broadcast Address/Subnet Mask settings are +correct and that Samba has correctly noted these in the <filename>log.nmbd</filename> file. +</para> + +</step> + +<step performance="required"> + +<para> +Run the command: <command>nmblookup -B BIGSERVER __SAMBA__</command>. +You should get back the IP address of your Samba server. +</para> + +<para> +If you do not, then nmbd is incorrectly installed. Check your <filename>inetd.conf</filename> +if you run it from there, or that the daemon is running and listening to udp port 137. +</para> + +<para> +One common problem is that many inetd implementations can't take many +parameters on the command line. If this is the case, then create a +one-line script that contains the right parameters and run that from +inetd. +</para> + +</step> + +<step performance="required"> + +<para> +Run the command: <command>nmblookup -B ACLIENT `*'</command> +</para> + +<para> +You should get the PC's IP address back. If you do not then the client +software on the PC isn't installed correctly, or isn't started, or you +got the name of the PC wrong. +</para> + +<para> +If ACLIENT does not resolve via DNS then use the IP address of the +client in the above test. +</para> + +</step> + +<step performance="required"> + +<para> +Run the command: <command>nmblookup -d 2 '*'</command> +</para> + +<para> +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/TCP/IP hosts on the network should respond, although Samba may +not catch all of the responses in the short time it listens. You +should see the <quote><errorname>got a positive name query response</errorname></quote> +messages from several hosts. +</para> + +<para> +If this does not give a similar result to the previous test, then +nmblookup isn't correctly getting your broadcast address through its +automatic mechanism. In this case you should experiment with the +<smbconfoption name="interfaces"/> option in &smb.conf; to manually configure your IP +address, broadcast and netmask. +</para> + +<para> +If your PC and server aren't on the same subnet, then you will need to use the +<option>-B</option> option to set the broadcast address to that of the PCs subnet. +</para> + +<para> +This test will probably fail if your subnet mask and broadcast address are +not correct. (Refer to TEST 3 notes above). +</para> + +</step> + +<step performance="required"> + + +<para> +<indexterm><primary>smbclient</primary></indexterm> +Run the command: <command>smbclient //BIGSERVER/TMP</command>. You should +then be prompted for a password. You should use the password of the account +with which you are logged into the UNIX box. If you want to test with +another account, then add the <option>-U accountname</option> option to the end of +the command line. For example, <command>smbclient //bigserver/tmp -Ujohndoe</command>. +</para> + +<note><para> +It is possible to specify the password along with the username as follows: +<command>smbclient //bigserver/tmp -Ujohndoe%secret</command>. +</para></note> + +<para> +Once you enter the password, you should get the <prompt>smb></prompt> prompt. If you +do not, then look at the error message. If it says <quote><errorname>invalid network +name</errorname></quote>, then the service <smbconfsection name="tmp"/> is not correctly setup in your &smb.conf;. +</para> + +<para> +If it says <quote><errorname>bad password</errorname></quote>, then the likely causes are: +</para> + +<orderedlist> +<listitem> + <para> + You have shadow passwords (or some other password system) but didn't + compile in support for them in &smbd;. + </para> +</listitem> + +<listitem> + <para> + Your <smbconfoption name="valid users"/> configuration is incorrect. + </para> +</listitem> + +<listitem> + <para> + You have a mixed case password and you haven't enabled the <smbconfoption name="password level"/> option at a high enough level. + </para> +</listitem> + +<listitem> + <para> + The <smbconfoption name="path"/> line in &smb.conf; is incorrect. Check it with &testparm;. + </para> +</listitem> + +<listitem> + <para> + You enabled password encryption but didn't map UNIX to Samba users. Run: + <command>smbpasswd -a username</command> + </para> +</listitem> +</orderedlist> + +<para> +Once connected, you should be able to use the commands <command>dir</command>, <command>get</command>, +<command>put</command> and so on. Type <command>help command</command> for instructions. You should +especially check that the amount of free disk space shown is correct when you type <command>dir</command>. +</para> + +</step> + +<step performance="required"> + +<para> +On the PC, type the command <command>net view \\BIGSERVER</command>. You will +need to do this from within a dos prompt window. You should get back a +list of shares available on the server. +</para> + +<para> +If you get a message <quote><errorname>network name not found</errorname></quote> or similar error, then netbios +name resolution is not working. This is usually caused by a problem in <command>nmbd</command>. +To overcome it, you could do one of the following (you only need to choose one of them): +</para> + +<orderedlist> +<listitem><para> + Fixup the &nmbd; installation. +</para></listitem> + +<listitem><para> + Add the IP address of BIGSERVER to the <command>wins server</command> box in the + advanced TCP/IP setup on the PC. +</para></listitem> + +<listitem><para> + Enable Windows name resolution via DNS in the advanced section of the TCP/IP setup. +</para></listitem> + +<listitem><para> + Add BIGSERVER to your lmhosts file on the PC. +</para></listitem> +</orderedlist> + +<para> +If you get a message <quote><errorname>invalid network name</errorname></quote> or +<quote><errorname>bad password error</errorname></quote>, then apply the +same fixes as for the <command>smbclient -L</command> test above. In +particular, make sure your <command>hosts allow</command> line is correct (see the man pages). +</para> + +<para> +Also, do not overlook that fact that when the workstation requests the +connection to the Samba server, it will attempt to connect using the +name with which you logged onto your Windows machine. You need to make +sure that an account exists on your Samba server with that exact same +name and password. +</para> + +<para> +If you get a message <quote><errorname>specified computer is not receiving requests</errorname></quote> or similar, +it probably means that the host is not contact-able 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, and so on.) +</para> + +</step> + +<step performance="required"> + +<para> +Run the command <command>net use x: \\BIGSERVER\TMP</command>. You should +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 <parameter>hosts allow</parameter> +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 +<smbconfoption name="user">username</smbconfoption> to the +<smbconfsection name="[tmp]"/> section of +&smb.conf; where <parameter>username</parameter> is the +username corresponding to the password you typed. If you find this +fixes things, you may need the username mapping option. +</para> + +<para> +It might also be the case that your client only sends encrypted passwords +and you have <smbconfoption name="encrypt passwords">no</smbconfoption> in &smb.conf;. +Change this to "yes" to fix this. +</para> + +</step> + +<step performance="required"> + +<para> +Run the command <command>nmblookup -M <parameter>testgroup</parameter></command> where +<parameter>testgroup</parameter> is the name of the workgroup that your Samba server and +Windows PCs belong to. You should get back the IP address of the +master browser for that workgroup. +</para> + +<para> +If you do not, 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 <smbconfoption name="preferred master">yes</smbconfoption> to ensure that +an election is held at startup. +</para> + +</step> + +<step performance="required"> + +<para> +From file manager, try to browse the server. Your Samba server should +appear in the browse list of your local workgroup (or the one you +specified in &smb.conf;). You should be able to double click on the name +of the server and get a list of shares. If you get the error message <quote>invalid password</quote>, + you are probably running Windows NT 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 +<smbconfoption name="security">server</smbconfoption> and +<smbconfoption name="password server">Windows_NT_Machine</smbconfoption> in your +&smb.conf; file, or make sure <smbconfoption name="encrypt passwords"/> is +set to <quote>yes</quote>. +</para> + +</step> +</procedure> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-DomainMember.xml b/docs/Samba3-HOWTO/TOSHARG-DomainMember.xml new file mode 100644 index 0000000000..0c7689c32f --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-DomainMember.xml @@ -0,0 +1,1106 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="domain-member"> + +<chapterinfo> + &author.jht; + &author.jeremy; + &author.jerry; + &author.tridge; + &author.jelmer; + <author>&person.gd;<contrib>LDAP updates</contrib></author> +</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 able to offer a viable option for many users. +</para> + +<para> +This chapter covers background information pertaining to Domain Membership, +the 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 +misinformation, 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 +be made Domain Members. Participating in Domain Security is often called +<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 &smbmdash; 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> +<indexterm><primary>Server Type</primary><secondary>Domain Member</secondary></indexterm> +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. Domain Membership has many advantages: +</para> + +<itemizedlist> + <listitem><para> +<indexterm><primary>SAM</primary></indexterm> + MS Windows workstation users get the benefit of SSO. + </para></listitem> + + <listitem><para> + Domain user access rights and file ownership/access controls can be set + from the single Domain Security Account Manager (SAM) database + (works with Domain Member servers as well as with MS Windows workstations + that are Domain Members). + </para></listitem> + + <listitem><para> + 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 (<filename>NTConfig.POL</filename>) and Desktop Profiles. + </para></listitem> + + <listitem><para> + Through the use of logon scripts, users can be given transparent access to network + applications that run off application servers. + </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 backend-ed with an + LDAP directory, or via an Active Directory infrastructure). + </para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="machine-trust-accounts"> +<title>MS Windows Workstation/Server Machine Trust Accounts</title> + +<para> +<indexterm><primary>Machine Trust Accounts</primary></indexterm> +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 <quote>Computer Account.</quote> The purpose of the machine account +is to prevent a rogue user and Domain Controller from colluding to gain access to a +domain member workstation. +</para> + +<para> +The password of a Machine Trust Account acts as the shared secret for +secure communication with the Domain Controller. This is a security +feature to prevent an unauthorized machine with the same NetBIOS name +from joining the domain and gaining access to domain user/group +accounts. Windows NT/200x/XP Professional clients use machine trust +accounts, but Windows 9x/Me/XP Home clients do not. Hence, a +Windows 9x/Me/XP Home client is never a true member of a Domain +because it does not possess a Machine Trust Account, and, thus, has no +shared secret with the Domain Controller. +</para> + +<para> +A Windows NT4 PDC stores each Machine Trust Account in the Windows Registry. +The introduction of MS Windows 2000 saw the introduction of Active Directory, +the new repository for Machine Trust Accounts. A Samba PDC, however, stores +each Machine Trust Account in two parts, +as follows: + +<itemizedlist> + <listitem><para> + A Domain Security Account (stored in the + <smbconfoption name="passdb backend"/> 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> + The older format of this data is the <filename>smbpasswd</filename> database + that contains the UNIX login ID, the UNIX user identifier (UID), and the + LanMan and NT encrypted passwords. There is also some other information in + this file that we do not need to concern ourselves with here. + </para> + + <para> + The two newer database types are called ldapsam, and + tdbsam. Both store considerably more data than the + older <filename>smbpasswd</filename> file did. The extra information + enables new user account controls to be implemented. + </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. + </para></listitem> +</itemizedlist> +</para> + +<para> +<indexterm><primary>Machine Trust Accounts</primary><secondary>creating</secondary></indexterm> +There are three ways to create Machine Trust Accounts: +</para> + +<itemizedlist> + <listitem><para> + Manual creation from the UNIX/Linux command line. Here, both the Samba and + corresponding UNIX account are created by hand. + </para></listitem> + + <listitem><para> + <indexterm><primary>Server Manager</primary></indexterm> + 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 as long as the user is + logged on as the administrator account. + </para></listitem> + + <listitem><para> + <quote>On-the-fly</quote> 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> + +<sect2> +<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 another <quote>add user</quote> command +that is normally used to create new UNIX accounts. The following is an example for +a Linux-based Samba server: +</para> + +<para> +<indexterm><primary>useradd</primary></indexterm> +<indexterm><primary>vipw</primary></indexterm> +<screen> +&rootprompt;<userinput>/usr/sbin/useradd -g machines -d /var/lib/nobody -c <replaceable>"machine nickname"</replaceable> \ + -s /bin/false <replaceable>machine_name</replaceable>$ </userinput> + +&rootprompt;<userinput>passwd -l <replaceable>machine_name</replaceable>$</userinput> +</screen> +</para> + +<para>In the example above there is an existing system group <quote>machines</quote> which is used +as the primary group for all machine accounts. In the following examples the <quote>machines</quote> group has +numeric GID equal 100.</para> + +<para> +<indexterm><primary>chpass</primary></indexterm> +On *BSD systems, this can be done using the <command>chpass</command> utility: +</para> + +<para> +<screen> +&rootprompt;<userinput>chpass -a \ +'<replaceable>machine_name</replaceable>$:*:101:100::0:0:Windows <replaceable>machine_name</replaceable>:/dev/null:/sbin/nologin'</userinput> +</screen> +</para> + +<para> +The <filename>/etc/passwd</filename> entry will list the machine name +with a <quote>$</quote> appended, will not have a password, will have a null shell and no +home directory. For example, a machine named <quote>doppy</quote> would have an +<filename>/etc/passwd</filename> entry like this: +</para> + +<programlisting> +doppy$:x:505:100:<replaceable>machine_nickname</replaceable>:/dev/null:/bin/false +</programlisting> + +<para> +Above, <replaceable>machine_nickname</replaceable> can be any +descriptive name for the client, i.e., BasementComputer. +<replaceable>machine_name</replaceable> absolutely must be the NetBIOS +name of the client to be joined to the domain. The <quote>$</quote> must be +appended to the NetBIOS name of the client or Samba will not recognize +this as a Machine Trust Account. +</para> + +<para> +Now that the corresponding UNIX account has been created, the next step is to create +the Samba account for the client containing the well-known initial +Machine Trust Account password. This can be done using the +<command>smbpasswd</command> command +as shown here: +</para> + +<para> +<screen> +&rootprompt;<userinput>smbpasswd -a -m <replaceable>machine_name</replaceable></userinput> +</screen> +</para> + +<para> +where <replaceable>machine_name</replaceable> is the machine's NetBIOS +name. The RID of the new machine account is generated from the UID of +the corresponding UNIX account. +</para> + +<warning> +<title>Join the client to the domain immediately</title> + +<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 +<indexterm><primary>Server Manager</primary></indexterm> +the <application>Server Manager</application>. From the time at which the +account is created to the time 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> +</sect2> + +<sect2> +<title>Managing Domain Machine Accounts using NT4 Server Manager</title> + +<para> +A working <smbconfoption name="add machine script"/> is essential +for machine trust accounts to be automatically created. This applies no matter whether +one uses automatic account creation, or if one wishes to use the NT4 Domain Server Manager. +</para> + +<para> +<indexterm><primary>SRVTOOLS.EXE</primary></indexterm> +If the machine from which you are trying to manage the domain is an +<application>MS Windows NT4 workstation or MS Windows 200x/XP Professional</application>, +the tool of choice is the package called <command>SRVTOOLS.EXE</command>. +When executed in the target directory it will unpack <command>SrvMgr.exe</command> +and <command>UsrMgr.exe</command> (both are domain management tools for MS Windows NT4 workstation). +</para> + +<para> +<indexterm><primary>Nexus.exe</primary></indexterm> +If your workstation is a <application>Microsoft Windows 9x/Me</application> family 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 +this platform. +</para> + +<para> +Further information about these tools may be obtained from the following locations: +</para> + +<para> +<simplelist> +<member><ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;173673"/></member> +<member><ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;172540"/></member> +</simplelist> +</para> + +<para> +Launch the <command>srvmgr.exe</command> (Server Manager for Domains) and follow these steps: +</para> + +<procedure> +<title>Server Manager Account Machine Account Management</title> + <step><para> + From the menu select <guimenu>Computer</guimenu>. + </para></step> + + <step><para> + Click <guimenuitem>Select Domain</guimenuitem>. + </para></step> + + <step><para> + Click 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 <guimenu>Computer</guimenu>. + </para></step> + + <step><para> + Select <guimenuitem>Add to Domain</guimenuitem>. + </para></step> + + <step><para> + In the dialog box, click the radio button to + <guilabel>Add NT Workstation of Server</guilabel>, then + enter the machine name in the field provided, and click the + <guibutton>Add</guibutton> button. + </para></step> +</procedure> + +</sect2> + +<sect2> +<title>On-the-Fly Creation of Machine Trust Accounts</title> + +<para> +The second (and recommended) way of creating Machine Trust Accounts is +simply to allow the Samba server to create them as needed when the client +is joined to the domain. +</para> + +<para>Since each Samba Machine Trust Account requires a corresponding UNIX account, a method +for automatically creating the UNIX account is usually supplied; this requires configuration of the +add machine script option in &smb.conf;. This method is not required, however, corresponding UNIX +accounts may also be created manually. +</para> + + +<para> +Here is an example for a Red Hat Linux system. +</para> + +<para><smbconfblock> +<smbconfsection name="[global]"/> +<smbconfcomment><...remainder of parameters...></smbconfcomment> +<smbconfoption name="add machine script">/usr/sbin/useradd -d /var/lib/nobody -g 100 -s /bin/false -M %u</smbconfoption> +</smbconfblock></para> + + +</sect2> + + +<sect2><title>Making an MS Windows Workstation or Server a Domain Member</title> + +<para> +The procedure for making an MS Windows workstation or server a member of the domain varies +with the version of Windows. +</para> + +<sect3> + <title>Windows 200x/XP Professional Client</title> + + <para> + When the user elects to make the client a Domain Member, Windows 200x prompts for + an account and password that has privileges to create machine accounts in the domain. + A Samba Administrator Account (i.e., a Samba account that has <constant>root</constant> privileges on the + Samba server) must be entered here; the operation will fail if an ordinary user + account is given. + </para> + + <para> + For security reasons, the password for this Administrator Account should be set + to a password that is other than that used for the root user in <filename>/etc/passwd</filename>. + </para> + + <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 <constant>root</constant> + then this is easily mapped to <constant>root</constant> in the file named in the &smb.conf; parameter + <smbconfoption name="username map">/etc/samba/smbusers</smbconfoption>. + </para> + + <para> + The session key of the Samba Administrator Account acts as an 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> +</sect3> + +<sect3> + <title>Windows NT4 Client</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 <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 <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 Administrator Account when + prompted). + </para> +</sect3> + +<sect3> + <title>Samba Client</title> + + <para>Joining a Samba client to a domain is documented in + <link linkend="domain-member-server">Domain Member Server</link>. + </para> +</sect3> + +</sect2> +</sect1> + +<sect1 id="domain-member-server"> +<title>Domain Member Server</title> + +<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. +</para> + +<para> +<emphasis> +Of course it should be clear that the authentication backend itself could be +from any distributed directory architecture server that is supported by Samba. +This can be LDAP (from OpenLDAP), or Sun's iPlanet, or NetWare Directory +Server, and so on. +</emphasis> +</para> + +<note><para> +When Samba is configured to use an LDAP, or other identity management and/or +directory service, it is Samba that continues to perform user and machine +authentication. It should be noted that the LDAP server does not perform +authentication handling in place of what Samba is designed to do. +</para></note> + +<para> +Please refer to <link linkend="samba-pdc">Domain Control</link>, for more information regarding +how to create a domain machine account for a Domain Member server as well as for +information on how to enable the Samba Domain Member machine to join the domain +and be fully trusted by it. +</para> + +<sect2> +<title>Joining an NT4-type Domain with Samba-3</title> + +<para><link linkend="assumptions">Next table</link> lists names that have been used in the remainder of this chapter.</para> + +<table frame="all" id="assumptions"><title>Assumptions</title> + <tgroup cols="2"> + <colspec align="right"/> + <colspec align="left"/> + <tbody> + <row> + <entry>NetBIOS name:</entry><entry>SERV1</entry> + </row> + <row> + <entry>Windows 200x/NT domain name:</entry><entry>&example.workgroup;</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> +First, you must edit your &smb.conf; file to tell Samba it should now use domain security. +</para> + +<para> + Change (or add) your + <smbconfoption name="security"/> line in the [global] section +of your &smb.conf; to read: +</para> + +<para> +<smbconfblock> +<smbconfoption name="security">domain</smbconfoption> +</smbconfblock> +</para> + +<para> +Next change the <smbconfoption name="workgroup"/> line in the <smbconfsection name="[global]"/> +section to read: +</para> + +<para> +<smbconfblock> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +</smbconfblock> +</para> + +<para> +This is the name of the domain we are joining. +</para> + +<para> +You must also have the parameter <smbconfoption name="encrypt passwords"/> +set to <constant>yes</constant> in order for your users to authenticate to the NT PDC. +This is the default setting if this parameter is not specified. There is no need to specify this +parameter, but if it is specified in the &smb.conf; file, it must be set to <constant>Yes</constant>. +</para> + +<para> +Finally, add (or modify) a <smbconfoption name="password server"/> line in the [global] +section to read: +</para> + +<para> +<smbconfblock> +<smbconfoption name="password server">DOMPDC DOMBDC1 DOMBDC2</smbconfoption> +</smbconfblock> +</para> + +<para> +These are the primary and backup Domain Controllers Samba +will attempt to contact in order to authenticate users. Samba will +try to contact each of these servers in order, so you may want to +rearrange this list in order to spread out the authentication load +among Domain Controllers. +</para> + +<para> +Alternately, if you want smbd to automatically determine +the list of Domain Controllers to use for authentication, you may +set this line to be: +</para> + +<para> +<smbconfblock> +<smbconfoption name="password server">*</smbconfoption> +</smbconfblock> +</para> + +<para> +This method allows Samba to use exactly the same mechanism that NT does. The +method either uses broadcast-based name resolution, performs a WINS database +lookup in order to find a Domain Controller against which to authenticate, +or locates the Domain Controller using DNS name resolution. +</para> + +<para> +To join the domain, run this command: +</para> + +<para> +<screen> +&rootprompt;<userinput>net join -S DOMPDC -U<replaceable>Administrator%password</replaceable></userinput> +</screen> +</para> + +<para> +If the <option>-S DOMPDC</option> argument is not given, the domain name will be obtained from &smb.conf;. +</para> + +<para> +The machine is joining the domain DOM, and the PDC for that domain (the only machine +that has write access to the domain SAM database) is DOMPDC, therefore use the <option>-S</option> +option. The <replaceable>Administrator%password</replaceable> is the login name and +password for an account that has the necessary privilege to add machines to the +domain. If this is successful, you will see the message in your terminal window the +text shown below. Where the older NT4 style domain architecture is used: +<screen> +<computeroutput>Joined domain DOM.</computeroutput> +</screen> +</para> + +<para> +Where Active Directory is used: +<screen> +<computeroutput>Joined SERV1 to realm MYREALM.</computeroutput> +</screen> +</para> + +<para> +Refer to the <command>net</command> man page for further information. +</para> + +<para> +This process joins the server to the domain without having to create the machine +trust account on the PDC beforehand. +</para> + +<para> +This command goes through the machine account password change protocol, then writes +the new (random) machine account password for this Samba server into a file in the +same directory in which a smbpasswd file would be normally stored: +<screen> +<filename>/usr/local/samba/private/secrets.tdb</filename> +or +<filename>/etc/samba/secrets.tdb</filename>. +</screen> +</para> + +<para> +This file is created and owned by root and is not readable by any other user. It is +the key to the Domain-level security for your system, and should be treated as carefully +as a shadow password file. +</para> + +<para> +Finally, restart your Samba daemons and get ready for clients to begin using domain +security. The way you can restart your Samba daemons depends on your distribution, +but in most cases the following will suffice: +<screen> +&rootprompt;/etc/init.d/samba restart +</screen> +</para> + +</sect2> + +<sect2> +<title>Why Is This Better Than <parameter>security = server</parameter>?</title> + +<para> +Currently, domain security in Samba does not free you from +having to create local UNIX users to represent the users attaching +to your server. This means that if Domain user <constant>DOM\fred +</constant> attaches to your Domain Security Samba server, there needs +to be a local UNIX user fred to represent that user in the UNIX +file system. This is similar to the older Samba security mode +<smbconfoption name="security">server</smbconfoption>, +where Samba would pass through the authentication request to a Windows +NT server in the same way as a Windows 95 or Windows 98 server would. +</para> + +<para> +Please refer to <link linkend="winbind">Winbind: Use of Domain Accounts</link> chapter, for information on a system +to automatically assign UNIX UIDs and GIDs to Windows NT Domain users and groups. +</para> + +<para> +The advantage to Domain-level security is that the +authentication in Domain-level security is passed down the authenticated +RPC channel in exactly the same way that an NT server would do it. This +means Samba servers now participate in domain trust relationships in +exactly the same way NT servers do (i.e., you can add Samba servers into +a resource domain and have the authentication passed on from a resource +domain PDC to an account domain PDC). +</para> + +<para> +In addition, with <smbconfoption name="security">server</smbconfoption>, 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 <smbconfoption name="security">domain</smbconfoption>, +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. +</para> + +<para> +And finally, acting in the same manner as an NT server +authenticating to a PDC means that as part of the authentication +reply, the Samba server gets the user identification information such +as the user SID, the list of NT groups the user belongs to, and so on. +</para> + +<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 +url="http://www.linuxworld.com/linuxworld/lw-1998-10/lw-10-samba.html"/> +<emphasis>Doing the NIS/NT Samba</emphasis>. +</para> +</note> + +</sect2> +</sect1> + +<sect1 id="ads-member"> +<title>Samba ADS Domain Membership</title> + +<para> +<indexterm significance="preferred"><primary>Active Directory</primary></indexterm> +<indexterm significance="preferred"><primary>ADS</primary><see>Active Directory</see></indexterm> +<indexterm><primary>KDC</primary></indexterm> +<indexterm><primary>Kerberos</primary></indexterm> +This is a rough guide to setting up Samba-3 with Kerberos authentication against a +Windows 200x KDC. A familiarity with Kerberos is assumed. +</para> + +<sect2> +<title>Configure &smb.conf;</title> + +<para> +You must use at least the following three options in &smb.conf;: +</para> + +<para><smbconfblock> +<smbconfoption name="realm">your.kerberos.REALM</smbconfoption> +<smbconfoption name="security">ADS</smbconfoption> +<smbconfcomment>The following parameter need only be specified if present.</smbconfcomment> +<smbconfcomment>The default setting is not present is Yes.</smbconfcomment> +<smbconfoption name="encrypt passwords">yes</smbconfoption> +</smbconfblock></para> + +<para> +In case samba cannot correctly identify the appropriate ADS server using the realm name, use the +<smbconfoption name="password server"/> option in &smb.conf;: +<smbconfblock> +<smbconfoption name="password server">your.kerberos.server</smbconfoption> +</smbconfblock> +</para> + +<note><para> +You do <emphasis>not</emphasis> need a smbpasswd file, and older clients will be authenticated as +if <smbconfoption name="security">domain</smbconfoption>, although it will not do any harm and +allows you to have local users not in the domain. +</para></note> + +</sect2> + +<sect2> +<title>Configure <filename>/etc/krb5.conf</filename></title> + +<para> +<indexterm><primary>/etc/krb5.conf</primary></indexterm> +<indexterm><primary>Kerberos</primary><secondary>/etc/krb5.conf</secondary></indexterm> +With both MIT and Heimdal Kerberos, it is unnecessary to configure the +<filename>/etc/krb5.conf</filename>, and it may be detrimental. +</para> + +<para> +Microsoft Active Directory servers automatically create SRV records in the DNS zone +<parameter>_kerberos.REALM.NAME</parameter> for each KDC in the realm. This is part +of the installation and configuration process used to create an Active Directory Domain. +</para> + +<para> +MIT's, as well as Heimdal's, recent KRB5 libraries default to checking for SRV records, so they will +automatically find the KDCs. In addition, <filename>krb5.conf</filename> only allows specifying +a single KDC, even there if there may be more than one. Using the DNS lookup allows the KRB5 +libraries to use whichever KDCs are available. +</para> + +<para> +When manually configuring <filename>krb5.conf</filename>, the minimal configuration is: +</para> + +<para> + <smbfile name="krb5.conf"> + <programlisting> +[libdefaults] + default_realm = YOUR.KERBEROS.REALM + +[realms] + YOUR.KERBEROS.REALM = { + kdc = your.kerberos.server + } + +[domain_realms] + .kerberos.server = YOUR.KERBEROS.REALM +</programlisting></smbfile></para> + +<para> +When using Heimdal versions before 0.6 use the following configuration settings: +<screen> +[libdefaults] + default_realm = YOUR.KERBEROS.REALM + default_etypes = des-cbc-crc des-cbc-md5 + default_etypes_des = des-cbc-crc des-cbc-md5 + +[realms] + YOUR.KERBEROS.REALM = { + kdc = your.kerberos.server + } + +[domain_realms] + .kerberos.server = YOUR.KERBEROS.REALM +</screen> +</para> + +<para> +<indexterm><primary>kinit</primary></indexterm> +Test your config by doing a <userinput>kinit +<replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput> and +making sure that your password is accepted by the Win2000 KDC. +</para> + +<para> +With Heimdal versions earlier than 0.6.x you only can use newly created accounts +in ADS or accounts that have had the password changed once after migration, or +in case of <constant>Administrator</constant> after installation. At the +moment, a Windows 2003 KDC can only be used with a Heimdal releases later than 0.6 +(and no default etypes in krb5.conf). Unfortunately this whole area is still +in a state of flux. +</para> + +<note><para> +The realm must be in uppercase or you will get <quote><errorname>Cannot find KDC for +requested realm while getting initial credentials</errorname></quote> error (Kerberos +is case-sensitive!). +</para></note> + +<note><para> +Time between the two servers must be synchronized. You will get a +<quote><errorname>kinit(v5): Clock skew too great while getting initial credentials</errorname></quote> +if the time difference is more than five minutes. +</para></note> + +<para> +Clock skew limits are configurable in the Kerberos protocols. The default setting is +five minutes. +</para> + +<para> +You also must ensure that you can do a reverse DNS lookup on the IP +address of your KDC. Also, the name that this reverse lookup maps to +must either be the NetBIOS name of the KDC (i.e., the hostname with no +domain attached) or it can alternately be the NetBIOS name followed by the realm. +</para> + +<para> +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 do not get this correct then you will get a +<errorname>local error</errorname> when you try to join the realm. +</para> + +<para> +If all you want is Kerberos support in &smbclient; then you can skip +directly to <link linkend="ads-test-smbclient">Testing with &smbclient;</link> now. +<link linkend="ads-create-machine-account">Create the Computer Account</link> and +<link linkend="ads-test-server">Testing Server Setup</link> +are needed only if you want Kerberos support for &smbd; and &winbindd;. +</para> + +</sect2> + +<sect2 id="ads-create-machine-account"> +<title>Create the Computer Account</title> + +<para> +As a user who has write permission on the Samba private directory (usually root), run: +<screen> +&rootprompt; <userinput>net ads join -U Administrator%password</userinput> +</screen> +</para> + +<para> +When making a Windows client a member of an ADS domain within a complex organization, you +may want to create the machine account within a particular organizational unit. Samba-3 permits +this to be done using the following syntax: +<screen> +&rootprompt; <userinput>kinit Administrator@your.kerberos.REALM</userinput> +&rootprompt; <userinput>net ads join "organizational_unit"</userinput> +</screen> +</para> + +<para> +For example, you may want to create the machine account in a container called <quote>Servers</quote> +under the organizational directory <quote>Computers\BusinessUnit\Department</quote> like this: +<screen> +&rootprompt; <userinput>net ads join "Computers\BusinessUnit\Department\Servers"</userinput> +</screen> +</para> + +<?latex \newpage ?> + +<sect3> +<title>Possible Errors</title> + +<para> +<variablelist> + <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 libraries and headers files are installed. + </para></listitem></varlistentry> + + <varlistentry><term><errorname>net ads 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 + to the domain. </para></listitem></varlistentry> + + <varlistentry><term>Unsupported encryption/or checksum types</term> + <listitem><para> + Make sure that the <filename>/etc/krb5.conf</filename> is correctly configured + for the type and version of Kerberos installed on the system. + </para></listitem></varlistentry> +</variablelist> +</para> + +</sect3> + +</sect2> + +<sect2 id="ads-test-server"> +<title>Testing Server Setup</title> + +<para> +If the join was successful, you will see a new computer account with the +NetBIOS name of your Samba server in Active Directory (in the <quote>Computers</quote> +folder under Users and Computers. +</para> + +<para> +On a Windows 2000 client, try <userinput>net use * \\server\share</userinput>. You should +be logged in with Kerberos without needing to know a password. If this fails then run +<userinput>klist tickets</userinput>. Did you get a ticket for the server? Does it have +an encryption type of DES-CBC-MD5? +</para> + +<note><para> +Samba can use both DES-CBC-MD5 encryption as well as ARCFOUR-HMAC-MD5 encoding. +</para></note> + +</sect2> + +<sect2 id="ads-test-smbclient"> +<title>Testing with &smbclient;</title> + + +<para> +<indexterm><primary>smbclient</primary></indexterm> +On your Samba server try to login to a Win2000 server or your Samba +server using &smbclient; and Kerberos. Use &smbclient; as usual, but +specify the <option>-k</option> option to choose Kerberos authentication. +</para> + +</sect2> + +<sect2> +<title>Notes</title> + +<para> +You must change administrator password at least once after DC +install, to create the right encryption types. +</para> + +<para> +Windows 200x does not seem to create the <parameter>_kerberos._udp</parameter> and <parameter>_ldap._tcp</parameter> in +the default DNS setup. Perhaps this will be fixed later in service packs. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Sharing User ID Mappings between Samba Domain Members</title> + +<para> +Samba maps UNIX users and groups (identified by UIDs and GIDs) to Windows users and groups (identified by SIDs). +These mappings are done by the <parameter>idmap</parameter> subsystem of Samba. +</para> + +<para> +In some cases it is useful to share these mappings between Samba Domain Members, +so <emphasis>name->id</emphasis> mapping is identical on all machines. +This may be needed in particular when sharing files over both CIFS and NFS. +</para> + +<para>To use the <emphasis>LDAP</emphasis> <parameter>ldap idmap suffix</parameter>, set:</para> + +<smbconfblock> +<smbconfoption name="ldap idmap suffix">ou=Idmap,dc=quenya,dc=org</smbconfoption> +</smbconfblock> + +<para>See the &smb.conf; man page entry for the <smbconfoption name="ldap idmap suffix"></smbconfoption> +parameter for further information.</para> + +<para> +Do not forget to specify also the <smbconfoption name="ldap admin dn"/> +and to make certain to set the LDAP administrative password into the <filename>secrets.tdb</filename> using: +<screen> +&rootprompt; smbpasswd -w ldap-admin-password +</screen></para> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +In the process of adding/deleting/re-adding Domain Member machine accounts, there are +many traps for the unwary player and many <quote>little</quote> things that can go wrong. +It is particularly interesting how often subscribers on the Samba mailing list have concluded +after repeated failed attempts to add a machine account that it is necessary to <quote>re-install</quote> +MS Windows on the machine. In truth, it is seldom necessary to reinstall because of this type +of problem. The real solution is often quite simple and with an understanding of how MS Windows +networking functions, it is easy to overcome. +</para> + +<sect2> +<title>Cannot Add Machine Back to Domain</title> + +<para> +<quote>A Windows workstation was re-installed. The original domain machine +account was deleted and added immediately. The workstation will not join the domain if I use +the same machine name. Attempts to add the machine fail with a message that the machine already +exists on the network &smbmdash; I know it does not. Why is this failing?</quote> +</para> + +<para> +The original name is still in the NetBIOS name cache and must expire after machine account +deletion before adding that same name as a Domain Member again. The best advice is to delete +the old account and then add the machine with a new name. +</para> + +</sect2> + +<sect2> +<title>Adding Machine to Domain Fails</title> + +<para> +<quote>Adding a Windows 200x or XP Professional machine to the Samba PDC Domain fails with a +message that, <errorname>`The machine could not be added at this time, there is a network problem. +Please try again later.'</errorname> Why?</quote> +</para> + +<para> +You should check that there is an <smbconfoption name="add machine script"/> 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 its operation. Increase the <smbconfoption name="log level"></smbconfoption> +in the &smb.conf; file to level 10, then try to rejoin the domain. Check the logs to see which +operation is failing. +</para> + +<para> +Possible causes include: +</para> + +<itemizedlist> + <listitem><para> + The script does not actually exist, or could not be located in the path specified. + </para> + + <para> + <emphasis>Corrective action:</emphasis> Fix it. Make sure when run manually + that the script will add both the UNIX system account and the Samba SAM account. + </para></listitem> + + <listitem><para> + The machine could not be added to the UNIX system accounts file <filename>/etc/passwd</filename>. + </para> + + <para> + <emphasis>Corrective action:</emphasis> Check that the machine name is a legal UNIX + system account name. If the UNIX utility <command>useradd</command> is called, + then make sure that the machine name you are trying to add can be added using this + tool. <command>Useradd</command> on some systems will not allow any upper case characters + nor will it allow spaces in the name. + </para></listitem> +</itemizedlist> + +<para> +The <smbconfoption name="add machine script"/> does not create the +machine account in the Samba backend database, it is there only to create a UNIX system +account to which the Samba backend database account can be mapped. +</para> + +</sect2> + +<sect2> + <title>I Can't Join a Windows 2003 PDC</title> + + <para>Windows 2003 requires SMB signing. Client side SMB signing has been implemented in Samba-3.0. + Set <smbconfoption name="client use spnego">yes</smbconfoption> when communicating + with a Windows 2003 server.</para> +</sect2> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-FastStart.xml b/docs/Samba3-HOWTO/TOSHARG-FastStart.xml new file mode 100644 index 0000000000..4469bc88ef --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-FastStart.xml @@ -0,0 +1,1278 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="FastStart"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>Fast Start: Cure for Impatience</title> + +<para> +When we first asked for suggestions for inclusion in the Samba HOWTO documentation, +someone wrote asking for example configurations &smbmdash; and lots of them. That is remarkably +difficult to do, without losing a lot of value that can be derived from presenting +many extracts from working systems. That is what the rest of this document does. +It does so with extensive descriptions of the configuration possibilities within the +context of the chapter that covers it. We hope that this chapter is the medicine +that has been requested. +</para> + +<para> +The information in this chapter is very sparse compared with the book <quote>Samba-3 by Example</quote> +that was written after the original version of this book was nearly complete. Samba-3 by Example +was the result of feedback from reviewers during the final copy editing of the first edition. It +was interesting to see that reader feedback mirrored that given be the original reviewers. +In any case, a month and a half was spent in doing basic research to better understand what +new as well as experienced network administrators would best benefit from. The book Samba-3 by Example +is the result of that research. What is presented in the few pages of this book is covered +far more comprehensively in the second edition of Samba-3 by Example. The second edition +of both books will be released at the same time. +</para> + +<para> +So in summary, the book <quote>The Official Samba-3 HOWTO & Reference Guide</quote> is intended +as the equivalent of a auto mechanics' repair guide. The book <quote>Samba-3 by Example</quote> is the +equivalent of the drivers guide that explains how to drive the car. If you want complete network +configuration examples go to <quote>Samba-3 by Example</quote>. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +Samba needs very little configuration to create a basic working system. +In this chapter we progress from the simple to the complex, for each providing +all steps and configuration file changes needed to make each work. Please note +that a comprehensively configured system will likely employ additional smart +features. These additional features are covered in the remainder of this document. +</para> + +<para> +The examples used here have been obtained from a number of people who made +requests for example configurations. All identities have been obscured to protect +the guilty and any resemblance to unreal non-existent sites is deliberate. +</para> + +</sect1> + +<sect1> +<title>Description of Example Sites</title> + +<para> +In the first set of configuration examples we consider the case of exceptionally simple +system requirements. There is a real temptation to make something that should require +little effort much too complex. +</para> + +<para> +<link linkend="anon-ro"></link> documents the type of server that might be sufficient to serve CD-ROM +images, or reference document files for network client use. This configuration is also discussed in +<link linkend="StandAloneServer"></link>, <link linkend="RefDocServer"></link>. +The purpose for this configuration is to provide a shared volume that is read-only that anyone, even guests, can access. +</para> + +<para> +The second example shows a minimal configuration for a print server that anyone can print +to as long as they have the correct printer drivers installed on their computer. This is a +mirror of the system described in <link linkend="StandAloneServer"></link>, <link linkend="SimplePrintServer"></link>. +</para> + +<para> +The next example is of a secure office file and print server that will be accessible only +to users who have an account on the system. This server is meant to closely resemble a +Workgroup file and print server, but has to be more secure than an anonymous access machine. +This type of system will typically suit the needs of a small office. The server provides no +network logon facilities, offers no Domain Control; instead it is just a network +attached storage (NAS) device and a print server. +</para> + +<para> +Finally, we start looking at more complex systems that will either integrate into existing +Microsoft Windows networks, or replace them entirely. The examples provided cover domain +member servers as well as Samba Domain Control (PDC/BDC) and finally describes in detail +a large distributed network with branch offices in remote locations. +</para> + +</sect1> + +<sect1> +<title>Worked Examples</title> + +<para> +The configuration examples are designed to cover everything necessary to get Samba +running. They do not cover basic operating system platform configuration, which is +clearly beyond the scope of this text. +</para> + +<para> +It is also assumed that Samba has been correctly installed, either by way of installation +of the packages that are provided by the operating system vendor, or through other means. +</para> + + <sect2> + <title>Stand-alone Server</title> + + <para> + <indexterm><primary>Server Type</primary><secondary>Stand-alone</secondary></indexterm> + A Stand-alone Server implies no more than the fact that it is not a Domain Controller + and it does not participate in Domain Control. It can be a simple workgroup-like + server, or it may be a complex server that is a member of a domain security context. + </para> + + <sect3 id="anon-ro"> + <title>Anonymous Read-Only Document Server</title> + + <para> + <indexterm><primary>read only</primary><secondary>server</secondary></indexterm> + The purpose of this type of server is to make available to any user + any documents or files that are placed on the shared resource. The + shared resource could be a CD-ROM drive, a CD-ROM image, or a file + storage area. + </para> + + <para> + As the examples are developed, every attempt is made to progress the + system toward greater capability, just as one might expect would happen + in a real business office as that office grows in size and its needs + change. + </para> + + <para>The configuration file is:</para> + + <para><smbconfexample id="anon-example"> + <title>Anonymous Read-Only Server Configuration</title> + <smbconfcomment>Global parameters</smbconfcomment> + <smbconfsection name="[global]"/> + <smbconfoption name="workgroup">MIDEARTH</smbconfoption> + <smbconfoption name="netbios name">HOBBIT</smbconfoption> + <smbconfoption name="security">share</smbconfoption> + + <smbconfsection name="[data]"/> + <smbconfoption name="comment">Data</smbconfoption> + <smbconfoption name="path">/export</smbconfoption> + <smbconfoption name="read only">Yes</smbconfoption> + <smbconfoption name="guest ok">Yes</smbconfoption> + </smbconfexample> + </para> + + <itemizedlist> + <listitem><para> + The file system share point will be <filename>/export</filename>. + </para></listitem> + + <listitem><para> + All files will be owned by a user called Jack Baumbach. + Jack's login name will be <emphasis>jackb</emphasis>. His password will be + <emphasis>m0r3pa1n</emphasis> &smbmdash; of course, that's just the example we are + using; do not use this in a production environment because + all readers of this document will know it. + </para></listitem> + </itemizedlist> + + <procedure> + <title>Installation Procedure &smbmdash; Read-Only Server</title> + <step><para> + Add user to system (with creation of the users' home directory): +<screen> +&rootprompt;<userinput>useradd -c "Jack Baumbach" -m -g users -p m0r3pa1n jackb</userinput> +</screen> + </para></step> + + <step><para> + Create directory, and set permissions and ownership: +<screen> +&rootprompt;<userinput>mkdir /export</userinput> +&rootprompt;<userinput>chmod u+rwx,g+rx,o+rx /export</userinput> +&rootprompt;<userinput>chown jackb.users /export</userinput> +</screen> + </para></step> + + <step><para> + Copy the files that should be shared to the <filename>/export</filename> + directory. + </para></step> + + <step><para> + Install the Samba configuration file (<filename>/etc/samba/smb.conf</filename>) + as shown. + </para></step> + + <step><para> + Test the configuration file: +<screen> +&rootprompt;<userinput>testparm</userinput> +</screen> + Note any error messages that might be produced. Proceed only if error-free output has been + obtained. An example of the output with the following file will list the file. +<screen> +Load smb config files from /etc/samba/smb.conf +Processing section "[data]" +Loaded services file OK. +Server role: ROLE_STANDALONE +Press enter to see a dump of your service definitions +<userinput>[Press enter]</userinput> + +# Global parameters +[global] + workgroup = MIDEARTH + netbios name = HOBBIT + security = share + +[data] + comment = Data + path = /export + read only = Yes + guest only = Yes +</screen> + </para></step> + + <step><para> + Start Samba using the method applicable to your operating system + platform. + </para></step> + + <step><para> + Configure your Microsoft Windows client for workgroup <emphasis>MIDEARTH</emphasis>, + set the machine name to ROBBINS, reboot, wait a few (2 - 5) minutes, + then open Windows Explorer and visit the network neighborhood. + The machine HOBBIT should be visible. When you click this machine + icon, it should open up to reveal the <emphasis>data</emphasis> share. After + clicking the share it, should open up to reveal the files previously + placed in the <filename>/export</filename> directory. + </para></step> + </procedure> + + <para> + The information above (following # Global parameters) provides the complete + contents of the <filename>/etc/samba/smb.conf</filename> file. + </para> + + </sect3> + + <sect3> + <title>Anonymous Read-Write Document Server</title> + + <para> + <indexterm><primary>anonymous</primary><secondary>read-write server</secondary></indexterm> + We should view this configuration as a progression from the previous example. + The difference is that shared access is now forced to the user identity of jackb + and to the primary group jackb belongs to. One other refinement we can make is to + add the user <emphasis>jackb</emphasis> to the <filename>smbpasswd</filename> file. + To do this execute: +<screen> +&rootprompt;<userinput>smbpasswd -a jackb</userinput> +New SMB password: <userinput>m0r3pa1n</userinput> +Retype new SMB password: <userinput>m0r3pa1n</userinput> +Added user jackb. +</screen> + Addition of this user to the <filename>smbpasswd</filename> file allows all files + to be displayed in the Explorer Properties boxes as belonging to <emphasis>jackb</emphasis> + instead of to <emphasis>User Unknown</emphasis>. + </para> + + <para> + The complete, modified &smb.conf; file is as shown in <link linkend="anon-rw"/>. + </para> + + <para> +<smbconfexample id="anon-rw"><title>Modified Anonymous Read-Write smb.conf</title> +<smbconfcomment>Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">HOBBIT</smbconfoption> +<smbconfoption name="security">SHARE</smbconfoption> + +<smbconfsection name="[data]"/> +<smbconfoption name="comment">Data</smbconfoption> +<smbconfoption name="path">/export</smbconfoption> +<smbconfoption name="force user">jackb</smbconfoption> +<smbconfoption name="force group">users</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +</smbconfexample> + </para> + + </sect3> + + <sect3> + <title>Anonymous Print Server</title> + + <para> + <indexterm><primary>anonymous</primary><secondary>print server</secondary></indexterm> + An anonymous print server serves two purposes: + </para> + + <itemizedlist> + <listitem><para> + It allows printing to all printers from a single location. + </para></listitem> + + <listitem><para> + It reduces network traffic congestion due to many users trying + to access a limited number of printers. + </para></listitem> + </itemizedlist> + + <para> + In the simplest of anonymous print servers, it is common to require the installation + of the correct printer drivers on the Windows workstation. In this case the print + server will be designed to just pass print jobs through to the spooler, and the spooler + should be configured to do raw pass-through to the printer. In other words, the print + spooler should not filter or process the data stream being passed to the printer. + </para> + + <para> + In this configuration it is undesirable to present the Add Printer Wizard and we do + not want to have automatic driver download, so we will disable it in the following + configuration. <link linkend="anon-print"></link> is the resulting &smb.conf; file. + </para> + + <para> +<smbconfexample id="anon-print"><title>Anonymous Print Server smb.conf</title> +<smbconfcomment>Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">LUTHIEN</smbconfoption> +<smbconfoption name="security">share</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> +<smbconfoption name="disable spoolss">Yes</smbconfoption> +<smbconfoption name="show add printer wizard">No</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="printable">Yes</smbconfoption> +<smbconfoption name="use client driver">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> +</smbconfexample> + </para> + + <para> + The above configuration is not ideal. It uses no smart features, and it deliberately + presents a less than elegant solution. But it is basic, and it does print. + </para> + + <note><para> + Windows users will need to install a local printer and then change the print + to device after installation of the drivers. The print to device can then be set to + the network printer on this machine. + </para></note> + + <para> + Make sure that the directory <filename>/var/spool/samba</filename> is capable of being used + as intended. The following steps must be taken to achieve this: + </para> + + <itemizedlist> + <listitem><para> + The directory must be owned by the superuser (root) user and group: +<screen> +&rootprompt;<userinput>chown root.root /var/spool/samba</userinput> +</screen> + </para></listitem> + + <listitem><para> + Directory permissions should be set for public read-write with the + sticky-bit set as shown: +<screen> +&rootprompt;<userinput>chmod a+trw TX /var/spool/samba</userinput> +</screen> + The purpose of setting the sticky bit is to prevent who does not own the temporary print file + from being able to take control of it with the potential for devious mis-use. + </para></listitem> + </itemizedlist> + + + <note><para> + <indexterm><primary>MIME</primary><secondary>raw</secondary></indexterm> + <indexterm><primary>raw printing</primary></indexterm> + On CUPS enabled systems there is a facility to pass raw data directly to the printer without + intermediate processing via CUPS print filters. Where use of this mode of operation is desired + it is necessary to configure a raw printing device. It is also necessary to enable the raw mime + handler in the <filename>/etc/mime.conv</filename> and <filename>/etc/mime.types</filename> + files. Refer to <link linkend="cups-raw"></link>. + </para></note> + + </sect3> + + <sect3> + + <title>Secure Read-Write File and Print Server</title> + + <para> + We progress now from simple systems to a server that is slightly more complex. + </para> + + <para> + Our new server will require a public data storage area in which only authenticated + users (i.e., those with a local account) can store files, as well as a home directory. + There will be one printer that should be available for everyone to use. + </para> + + <para> + In this hypothetical environment (no espionage was conducted to obtain this data), + the site is demanding a simple environment that is <emphasis>secure enough</emphasis> + but not too difficult to use. + </para> + + <para> + Site users will be: Jack Baumbach, Mary Orville and Amed Sehkah. Each will have + a password (not shown in further examples). Mary will be the printer administrator and will + own all files in the public share. + </para> + + <para> + This configuration will be based on <emphasis>User Level Security</emphasis> that + is the default, and for which the default is to store Microsoft Windows-compatible + encrypted passwords in a file called <filename>/etc/samba/smbpasswd</filename>. + The default &smb.conf; entry that makes this happen is: + <smbconfoption name="passdb backend">smbpasswd, guest</smbconfoption>. Since this is the default + it is not necessary to enter it into the configuration file. Note that guest backend is + added to the list of active passdb backends not matter was it specified directly in Samba configuration + file or not. + </para> + + + <procedure> + <title>Installing the Secure Office Server</title> + <step><para> + <indexterm><primary>office server</primary></indexterm> + Add all users to the Operating System: +<screen> +&rootprompt;<userinput>useradd -c "Jack Baumbach" -m -g users -p m0r3pa1n jackb</userinput> +&rootprompt;<userinput>useradd -c "Mary Orville" -m -g users -p secret maryo</userinput> +&rootprompt;<userinput>useradd -c "Amed Sehkah" -m -g users -p secret ameds</userinput> +</screen> + </para></step> + + <step><para> + Configure the Samba &smb.conf; file as shown in <link linkend="OfficeServer"/>. +<smbconfexample id="OfficeServer"> +<title>Secure Office Server smb.conf</title> +<smbconfcomment>Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">OLORIN</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> +<smbconfoption name="disable spoolss">Yes</smbconfoption> +<smbconfoption name="show add printer wizard">No</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> + +<smbconfsection name="[homes]"/> +<smbconfoption name="comment">Home Directories</smbconfoption> +<smbconfoption name="valid users">%S</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + +<smbconfsection name="[public]"/> +<smbconfoption name="comment">Data</smbconfoption> +<smbconfoption name="path">/export</smbconfoption> +<smbconfoption name="force user">maryo</smbconfoption> +<smbconfoption name="force group">users</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="printer admin">root, maryo</smbconfoption> +<smbconfoption name="create mask">0600</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="printable">Yes</smbconfoption> +<smbconfoption name="use client driver">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + </smbconfexample> + </para></step> + + <step><para> + Initialize the Microsoft Windows password database with the new users: +<screen> +&rootprompt;<userinput>smbpasswd -a root</userinput> +New SMB password: <userinput>bigsecret</userinput> +Reenter smb password: <userinput>bigsecret</userinput> +Added user root. + +&rootprompt;<userinput>smbpasswd -a jackb</userinput> +New SMB password: <userinput>m0r3pa1n</userinput> +Retype new SMB password: <userinput>m0r3pa1n</userinput> +Added user jackb. + +&rootprompt;<userinput>smbpasswd -a maryo</userinput> +New SMB password: <userinput>secret</userinput> +Reenter smb password: <userinput>secret</userinput> +Added user maryo. + +&rootprompt;<userinput>smbpasswd -a ameds</userinput> +New SMB password: <userinput>mysecret</userinput> +Reenter smb password: <userinput>mysecret</userinput> +Added user ameds. +</screen> + </para></step> + + <step><para> + Install printer using the CUPS Web interface. Make certain that all + printers that will be shared with Microsoft Windows clients are installed + as raw printing devices. + </para></step> + + <step><para> + Start Samba using the operating system administrative interface. + Alternately, this can be done manually by executing: + <indexterm><primary>smbd</primary></indexterm> + <indexterm><primary>nmbd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm> + <indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm> +<screen> +&rootprompt;<userinput> nmbd; smbd;</userinput> +</screen> + Both applications automatically will execute as daemons. Those who are paranoid about + maintaining control can add the <constant>-D</constant> flag to coerce them to start + up in daemon mode. + </para></step> + + <step><para> + Configure the <filename>/export</filename> directory: +<screen> +&rootprompt;<userinput>mkdir /export</userinput> +&rootprompt;<userinput>chown maryo.users /export</userinput> +&rootprompt;<userinput>chmod u=rwx,g=rwx,o-rwx /export</userinput> +</screen> + </para></step> + + <step><para> + Check that Samba is running correctly: +<screen> +&rootprompt;<userinput>smbclient -L localhost -U%</userinput> +Domain=[MIDEARTH] OS=[UNIX] Server=[Samba-3.0.20] + +Sharename Type Comment +--------- ---- ------- +public Disk Data +IPC$ IPC IPC Service (Samba-3.0.20) +ADMIN$ IPC IPC Service (Samba-3.0.20) +hplj4 Printer hplj4 + +Server Comment +--------- ------- +OLORIN Samba-3.0.20 + +Workgroup Master +--------- ------- +MIDEARTH OLORIN +</screen> + </para></step> + + <step><para> + Connect to OLORIN as maryo: +<screen> +&rootprompt;<userinput>smbclient //olorin/maryo -Umaryo%secret</userinput> +OS=[UNIX] Server=[Samba-3.0.20] +smb: \> <userinput>dir</userinput> +. D 0 Sat Jun 21 10:58:16 2003 +.. D 0 Sat Jun 21 10:54:32 2003 +Documents D 0 Fri Apr 25 13:23:58 2003 +DOCWORK D 0 Sat Jun 14 15:40:34 2003 +OpenOffice.org D 0 Fri Apr 25 13:55:16 2003 +.bashrc H 1286 Fri Apr 25 13:23:58 2003 +.netscape6 DH 0 Fri Apr 25 13:55:13 2003 +.mozilla DH 0 Wed Mar 5 11:50:50 2003 +.kermrc H 164 Fri Apr 25 13:23:58 2003 +.acrobat DH 0 Fri Apr 25 15:41:02 2003 + + 55817 blocks of size 524288. 34725 blocks available +smb: \> <userinput>q</userinput> +</screen> + </para></step> + </procedure> + + <para> + By now you should be getting the hang of configuration basics. Clearly, it is time to + explore slightly more complex examples. For the remainder of this chapter we will abbreviate + instructions since there are previous examples. + </para> + + </sect3> + + </sect2> + + <sect2> + <title>Domain Member Server</title> + + + <para> + <indexterm><primary>Server Type</primary><secondary>Domain Member</secondary></indexterm> + In this instance we will consider the simplest server configuration we can get away with + to make an accounting department happy. Let's be warned, the users are accountants and they + do have some nasty demands. There is a budget for only one server for this department. + </para> + + <para> + The network is managed by an internal Information Services Group (ISG), to which we belong. + Internal politics are typical of a medium-sized organization; Human Resources is of the + opinion that they run the ISG because they are always adding and disabling users. Also, + departmental managers have to fight tooth and nail to gain basic network resources access for + their staff. Accounting is different though, they get exactly what they want. So this should + set the scene. + </para> + + <para> + We will use the users from the last example. The accounting department + has a general printer that all departmental users may. There is also a check printer + that may be used only by the person who has authority to print checks. The Chief Financial + Officer (CFO) wants that printer to be completely restricted and for it to be located in the + private storage area in her office. It therefore must be a network printer. + </para> + + <para> + Accounting department uses an accounting application called <emphasis>SpytFull</emphasis> + that must be run from a central application server. The software is licensed to run only off + one server, there are no workstation components, and it is run off a mapped share. The data + store is in a UNIX-based SQL backend. The UNIX gurus look after that, so is not our + problem. + </para> + + <para> + The accounting department manager (maryo) wants a general filing system as well as a separate + file storage area for form letters (nastygrams). The form letter area should be read-only to + all accounting staff except the manager. The general filing system has to have a structured + layout with a general area for all staff to store general documents, as well as a separate + file area for each member of her team that is private to that person, but she wants full + access to all areas. Users must have a private home share for personal work-related files + and for materials not related to departmental operations. + </para> + + <sect3> + <title>Example Configuration</title> + + <para> + The server <emphasis>valinor</emphasis> will be a member server of the company domain. + Accounting will have only a local server. User accounts will be on the Domain Controllers + as will desktop profiles and all network policy files. + </para> + + <procedure> + <step><para> + Do not add users to the UNIX/Linux server; all of this will run off the + central domain. + </para></step> + + <step><para> + Configure &smb.conf; according to <link linkend="fast-member-server"/> + and <link linkend="fast-memberserver-shares"></link>. + </para> + + <para> + <smbconfexample id="fast-member-server"> + <title>Member server smb.conf (globals)</title> +<smbconfcomment>Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">VALINOR</smbconfoption> +<smbconfoption name="security">DOMAIN</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> +<smbconfoption name="disable spoolss">Yes</smbconfoption> +<smbconfoption name="show add printer wizard">No</smbconfoption> +<smbconfoption name="idmap uid">15000-20000</smbconfoption> +<smbconfoption name="idmap gid">15000-20000</smbconfoption> +<smbconfoption name="winbind use default domain">Yes</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> + </smbconfexample></para> + + <para> + <smbconfexample id="fast-memberserver-shares"> + <title>Member server smb.conf (shares and services)</title> +<smbconfsection name="[homes]"/> +<smbconfoption name="comment">Home Directories</smbconfoption> +<smbconfoption name="valid users">%S</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + +<smbconfsection name="[spytfull]"/> +<smbconfoption name="comment">Accounting Application Only</smbconfoption> +<smbconfoption name="path">/export/spytfull</smbconfoption> +<smbconfoption name="valid users">@Accounts</smbconfoption> +<smbconfoption name="admin users">maryo</smbconfoption> +<smbconfoption name="read only">Yes</smbconfoption> + +<smbconfsection name="[public]"/> +<smbconfoption name="comment">Data</smbconfoption> +<smbconfoption name="path">/export/public</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="printer admin">root, maryo</smbconfoption> +<smbconfoption name="create mask">0600</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="printable">Yes</smbconfoption> +<smbconfoption name="use client driver">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + </smbconfexample> + </para></step> + + + <step><para> +<indexterm><primary>net</primary><secondary>rpc</secondary></indexterm> + Join the domain. Note: Do not start Samba until this step has been completed! +<screen> +&rootprompt;<userinput>net rpc join -Uroot%'bigsecret'</userinput> +Joined domain MIDEARTH. +</screen> + </para></step> + + <step><para> + Make absolutely certain that you disable (shut down) the <command>nscd</command> + daemon on any system on which <command>winbind</command> is configured to run. + </para></step> + + <step><para> + Start Samba following the normal method for your operating system platform. + If you wish to this manually execute as root: + <indexterm><primary>smbd</primary></indexterm> + <indexterm><primary>nmbd</primary></indexterm> + <indexterm><primary>winbindd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm> + <indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm> + <indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm> +<screen> +&rootprompt;<userinput>nmbd; smbd; winbindd;</userinput> +</screen> + </para></step> + + <step><para> + Configure the name service switch control file on your system to resolve user and group names + via winbind. Edit the following lines in <filename>/etc/nsswitch.conf</filename>: +<programlisting> +passwd: files winbind +group: files winbind +hosts: files dns winbind +</programlisting> + </para></step> + + <step><para> + Set the password for <command>wbinfo</command> to use: +<screen> +&rootprompt;<userinput>wbinfo --set-auth-user=root%'bigsecret'</userinput> +</screen> + </para></step> + + <step><para> + Validate that domain user and group credentials can be correctly resolved by executing: +<screen> +&rootprompt;<userinput>wbinfo -u</userinput> +MIDEARTH\maryo +MIDEARTH\jackb +MIDEARTH\ameds +... +MIDEARTH\root + +&rootprompt;<userinput>wbinfo -g</userinput> +MIDEARTH\Domain Users +MIDEARTH\Domain Admins +MIDEARTH\Domain Guests +... +MIDEARTH\Accounts +</screen> + </para></step> + + <step><para> + Check that <command>winbind</command> is working. The following demonstrates correct + username resolution via the <command>getent</command> system utility: +<screen> +&rootprompt;<userinput>getent passwd maryo</userinput> +maryo:x:15000:15003:Mary Orville:/home/MIDEARTH/maryo:/bin/false +</screen> + </para></step> + + <step><para> + A final test that we have this under control might be reassuring: +<screen> +&rootprompt;<userinput>touch /export/a_file</userinput> +&rootprompt;<userinput>chown maryo /export/a_file</userinput> +&rootprompt;<userinput>ls -al /export/a_file</userinput> +... +-rw-r--r-- 1 maryo users 11234 Jun 21 15:32 a_file +... + +&rootprompt;<userinput>rm /export/a_file</userinput> +</screen> + </para></step> + + <step><para> + Configuration is now mostly complete, so this is an opportune time + to configure the directory structure for this site: +<screen> +&rootprompt;<userinput>mkdir -p /export/{spytfull,public}</userinput> +&rootprompt;<userinput>chmod ug=rwxS,o=x /export/{spytfull,public}</userinput> +&rootprompt;<userinput>chown maryo.Accounts /export/{spytfull,public}</userinput> +</screen> + </para></step> + </procedure> + + </sect3> + + </sect2> + + <sect2> + <title>Domain Controller</title> + + + <para> + <indexterm><primary>Server Type</primary><secondary>Domain Controller</secondary></indexterm> + For the remainder of this chapter the focus is on the configuration of Domain Control. + The examples that follow are for two implementation strategies. Remember, our objective is + to create a simple but working solution. The remainder of this book should help to highlight + opportunity for greater functionality and the complexity that goes with it. + </para> + + <para> + A Domain Controller configuration can be achieved with a simple configuration using the new + tdbsam password backend. This type of configuration is good for small + offices, but has limited scalability (cannot be replicated) and performance can be expected + to fall as the size and complexity of the domain increases. + </para> + + <para> + The use of tdbsam is best limited to sites that do not need + more than a primary Domain Controller (PDC). As the size of a domain grows the need + for additional Domain Controllers becomes apparent. Do not attempt to under-resource + a Microsoft Windows network environment; Domain Controllers provide essential + authentication services. The following are symptoms of an under-resourced Domain Control + environment: + </para> + + <itemizedlist> + <listitem><para> + Domain logons intermittently fail. + </para></listitem> + + <listitem><para> + File access on a Domain Member server intermittently fails, giving a permission denied + error message. + </para></listitem> + </itemizedlist> + + <para> + A more scalable Domain Control authentication backend option might use + Microsoft Active Directory, or an LDAP-based backend. Samba-3 provides + for both options as a Domain Member server. As a PDC Samba-3 is not able to provide + an exact alternative to the functionality that is available with Active Directory. + Samba-3 can provide a scalable LDAP-based PDC/BDC solution. + </para> + + <para> + The tdbsam authentication backend provides no facility to replicate + the contents of the database, except by external means. (i.e., there is no self-contained protocol + in Samba-3 for Security Account Manager database [SAM] replication.) + </para> + + <note><para> + If you need more than one Domain Controller, do not use a tdbsam authentication backend. + </para></note> + + <sect3> + <title>Example: Engineering Office</title> + + <para> + The engineering office network server we present here is designed to demonstrate use + of the new tdbsam password backend. The tdbsam + facility is new to Samba-3. It is designed to provide many user and machine account controls + that are possible with Microsoft Windows NT4. It is safe to use this in smaller networks. + </para> + + <procedure> + <step><para> + A working PDC configuration using the tdbsam + password backend can be found in <link linkend="fast-engoffice-global"></link> together with + <link linkend="fast-engoffice-shares"></link>: + </para> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + <smbconfexample id="fast-engoffice-global"> + <title>Engineering Office smb.conf (globals)</title> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">FRODO</smbconfoption> +<smbconfoption name="passdb backend">tdbsam</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> +<smbconfoption name="add user script">/usr/sbin/useradd -m %u</smbconfoption> +<smbconfoption name="delete user script">/usr/sbin/userdel -r %u</smbconfoption> +<smbconfoption name="add group script">/usr/sbin/groupadd %g</smbconfoption> +<smbconfoption name="delete group script">/usr/sbin/groupdel %g</smbconfoption> +<smbconfoption name="add user to group script">/usr/sbin/groupmod -A %u %g</smbconfoption> +<smbconfoption name="delete user from group script">/usr/sbin/groupmod -R %u %g</smbconfoption> +<smbconfoption name="add machine script">/usr/sbin/useradd -s /bin/false -d /var/lib/nobody %u</smbconfoption> +<smbconfcomment>Note: The following specifies the default logon script.</smbconfcomment> +<smbconfcomment>Per user logon scripts can be specified in the user account using pdbedit </smbconfcomment> +<smbconfoption name="logon script">scripts\logon.bat</smbconfoption> +<smbconfcomment>This sets the default profile path. Set per user paths with pdbedit</smbconfcomment> +<smbconfoption name="logon path">\\%L\Profiles\%U</smbconfoption> +<smbconfoption name="logon drive">H:</smbconfoption> +<smbconfoption name="logon home">\\%L\%U</smbconfoption> +<smbconfoption name="domain logons">Yes</smbconfoption> +<smbconfoption name="os level">35</smbconfoption> +<smbconfoption name="preferred master">Yes</smbconfoption> +<smbconfoption name="domain master">Yes</smbconfoption> +<smbconfoption name="idmap uid">15000-20000</smbconfoption> +<smbconfoption name="idmap gid">15000-20000</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> + </smbconfexample> + + <smbconfexample id="fast-engoffice-shares"> + <title>Engineering Office smb.conf (shares and services)</title> +<smbconfsection name="[homes]"/> +<smbconfoption name="comment">Home Directories</smbconfoption> +<smbconfoption name="valid users">%S</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + +<smbconfcomment>Printing auto-share (makes printers available thru CUPS)</smbconfcomment> +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="printer admin">root, maryo</smbconfoption> +<smbconfoption name="create mask">0600</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="printable">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + +<smbconfsection name="[print$]"/> +<smbconfoption name="comment">Printer Drivers Share</smbconfoption> +<smbconfoption name="path">/var/lib/samba/drivers</smbconfoption> +<smbconfoption name="write list">maryo, root</smbconfoption> +<smbconfoption name="printer admin">maryo, root</smbconfoption> + +<smbconfcomment>Needed to support domain logons</smbconfcomment> +<smbconfsection name="[netlogon]"/> +<smbconfoption name="comment">Network Logon Service</smbconfoption> +<smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption> +<smbconfoption name="admin users">root, maryo</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> + +<smbconfcomment>For profiles to work, create a user directory under the path</smbconfcomment> +<smbconfcomment> shown. i.e., mkdir -p /var/lib/samba/profiles/maryo</smbconfcomment> +<smbconfsection name="[Profiles]"/> +<smbconfoption name="comment">Roaming Profile Share</smbconfoption> +<smbconfoption name="path">/var/lib/samba/profiles</smbconfoption> +<smbconfoption name="read only">No</smbconfoption> +<smbconfoption name="profile acls">Yes</smbconfoption> + +<smbconfcomment>Other resource (share/printer) definitions would follow below.</smbconfcomment> + </smbconfexample> + </para></step> + + <step><para> + Create UNIX group accounts as needed using a suitable operating system tool: +<screen> +&rootprompt;<userinput>groupadd ntadmins</userinput> +&rootprompt;<userinput>groupadd designers</userinput> +&rootprompt;<userinput>groupadd engineers</userinput> +&rootprompt;<userinput>groupadd qateam</userinput> +</screen> + </para></step> + + <step><para> + Create user accounts on the system using the appropriate tool + provided with the operating system. Make sure all user home directories + are created also. Add users to groups as required for access control + on files, directories, printers, and as required for use in the Samba + environment. + </para></step> + + + <step><para> +<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm> +<indexterm><primary>initGroups.sh</primary></indexterm> + Assign each of the UNIX groups to NT groups: + (It may be useful to copy this text to a shell script called + <filename>initGroups.sh</filename>.) + <smbfile name="initGroups.sh"> + <title>Shell script for initializing group mappings</title> + <programlisting> +#!/bin/bash +#### Keep this as a shell script for future re-use + +# First assign well known groups +net groupmap modify ntgroup="Domain Admins" unixgroup=ntadmins +net groupmap modify ntgroup="Domain Users" unixgroup=users +net groupmap modify ntgroup="Domain Guests" unixgroup=nobody + +# Now for our added Domain Groups +net groupmap add ntgroup="Designers" unixgroup=designers type=d +net groupmap add ntgroup="Engineers" unixgroup=engineers type=d +net groupmap add ntgroup="QA Team" unixgroup=qateam type=d +</programlisting> +</smbfile> + </para></step> + + <step><para> + Create the <filename>scripts</filename> directory for use in the + <smbconfsection name="[NETLOGON]"/> share: +<screen> +&rootprompt;<userinput>mkdir -p /var/lib/samba/netlogon/scripts</userinput> +</screen> + Place the logon scripts that will be used (batch or cmd scripts) + in this directory. + </para></step> + </procedure> + + <para> + The above configuration provides a functional Primary Domain Control (PDC) + system to which must be added file shares and printers as required. + </para> + + </sect3> + + <sect3> + <title>A Big Organization</title> + + <para> + In this section we finally get to review in brief a Samba-3 configuration that + uses a Light Weight Directory Access (LDAP)-based authentication backend. The + main reasons for this choice are to provide the ability to host primary + and Backup Domain Control (BDC), as well as to enable a higher degree of + scalability to meet the needs of a very distributed environment. + </para> + + <sect4> + <title>The Primary Domain Controller</title> + + <para> + This is an example of a minimal configuration to run a Samba-3 PDC + using an LDAP authentication backend. It is assumed that the operating system + has been correctly configured. + </para> + + <para> + The Idealx scripts (or equivalent) are needed to manage LDAP based Posix and/or + SambaSamAccounts. The Idealx scripts may be downloaded from the <ulink url="http://www.idealx.org"> + Idealx</ulink> Web site. They may also be obtained from the Samba tarball. Linux + distributions tend to install the Idealx scripts in the + <filename>/usr/share/doc/packages/sambaXXXXXX/examples/LDAP/smbldap-tools</filename> directory. + Idealx scripts version <constant>smbldap-tools-0.8.7</constant> are known to work well. + </para> + + <procedure> + <step><para> + Obtain from the Samba sources <filename>~/examples/LDAP/samba.schema</filename> + and copy it to the <filename>/etc/openldap/schema/</filename> directory. + </para></step> + + <step><para> + Set up the LDAP server. This example is suitable for OpenLDAP 2.1.x. + The <filename>/etc/openldap/slapd.conf</filename> file: +<indexterm><primary>/etc/openldap/slapd.conf</primary></indexterm> +<smbfile name="slapd.conf"><title>Example slapd.conf file</title> +<programlisting> +# Note commented out lines have been removed +include /etc/openldap/schema/core.schema +include /etc/openldap/schema/cosine.schema +include /etc/openldap/schema/inetorgperson.schema +include /etc/openldap/schema/nis.schema +include /etc/openldap/schema/samba.schema + +pidfile /var/run/slapd/slapd.pid +argsfile /var/run/slapd/slapd.args + +database bdb +suffix "dc=quenya,dc=org" +rootdn "cn=Manager,dc=quenya,dc=org" +rootpw {SSHA}06qDkonA8hk6W6SSnRzWj0/pBcU3m0/P +# The password for the above is 'nastyon3' + +directory /var/lib/ldap + +index objectClass eq +index cn pres,sub,eq +index sn pres,sub,eq +index uid pres,sub,eq +index displayName pres,sub,eq +index uidNumber eq +index gidNumber eq +index memberUid eq +index sambaSID eq +index sambaPrimaryGroupSID eq +index sambaDomainName eq +index default sub +</programlisting> +</smbfile> + </para></step> + + <step><para> + Create the following file <filename>samba-ldap-init.ldif</filename>: + <indexterm><primary>samba-ldap-init.ldif</primary></indexterm> + <smbfile name="samba-ldap-init.ldif"> +<programlisting> +# Organization for SambaXP Demo +dn: dc=quenya,dc=org +objectclass: dcObject +objectclass: organization +dc: quenya +o: SambaXP Demo +description: The SambaXP Demo LDAP Tree + +# Organizational Role for Directory Management +dn: cn=Manager,dc=quenya,dc=org +objectclass: organizationalRole +cn: Manager +description: Directory Manager + +# Setting up the container for users +dn: ou=People, dc=quenya, dc=org +objectclass: top +objectclass: organizationalUnit +ou: People + +# Set up an admin handle for People OU +dn: cn=admin, ou=People, dc=quenya, dc=org +cn: admin +objectclass: top +objectclass: organizationalRole +objectclass: simpleSecurityObject +userPassword: {SSHA}0jBHgQ1vp4EDX2rEMMfIudvRMJoGwjVb +# The password for above is 'mordonL8' +</programlisting> +</smbfile> + </para></step> + + <step><para> + Load the initial data above into the LDAP database: +<screen> +&rootprompt;<userinput>slapadd -v -l initdb.ldif</userinput> +</screen> + </para></step> + + <step><para> + Start the LDAP server using the appropriate tool or method for + the operating system platform on which it is installed. + </para></step> + + <step><para> + Install the Idealx script files in the <filename>/usr/local/sbin</filename> directory, + then configure the smbldap_conf.pm file to match your system configuration. + </para></step> + + <step><para> + The &smb.conf; file that drives this backend can be found in example <link linkend="fast-ldap"/>. + </para> + + <para> +<smbconfexample id="fast-ldap"> +<title>LDAP backend smb.conf for PDC</title> +<smbconfcomment>Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">FRODO</smbconfoption> +<smbconfoption name="passdb backend">ldapsam:ldap://localhost</smbconfoption> +<smbconfoption name="username map">/etc/samba/smbusers</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> +<smbconfoption name="add user script">/usr/local/sbin/smbldap-useradd -m '%u'</smbconfoption> +<smbconfoption name="delete user script">/usr/local/sbin/smbldap-userdel %u</smbconfoption> +<smbconfoption name="add group script">/usr/local/sbin/smbldap-groupadd -p '%g'</smbconfoption> +<smbconfoption name="delete group script">/usr/local/sbin/smbldap-groupdel '%g'</smbconfoption> +<smbconfoption name="add user to group script">/usr/local/sbin/smbldap-groupmod -m '%u' '%g'</smbconfoption> +<smbconfoption name="delete user from group script">/usr/local/sbin/smbldap-groupmod -x '%u' '%g'</smbconfoption> +<smbconfoption name="set primary group script">/usr/local/sbin/smbldap-usermod -g '%g' '%u'</smbconfoption> +<smbconfoption name="add machine script">/usr/local/sbin/smbldap-useradd -w '%u'</smbconfoption> +<smbconfoption name="logon script">scripts\logon.bat</smbconfoption> +<smbconfoption name="logon path">\\%L\Profiles\%U</smbconfoption> +<smbconfoption name="logon drive">H:</smbconfoption> +<smbconfoption name="logon home">\\%L\%U</smbconfoption> +<smbconfoption name="domain logons">Yes</smbconfoption> +<smbconfoption name="os level">35</smbconfoption> +<smbconfoption name="preferred master">Yes</smbconfoption> +<smbconfoption name="domain master">Yes</smbconfoption> +<smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption> +<smbconfoption name="ldap machine suffix">ou=People</smbconfoption> +<smbconfoption name="ldap user suffix">ou=People</smbconfoption> +<smbconfoption name="ldap group suffix">ou=People</smbconfoption> +<smbconfoption name="ldap idmap suffix">ou=People</smbconfoption> +<smbconfoption name="ldap admin dn">cn=Manager</smbconfoption> +<smbconfoption name="ldap ssl">no</smbconfoption> +<smbconfoption name="ldap passwd sync">Yes</smbconfoption> +<smbconfoption name="idmap uid">15000-20000</smbconfoption> +<smbconfoption name="idmap gid">15000-20000</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> +</smbconfexample> + </para></step> + + <step><para> + Add the LDAP password to the <filename>secrets.tdb</filename> file so Samba can update + the LDAP database: +<screen> +&rootprompt;<userinput>smbpasswd -w mordonL8</userinput> +</screen> + </para></step> + + <step><para> + Add users and groups as required. Users and groups added using Samba tools + will automatically be added to both the LDAP backend as well as to the operating + system as required. + </para></step> + + </procedure> + + </sect4> + + <sect4> + <title>Backup Domain Controller</title> + + <para> + <link linkend="fast-bdc"/> shows the example configuration for the BDC. + </para> + + <procedure> + <step><para> + Decide if the BDC should have its own LDAP server or not. If the BDC is to be + the LDAP server change the following &smb.conf; as indicated. The default + configuration in <link linkend="fast-bdc"/> uses a central LDAP server. +<smbconfexample id="fast-bdc"> +<title>Remote LDAP BDC smb.conf</title> +<smbconfcomment>Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">MIDEARTH</smbconfoption> +<smbconfoption name="netbios name">GANDALF</smbconfoption> +<smbconfoption name="passdb backend">ldapsam:ldap://frodo.quenya.org</smbconfoption> +<smbconfoption name="username map">/etc/samba/smbusers</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> +<smbconfoption name="logon script">scripts\logon.bat</smbconfoption> +<smbconfoption name="logon path">\\%L\Profiles\%U</smbconfoption> +<smbconfoption name="logon drive">H:</smbconfoption> +<smbconfoption name="logon home">\\%L\%U</smbconfoption> +<smbconfoption name="domain logons">Yes</smbconfoption> +<smbconfoption name="os level">33</smbconfoption> +<smbconfoption name="preferred master">Yes</smbconfoption> +<smbconfoption name="domain master">No</smbconfoption> +<smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption> +<smbconfoption name="ldap machine suffix">ou=People</smbconfoption> +<smbconfoption name="ldap user suffix">ou=People</smbconfoption> +<smbconfoption name="ldap group suffix">ou=People</smbconfoption> +<smbconfoption name="ldap idmap suffix">ou=People</smbconfoption> +<smbconfoption name="ldap admin dn">cn=Manager</smbconfoption> +<smbconfoption name="ldap ssl">no</smbconfoption> +<smbconfoption name="ldap passwd sync">Yes</smbconfoption> +<smbconfoption name="idmap uid">15000-20000</smbconfoption> +<smbconfoption name="idmap gid">15000-20000</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> +</smbconfexample> + </para></step> + + <step><para> + Configure the NETLOGON and PROFILES directory as for the PDC in <link linkend="fast-bdc"/>. + </para></step> + </procedure> + + </sect4> + + </sect3> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Further-Resources.xml b/docs/Samba3-HOWTO/TOSHARG-Further-Resources.xml new file mode 100644 index 0000000000..0a9d7d1cd5 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Further-Resources.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="Further-Resources"> +<chapterinfo> + &author.jelmer; + <pubdate>May 1, 2003</pubdate> +</chapterinfo> + +<title>Further Resources</title> + +<sect1> + <title>Web sites</title> + +<itemizedlist> + + <listitem><para> + <ulink url="http://hr.uoregon.edu/davidrl/cifs.txt"> + <emphasis>CIFS: Common Insecurities Fail Scrutiny</emphasis> by <quote>Hobbit</quote></ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://afr.com/it/2002/10/01/FFXDF43AP6D.html"> + <emphasis>Doing the Samba on Windows</emphasis> by Financial Review + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://ubiqx.org/cifs/"> + <emphasis>Implementing CIFS</emphasis> by Christopher R. Hertel + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://samba.anu.edu.au/cifs/docs/what-is-smb.html"> + <emphasis>Just What Is SMB?</emphasis> by Richard Sharpe + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.linux-mag.com/1999-05/samba_01.html"> + <emphasis>Opening Windows Everywhere</emphasis> by Mike Warfield + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.tldp.org/HOWTO/SMB-HOWTO.html"> + <emphasis>SMB HOWTO</emphasis> by David Wood + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.phrack.org/phrack/60/p60-0x0b.txt"> + <emphasis>SMB/CIFS by The Root</emphasis> by <quote>ledin</quote> + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.linux-mag.com/1999-09/samba_01.html"> + <emphasis>The Story of Samba</emphasis> by Christopher R. Hertel + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://hr.uoregon.edu/davidrl/samba/"> + <emphasis>The Unofficial Samba HOWTO</emphasis> by David Lechnyr + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.linux-mag.com/2001-05/smb_01.html"> + <emphasis>Understanding the Network Neighborhood</emphasis> by Christopher R. Hertel + </ulink> + </para></listitem> + + <listitem><para> + <ulink url="http://www.linux-mag.com/2002-02/samba_01.html"> + <emphasis>Using Samba as a PDC</emphasis> by Andrew Bartlett + </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> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml b/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml new file mode 100644 index 0000000000..4a1664b1f6 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml @@ -0,0 +1,792 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="groupmapping"> +<chapterinfo> + &author.jht; + <author> + <firstname>Jean François</firstname><surname>Micouleau</surname> + </author> + &author.jerry; +</chapterinfo> +<title>Group Mapping &smbmdash; MS Windows and UNIX</title> + + + <para> +<indexterm significance="preferred"><primary>groups</primary><secondary>mapping</secondary></indexterm> + Starting with Samba-3, new group mapping functionality is available to create associations + between Windows group SIDs and UNIX groups. The <command>groupmap</command> subcommand + included with the &net; tool can be used to manage these associations. + </para> + + <para> + The new facility for mapping NT Groups to UNIX system groups allows the administrator to decide + which NT Domain Groups are to be exposed to MS Windows clients. Only those NT Groups that map + to a UNIX group that has a value other than the default (<constant>-1</constant>) will be exposed + in group selection lists in tools that access domain users and groups. + </para> + + <warning> + <para> + <indexterm><primary>domain admin group</primary></indexterm> + The <parameter>domain admin group</parameter> parameter has been removed in Samba-3 and should no longer + be specified in &smb.conf;. In Samba-2.2.x, 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> + +<sect1> +<title>Features and Benefits</title> + + <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> +<indexterm><primary>UID</primary></indexterm> +<indexterm><primary>GID</primary></indexterm> +<indexterm><primary>idmap uid</primary></indexterm> + Group accounts can be managed using the MS Windows NT4 or MS Windows 200x/XP Professional MMC tools. + Appropriate interface scripts should be provided in &smb.conf; if it is desired that UNIX/Linux system + accounts should be automatically created when these tools are used. In the absence of these scripts, and + so long as <command>winbindd</command> is running, Samba group accounts that are created using these + tools will be allocated UNIX UIDs/GIDs from the ID range specified by the + <smbconfoption name="idmap uid"/>/<smbconfoption name="idmap gid"/> + parameters in the &smb.conf; file. + </para> + + <image id="idmap-sid2gid"> + <imagedescription>IDMAP: group SID to GID resolution.</imagedescription> + <imagefile scale="50">idmap-sid2gid</imagefile> + </image> + + <image id="idmap-gid2sid"> + <imagedescription>IDMAP: GID resolution to matching SID.</imagedescription> + <imagefile scale="50">idmap-gid2sid</imagefile> + </image> + + <para> + <indexterm><primary>IDMAP</primary></indexterm> + In both cases, when winbindd is not running, only locally resolvable groups can be recognized. Please refer to + <link linkend="idmap-sid2gid">IDMAP: group SID to GID resolution</link> and + <link linkend="idmap-gid2sid">IDMAP: GID resolution to matching SID</link>. + The <command>net groupmap</command> is + used to establish UNIX group to NT SID mappings as shown in <link linkend="idmap-store-gid2sid">IDMAP: storing group mappings</link>. + </para> + + <image id="idmap-store-gid2sid"> + <imagedescription>IDMAP storing group mappings.</imagedescription> + <imagefile scale="50">idmap-store-gid2sid</imagefile> + </image> + + <para> + <indexterm><primary>groupadd</primary></indexterm> + <indexterm><primary>groupdel</primary></indexterm> + Administrators should be aware that where &smb.conf; group interface scripts make + direct calls to the UNIX/Linux system tools (the shadow utilities, <command>groupadd</command>, + <command>groupdel</command>, and <command>groupmod</command>), 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 + <literal>Engineering Managers</literal> will attempt to create an identically named + UNIX/Linux group, an attempt that will of course fail. + </para> + + <para> + <indexterm><primary>GID</primary></indexterm> + <indexterm><primary>SID</primary></indexterm> + 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 that group privileges necessary privileges to perform essential system tasks, + such as the ability to change the date and time or to kill (or close) any process running on the + local machine. + </para> + + <para> + <indexterm><primary>Administrator</primary></indexterm> + The <constant>Administrator</constant> user is a member of the <constant>Administrators</constant> group, and thus inherits + <constant>Administrators</constant> group privileges. If a <constant>joe</constant> user is created to be a member of the + <constant>Administrators</constant> group, <constant>joe</constant> has exactly the same rights as the user, + <constant>Administrator</constant>. + </para> + + <para> + When an MS Windows NT4/200x/XP machine is made a Domain Member, the <quote>Domain Admins</quote> group of the + PDC is added to the local <constant>Administrators</constant> group of the workstation. Every member of the + <constant>Domain Administrators</constant> group inherits the rights of the local <constant>Administrators</constant> group when + logging on the workstation. + </para> + + <para> + The following steps describe how to make Samba PDC users members of the <constant>Domain Admins</constant> group? + </para> + + <orderedlist> + <listitem><para> + Create a UNIX group (usually in <filename>/etc/group</filename>), let's call it <constant>domadm</constant>. + </para></listitem> + + <listitem><para> + Add to this group the users that must be <quote>Administrators</quote>. For example, + if you want <constant>joe, john</constant> and <constant>mary</constant> to be administrators, + your entry in <filename>/etc/group</filename> will look like this: + </para> + + <para><programlisting> + domadm:x:502:joe,john,mary + </programlisting> + </para></listitem> + + <listitem><para> + Map this domadm group to the <quote>Domain Admins</quote> group by running the command: + </para> + + <para> + <screen> + &rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm</userinput> + </screen> + </para> + + <para> + <indexterm><primary>Domain Admins group</primary></indexterm> + The quotes around <quote>Domain Admins</quote> are necessary due to the space in the group name. + Also make sure to leave no white-space surrounding the equal character (=). + </para></listitem> + </orderedlist> + + <para> + Now <constant>joe, john</constant> and <constant>mary</constant> are domain administrators. + </para> + + <para> + <indexterm><primary>groups</primary><secondary>domain</secondary></indexterm> + 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 an 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 parameter 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. Verification for this is done differently depending 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>Warning &smbmdash; User Private Group Problems</title> + + <para> + Windows does not permit user and group accounts to have the same name. + This has serious implications for all sites that use private group accounts. + A private group account is an administrative practice whereby users are each + given their own group account. Red Hat Linux, as well as several free distributions + of Linux by default create private groups. + </para> + + <para> + When mapping a UNIX/Linux group to a Windows group account all conflict can + be avoided by assuring that the Windows domain group name does not overlap + with any user account name. + </para> + + </sect2> + + <sect2> + <title>Nested Groups: Adding Windows Domain Groups to Windows Local Groups</title> + + <indexterm><primary>groups</primary><secondary>nested</secondary></indexterm> + + <para> + This functionality is known as <constant>nested groups</constant> and was first added to + Samba-3.0.3. + </para> + + <para> + All Microsoft Windows products since the release of Windows NT 3.10 support the use of nested groups. + Many Windows network administrators depend on this capability becasue it greatly simplifies security + administration. + </para> + + <para> + The nested group architecture was designed with the premise that day-to-day user and group membership + management should be performed on the domain security database. The application of group security + should be implemented on domain member servers using only local groups. On the domain member server + all file system security controls are then limited to use of the local groups which will contain + domain global groups and domain global users. + </para> + + <para> + You may ask, What are the benefits of this arrangement? The answer is obvious to those who have plumbed + the dark depths of Windows networking architecture. Consider for a moment a server on which are stored + 200,000 files, each with individual domain user and domain group settings. The company that owns the + file server is bought by another company resulting in the server being moved to another location and then + it is made a member of a different domain. Who would you think now owns all the files and directories? + Answer: Account Unknown. + </para> + + <para> + Unravelling the file ownership mess is an unenviable administrative task that can be avoided simply + by using local groups to control all file and directory access control. In this case, only the members + of the local groups will have been lost. The files and directories in the storage subsystem will still + be owned by the local groups. The same goes for all ACLs on them. It is administratively much simpler + to delete the <constant>Account Unknown</constant> membership entries inside local groups with appropriate + entries for domain global groups in the new domain that the server has been made a member of. + </para> + + <para> + Another prominent example of the use of nested groups involves implementation of administrative privileges + on domain member workstations and servers. Administrative privileges are given to all members of the + builtin + local group <constant>Administrators</constant> on each domain member machine. To ensure that all domain + administrators have full rights on the member server or workstation, on joining the domain the + <constant>Domain Admins</constant> group is added to the local Administrators group. Thus everyone who is + logged into the domain as a member of the Domain Admins group is also granted local adminitrative + privileges on each domain member. + </para> + + <para> + UNIX/Linux has no concept of support for nested groups, and thus Samba has for a long time not supported + them either. The problem is that you would have to enter unix groups as auxiliary members of a group in + <filename>/etc/group</filename>. This does not work because it was not a design requirement at the time + the UNIX file system security model was implemented. Since Samba-2.2 the winbind daemon can provide + <filename>/etc/group</filename> entries on demand by obtaining user and group information from the Domain + Controller that the Samba server is a member of. + </para> + <para> + In effect, Samba supplements the <filename>/etc/group</filename> data via the dynamic + <command>libnss_winbind</command> mechanism. Beginning with Samba-3.0.3 this facility is used to provide + local groups in the same manner as Windows does it. It works by expanding the local groups on the + fly as they are accessed. For example, the <constant>Domain Users</constant> group of the domain is made + a member of the local group <constant>demo</constant>. Whenever Samba needs to resolve membership of the + <constant>demo</constant> local (alias) group winbind asks the DC for demo members of the Domain Users + group. By definition it can only contain user objects which can then be faked to be member of the + UNIX/Linux group <constant>demo</constant>. + </para> + + <para> + To enable the use of nested groups, <command>winbindd</command> must be used together with NSS winbind. + Creation and administration of the local groups is done best via the Windows Domain User Manager or its + Samba equivalent, the utility <command>net rpc group</command>. Creating the local group + <constant>demo</constant> is achieved by executing: + <screen> + &rootprompt; net rpc group add demo -L -Uroot%not24get + </screen> + Here the -L switch means that you want to create a local group. It may be necessary to add -S and -U + switches for accessing the correct host with appropriate user or root priviliges. Adding and removing + group + members can be done via the <constant>addmem</constant> and <constant>delmem</constant> subcommands of + <command>net rpc group</command> command. For example addition of <quote>DOM\Domain Users</quote> to the + local + group <constant>demo</constant> would be done by executing: + <screen> + net rpc group addmem demo "DOM\Domain Users" + </screen> + Having completed these two steps the execution of <command>getent group demo</command> will show demo + members of the global <constant>Domain Users</constant> group as members of the group + <constant>demo</constant>. This also works with any local or domain user. In case the domain DOM trusts + another domain, it is also possible to add global users and groups of the trusted domain as members of + <constant>demo</constant>. + </para> + + </sect2> + + <sect2> + <title>Important Administrative Information</title> + + <para> + Administrative rights are necessary in two specific forms: + </para> + + <orderedlist> + <listitem><para>For Samba-3 Domain Controllers and + Domain Member Servers/Clients.</para></listitem> + <listitem><para>To manage Domain Member Windows workstations.</para></listitem> + </orderedlist> + + <para> + Versions of Samba up to and including 3.0.10 do not provide a means for assigning rights and privileges + that are necessary for system administration tasks from a Windows Domain Member Client machine so that + domain administration tasks such as adding/deleting/changing user and group account information, and + managing workstation domain membership accounts, can be handled by any account other than root. + </para> + + <para> + Samba-3.0.11 introduced a new privilege management interface (see <link linkend="rights">Chapter on Rights and Privileges</link>) + that permits these tasks to be delegated to non-root (i.e.: accounts other than the equivalent of the + MS Windows Administrator) account. + </para> + + <para> + Administrative tasks on a Windows Domain Member workstation, can be done by anyone who is a member of the + <constant>Domain Admins</constant> group. This group can be mapped to any convenient UNIX group. + </para> + + <sect3> + <title>Applicable Only to Versions Earlier than 3.0.11</title> + + <para> + Administrative tasks on UNIX/Linux systems, such as adding users or groups, requires <constant>root</constant> + level privilege. The addition of a Windows client to a Samba Domain involves the addition of a user account + for the Windows client. + </para> + + <para> + Many UNIX administrators continue to request the Samba Team make it possible to add Windows workstations, or + to ability to add/delete or modify user accounts, without requiring <constant>root</constant> privileges. + Such a request violates every understanding of basic UNIX system security. + </para> + + <para> + There is no safe way to provide access on a UNIX/Linux system without providing <constant>root</constant> + level privilege. Provision of <constant>root</constant> privileges can be done either by logging onto + the Domain as the user <constant>root</constant>, or by permitting particular users to use a UNIX account + that has a UID=0 in the <filename>/etc/passwd</filename> database. Users of such accounts can use tools + like the NT4 Domain User Manager, and the NT4 Domain Server Manager to manage user and group accounts as + well as Domain Member server and client accounts. This level of privilege is also needed to manage share + level ACLs. + </para> + + </sect3> + + </sect2> + + <sect2> + <title>Default Users, Groups and Relative Identifiers</title> + + <para> +<indexterm><primary>Relative Identifier</primary><see>RID</see></indexterm> +<indexterm><primary>RID</primary></indexterm> + When first installed, Microsoft Windows NT4/200x/XP are pre-configured with certain User, Group, and + Alias entities. Each has a well-known Relative Identifier (RID). These must be preserved for continued + integrity of operation. Samba must be provisioned with certain essential Domain Groups that require + the appropriate RID value. When Samba-3 is configured to use <constant>tdbsam</constant> the essential + Domain Groups are automatically created. It is the LDAP administrators' responsibility to create + (provision) the default NT Groups. + </para> + + <para> + Each essential Domain Group must be assigned its respective well-known RID. The default Users, Groups, + Aliases, and RIDs are shown in <link linkend="WKURIDS">Well-Known User Default RIDs</link> table. + </para> + + <note><para> + When the <parameter>passdb backend</parameter> uses LDAP (<constant>ldapsam</constant>) it is the + administrators' responsibility to create the essential Domain Groups, and to assign each its default RID. + </para></note> + + <para> + It is permissible to create any Domain Group that may be necessary, just make certain that the essential + Domain Groups (well known) have been created and assigned its default RID. Other groups you create may + be assigned any arbitrary RID you care to use. + </para> + + <para> + Be sure to map each Domain Group to a UNIX system group. That is the only way to ensure that the group + will be available for use as an NT Domain Group. + </para> + + <para> + <table frame="all" id="WKURIDS"> + <title>Well-Known User Default RIDs</title> + <tgroup cols="4" align="left"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="center"/> + <thead> + <row> + <entry>Well-Known Entity</entry> + <entry>RID</entry> + <entry>Type</entry> + <entry>Essential</entry> + </row> + </thead> + <tbody> + <row> + <entry>Domain Administrator</entry> + <entry>500</entry> + <entry>User</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Guest</entry> + <entry>501</entry> + <entry>User</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain KRBTGT</entry> + <entry>502</entry> + <entry>User</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Admins</entry> + <entry>512</entry> + <entry>Group</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Domain Users</entry> + <entry>513</entry> + <entry>Group</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Domain Guests</entry> + <entry>514</entry> + <entry>Group</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Domain Computers</entry> + <entry>515</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Controllers</entry> + <entry>516</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Certificate Admins</entry> + <entry>517</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Schema Admins</entry> + <entry>518</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Enterprise Admins</entry> + <entry>519</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Policy Admins</entry> + <entry>520</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Admins</entry> + <entry>544</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin users</entry> + <entry>545</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Guests</entry> + <entry>546</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Power Users</entry> + <entry>547</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Account Operators</entry> + <entry>548</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin System Operators</entry> + <entry>549</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Print Operators</entry> + <entry>550</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Backup Operators</entry> + <entry>551</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Replicator</entry> + <entry>552</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin RAS Servers</entry> + <entry>553</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + </sect2> + + <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> + +<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm> + + <para> +<screen> +&rootprompt; <userinput>net groupmap list</userinput> +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 + (i.e., prepared by someone else for general use). + </para> + + <sect2> + <title>Sample &smb.conf; Add Group Script</title> + + <para> + <indexterm><primary>smbgrpadd.sh</primary></indexterm> + <indexterm><primary>groupadd limitations</primary></indexterm> + A script to create complying group names for use by the Samba group interfaces + is provided in <link linkend="smbgrpadd.sh">smbgrpadd.sh</link>. This script will + add a temporary entry in the <filename>/etc/group</filename> file and then rename + it to to the desired name. This is an example of a method to get around operating + system maintenance tool limititations such as that present in some version of the + <command>groupadd</command> tool. + </para> + +<indexterm><primary>smbgrpadd.sh</primary></indexterm> + <para> +<example id="smbgrpadd.sh"> + <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 +cp /etc/group /etc/group.bak +cat /etc/group.bak | 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 be something like that in <link linkend="smbgrpadd">the following example</link>. +<smbconfexample id="smbgrpadd" fragment="1"> +<title>Configuration of &smb.conf; for the add group script.</title> +<smbconfsection name="[global]"/> +<smbconfoption name="add group script">/path_to_tool/smbgrpadd.sh "%g"</smbconfoption> +</smbconfexample> + </para> + + </sect2> + + <sect2> + <title>Script to Configure Group Mapping</title> + + <para> + In our example we have created a UNIX/Linux group called <literal>ntadmin</literal>. + Our script will create the additional groups <literal>Orks</literal>, <literal>Elves</literal>, and <literal>Gnomes</literal>. + It is a good idea to save this shell script for later re-use just in case you ever need to rebuild your mapping database. + For the sake of convenience we elect to save this script as a file called <filename>initGroups.sh</filename>. + This script is given in <link linkend="set-group-map">intGroups.sh</link>. + </para> + +<para> +<indexterm><primary>initGroups.sh</primary></indexterm> +<example id="set-group-map"> + <title>Script to Set Group Mapping</title> +<programlisting> +#!/bin/bash + +net groupmap modify ntgroup="Domain Admins" unixgroup=ntadmin +net groupmap modify ntgroup="Domain Users" unixgroup=users +net groupmap modify ntgroup="Domain Guests" unixgroup=nobody + +groupadd Orks +groupadd Elves +groupadd Gnomes + +net groupmap add ntgroup="Orks" unixgroup=Orks type=d +net groupmap add ntgroup="Elves" unixgroup=Elves type=d +net groupmap add ntgroup="Gnomes" unixgroup=Gnomes type=d +</programlisting> +</example> +</para> + + <para> + Of course it is expected that the administrator 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> + + </sect2> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +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> + + <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 <smbconfoption name="add group script"/> in + the &smb.conf; file. + </para> + + <para> + The most common cause of failure is an attempt to add an MS Windows group account + that has either an upper case character and/or a space character in it. + </para> + + <para> + There are three possible work-arounds. First, use only group names that comply + with the limitations of the UNIX/Linux <command>groupadd</command> system tool. + Second, it involves the use of the script mentioned earlier in this chapter, and + third is the 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> + + <sect2> + <title>Adding <emphasis>Domain Users</emphasis> to the <emphasis>Power Users</emphasis> Group</title> + + <para><quote> + What must I do to add Domain Users to the Power Users group? + </quote></para> + +<indexterm><primary>Domain Users group</primary></indexterm> + + <para> + The Power Users group is a group that is local to each Windows 200x/XP Professional workstation. + You cannot add the Domain Users group to the Power Users group automatically, it must be done on + each workstation by logging in as the local workstation <emphasis>administrator</emphasis> and + then using the following procedure: + </para> + + <procedure> + <step><para> + Click <guimenu>Start -> Control Panel -> Users and Passwords</guimenu>. + </para></step> + + <step><para> + Click the <guimenuitem>Advanced</guimenuitem> tab. + </para></step> + + <step><para> + Click the <guibutton>Advanced</guibutton> button. + </para></step> + + <step><para> + Click <constant>Groups</constant>. + </para></step> + + <step><para> + Double click <constant>Power Users</constant>. This will launch the panel to add users or groups + to the local machine <constant>Power Uses</constant> group. + </para></step> + + <step><para> + Click the <guibutton>Add</guibutton> button. + </para></step> + + <step><para> + Select the domain from which the <constant>Domain Users</constant> group is to be added. + </para></step> + + <step><para> + Double click the <constant>Domain Users</constant> group. + </para></step> + + <step><para> + Click the <guibutton>Ok</guibutton> button. If a logon box is presented during this process + please remember to enter the connect as <constant>DOMAIN\UserName</constant>. i.e., For the + domain <constant>MIDEARTH</constant> and the user <constant>root</constant> enter + <constant>MIDEARTH\root</constant>. + </para></step> + </procedure> + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-HighAvailability.xml b/docs/Samba3-HOWTO/TOSHARG-HighAvailability.xml new file mode 100644 index 0000000000..385646d91f --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-HighAvailability.xml @@ -0,0 +1,414 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="SambaHA"> +<chapterinfo> + &author.jht; + &author.jeremy; +</chapterinfo> + +<title>High Availability</title> + +<sect1> +<title>Features and Benefits</title> + +<para> +Network administrators are often concerned about the availability of file and print +services. Network users are inclined toward intolerance of the services they depend +on to perform vital task responsibilities. +</para> + +<para> +A sign in a computer room served to remind staff of their responsibilities. It read: +</para> + +<blockquote> +<para> +All humans fail, in both great and small ways we fail continually. Machines fail too. +Computers are machines that are managed by humans, the fallout from failure +can be spectacular. Your responsibility is to deal with failure, to anticipate it +and to eliminate it as far as is humanly and economically wise to achieve. +Are your actions part of the problem or part of the solution? +</para> +</blockquote> + +<para> +If we are to deal with failure in a planned and productive manner, then first we must +understand the problem. That is the purpose of this chapter. +</para> + +<para> +Parenthetically, in the following discussion there are seeds of information on how to +provision a network infrastructure against failure. Our purpose here is not to provide +a lengthy dissertation on the subject of high availability. Additionally, we have made +a conscious decision to not provide detailed working examples of high availability +solutions; instead we present an overview of the issues in the hope that someone will +rise to the challenge of providing a detailed document that is focused purely on +presentation of the current state of knowledge and practice in high availability as it +applies to the deployment of Samba and other CIFS/SMB technologies. +</para> + +</sect1> + +<sect1> +<title>Technical Discussion</title> + +<para> +The following summary was part of a presentation by Jeremy Allison at the SambaXP 2003 +conference that was held at Goettingen, Germany, in April 2003. Material has been added +from other sources, but it was Jeremy who inspired the structure that follows. +</para> + + <sect2> + <title>The Ultimate Goal</title> + + <para> + All clustering technologies aim to achieve one or more of the following: + </para> + + <itemizedlist> + <listitem><para>Obtain the maximum affordable computational power.</para></listitem> + <listitem><para>Obtain faster program execution.</para></listitem> + <listitem><para>Deliver unstoppable services.</para></listitem> + <listitem><para>Avert points of failure.</para></listitem> + <listitem><para>Exact most effective utilization of resources.</para></listitem> + </itemizedlist> + + <para> + A clustered file server ideally has the following properties: + </para> + + <itemizedlist> + <listitem><para>All clients can connect transparently to any server.</para></listitem> + <listitem><para>A server can fail and clients are transparently reconnected to another server.</para></listitem> + <listitem><para>All servers server out the same set of files.</para></listitem> + <listitem><para>All file changes are immediately seen on all servers.</para> + <itemizedlist><listitem><para>Requires a distributed file system.</para></listitem></itemizedlist></listitem> + <listitem><para>Infinite ability to scale by adding more servers or disks.</para></listitem> + </itemizedlist> + + </sect2> + + <sect2> + <title>Why Is This So Hard?</title> + + <para> + In short, the problem is one of <emphasis>state</emphasis>. + </para> + + <itemizedlist> + <listitem> + <para> + All TCP/IP connections are dependent on state information. + </para> + <para> + The TCP connection involves a packet sequence number. This + sequence number would need to be dynamically updated on all + machines in the cluster to effect seamless TCP fail-over. + </para> + </listitem> + <listitem> + <para> + CIFS/SMB (the Windows networking protocols) uses TCP connections. + </para> + <para> + This means that from a basic design perspective, fail-over is not + seriously considered. + <itemizedlist> + <listitem><para> + All current SMB clusters are fail-over solutions + &smbmdash; they rely on the clients to reconnect. They provide server + fail-over, but clients can lose information due to a server failure. + </para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + Servers keep state information about client connections. + <itemizedlist> + <listitem><para>CIFS/SMB involves a lot of state.</para></listitem> + <listitem><para>Every file open must be compared with other file opens + to check share modes.</para></listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + + <sect3> + <title>The Front-End Challenge</title> + + <para> + To make it possible for a cluster of file servers to appear as a single server that has one + name and one IP address, the incoming TCP data streams from clients must be processed by the + front end virtual server. This server must de-multiplex the incoming packets at the SMB protocol + layer level and then feed the SMB packet to different servers in the cluster. + </para> + + <para> + One could split all IPC$ connections and RPC calls to one server to handle printing and user + lookup requirements. RPC Printing handles are shared between different IPC4 sessions &smbmdash; it is + hard to split this across clustered servers! + </para> + + <para> + Conceptually speaking, all other servers would then provide only file services. This is a simpler + problem to concentrate on. + </para> + + </sect3> + + <sect3> + <title>De-multiplexing SMB Requests</title> + + <para> + De-multiplexing of SMB requests requires knowledge of SMB state information, + all of which must be held by the front-end <emphasis>virtual</emphasis> server. + This is a perplexing and complicated problem to solve. + </para> + + <para> + Windows XP and later have changed semantics so state information (vuid, tid, fid) + must match for a successful operation. This makes things simpler than before and is a + positive step forward. + </para> + + <para> + SMB requests are sent by vuid to their associated server. No code exists today to + affect this solution. This problem is conceptually similar to the problem of + correctly handling requests from multiple requests from Windows 2000 + Terminal Server in Samba. + </para> + + <para> + One possibility is to start by exposing the server pool to clients directly. + This could eliminate the de-multiplexing step. + </para> + + </sect3> + + <sect3> + <title>The Distributed File System Challenge</title> + + <para> +<indexterm><primary>Distributed File Systems</primary></indexterm> + There exists many distributed file systems for UNIX and Linux. + </para> + + <para> + Many could be adopted to backend our cluster, so long as awareness of SMB + semantics is kept in mind (share modes, locking and oplock issues in particular). + Common free distributed file systems include: +<indexterm><primary>NFS</primary></indexterm> +<indexterm><primary>AFS</primary></indexterm> +<indexterm><primary>OpenGFS</primary></indexterm> +<indexterm><primary>Lustre</primary></indexterm> + </para> + + <itemizedlist> + <listitem><para>NFS</para></listitem> + <listitem><para>AFS</para></listitem> + <listitem><para>OpenGFS</para></listitem> + <listitem><para>Lustre</para></listitem> + </itemizedlist> + + <para> + The server pool (cluster) can use any distributed file system backend if all SMB + semantics are performed within this pool. + </para> + + </sect3> + + <sect3> + <title>Restrictive Constraints on Distributed File Systems</title> + + <para> + Where a clustered server provides purely SMB services, oplock handling + may be done within the server pool without imposing a need for this to + be passed to the backend file system pool. + </para> + + <para> + On the other hand, where the server pool also provides NFS or other file services, + it will be essential that the implementation be oplock aware so it can + interoperate with SMB services. This is a significant challenge today. A failure + to provide this will result in a significant loss of performance that will be + sorely noted by users of Microsoft Windows clients. + </para> + + <para> + Last, all state information must be shared across the server pool. + </para> + + </sect3> + + <sect3> + <title>Server Pool Communications</title> + + <para> + Most backend file systems support POSIX file semantics. This makes it difficult + to push SMB semantics back into the file system. POSIX locks have different properties + and semantics from SMB locks. + </para> + + <para> + All <command>smbd</command> processes in the server pool must of necessity communicate + very quickly. For this, the current <parameter>tdb</parameter> file structure that Samba + uses is not suitable for use across a network. Clustered <command>smbd</command>'s must use something else. + </para> + + </sect3> + + <sect3> + <title>Server Pool Communications Demands</title> + + <para> + High speed inter-server communications in the server pool is a design prerequisite + for a fully functional system. Possibilities for this include: + </para> + + <itemizedlist> + <listitem><para> + Proprietary shared memory bus (example: Myrinet or SCI [Scalable Coherent Interface]). + These are high cost items. + </para></listitem> + + <listitem><para> + Gigabit ethernet (now quite affordable). + </para></listitem> + + <listitem><para> + Raw ethernet framing (to bypass TCP and UDP overheads). + </para></listitem> + </itemizedlist> + + <para> + We have yet to identify metrics for performance demands to enable this to happen + effectively. + </para> + + </sect3> + + <sect3> + <title>Required Modifications to Samba</title> + + <para> + Samba needs to be significantly modified to work with a high-speed server inter-connect + system to permit transparent fail-over clustering. + </para> + + <para> + Particular functions inside Samba that will be affected include: + </para> + + <itemizedlist> + <listitem><para> + The locking database, oplock notifications, + and the share mode database. + </para></listitem> + + <listitem><para> + Failure semantics need to be defined. Samba behaves the same way as Windows. + When oplock messages fail, a file open request is allowed, but this is + potentially dangerous in a clustered environment. So how should inter-server + pool failure semantics function and how should this be implemented? + </para></listitem> + + <listitem><para> + Should this be implemented using a point-to-point lock manager, or can this + be done using multicast techniques? + </para></listitem> + + </itemizedlist> + + </sect3> + </sect2> + + <sect2> + <title>A Simple Solution</title> + + <para> + Allowing fail-over servers to handle different functions within the exported file system + removes the problem of requiring a distributed locking protocol. + </para> + + <para> + If only one server is active in a pair, the need for high speed server interconnect is avoided. + This allows the use of existing high availability solutions, instead of inventing a new one. + This simpler solution comes at a price &smbmdash; the cost of which is the need to manage a more + complex file name space. Since there is now not a single file system, administrators + must remember where all services are located &smbmdash; a complexity not easily dealt with. + </para> + + <para> + The <emphasis>virtual server</emphasis> is still needed to redirect requests to backend + servers. Backend file space integrity is the responsibility of the administrator. + </para> + + </sect2> + + <sect2> + <title>High Availability Server Products</title> + + <para> + Fail-over servers must communicate in order to handle resource fail-over. This is essential + for high availability services. The use of a dedicated heartbeat is a common technique to + introduce some intelligence into the fail-over process. This is often done over a dedicated + link (LAN or serial). + </para> + + <para> +<indexterm><primary>SCSI</primary></indexterm> + Many fail-over solutions (like Red Hat Cluster Manager, as well as Microsoft Wolfpack) + can use a shared SCSI of Fiber Channel disk storage array for fail-over communication. + Information regarding Red Hat high availability solutions for Samba may be obtained from: + <ulink url="http://www.redhat.com/docs/manuals/enterprise/RHEL-AS-2.1-Manual/cluster-manager/s1-service-samba.html">www.redhat.com.</ulink> + </para> + + <para> + The Linux High Availability project is a resource worthy of consultation if your desire is + to build a highly available Samba file server solution. Please consult the home page at + <ulink url="http://www.linux-ha.org/">www.linux-ha.org/.</ulink> + </para> + + <para> + Front-end server complexity remains a challenge for high availability as it needs to deal + gracefully with backend failures, while at the same time it needs to provide continuity of service + to all network clients. + </para> + + </sect2> + + <sect2> + <title>MS-DFS: The Poor Man's Cluster</title> + + <para> +<indexterm><primary>MS-DFS</primary></indexterm> +<indexterm><primary>DFS</primary><see>MS-DFS, Distributed File Systems</see></indexterm> + MS-DFS links can be used to redirect clients to disparate backend servers. This pushes + complexity back to the network client, something already included by Microsoft. + MS-DFS creates the illusion of a simple, continuous file system name space, that even + works at the file level. + </para> + + <para> + Above all, at the cost of complexity of management, a distributed (pseudo-cluster) can + be created using existing Samba functionality. + </para> + + </sect2> + + <sect2> + <title>Conclusions</title> + + <itemizedlist> + <listitem><para>Transparent SMB clustering is hard to do!</para></listitem> + <listitem><para>Client fail-over is the best we can do today.</para></listitem> + <listitem><para>Much more work is needed before a practical and manageable high + availability transparent cluster solution will be possible.</para></listitem> + <listitem><para>MS-DFS can be used to create the illusion of a single transparent cluster.</para></listitem> + </itemizedlist> + + </sect2> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-IDMAP.xml b/docs/Samba3-HOWTO/TOSHARG-IDMAP.xml new file mode 100644 index 0000000000..0ea50280a7 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-IDMAP.xml @@ -0,0 +1,985 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="idmapper"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>Identity Mapping (IDMAP)</title> + +<para> +<indexterm><primary>Windows</primary></indexterm> +<indexterm><primary>interoperability</primary></indexterm> +<indexterm><primary>IDMAP</primary></indexterm> +<indexterm><primary>Windows Security Identifiers</primary><see>SID</see></indexterm> +<indexterm><primary>SID</primary></indexterm> +<indexterm><primary>UID</primary></indexterm> +<indexterm><primary>GID</primary></indexterm> +The Microsoft Windows operating system has a number of features that impose specific challenges +to interoperability with operating system on which Samba is implemented. This chapter deals +explicitly with the mechanisms Samba-3 (version 3.0.8 and later) uses to overcome one of the +key challenges in the integration of Samba servers into an MS Windows networking environment. +This chapter deals with Identify Mapping (IDMAP) of Windows Security Identifers (SIDs) +to UNIX UIDs and GIDs. +</para> + +<para> +To ensure good sufficient coverage each possible Samba deployment type will be discussed. +This is followed by an overview of how the IDMAP facility may be implemented. +</para> + +<para> +<indexterm><primary>network client</primary></indexterm> +The IDMAP facility is usually of concern where more than one Samba server (or Samba network client) +is installed in the one Domain. Where there is a single Samba server do not be too concerned regarding +the IDMAP infrastructure - the default behavior of Samba is nearly always sufficient. +</para> + +<para> +<indexterm><primary>one domain</primary></indexterm> +The use of IDMAP is important where the Samba server will be accessed by workstations or servers from +more than one domain, in which case it is important to run winbind so it can handle the resolution (ID mapping) +of foreign SIDs to local UNIX UIDs and GIDs. +</para> + +<para> +<indexterm><primary>winbindd</primary></indexterm> +The use of the IDMAP facility requires that the <command>winbindd</command> be executed on Samba start-up. +</para> + +<sect1> +<title>Samba Server Deployment Types and IDMAP</title> + +<para> +<indexterm><primary>Server Types</primary></indexterm> +There are four (4) basic server deployment types, as documented in <link linkend="ServerType">the chapter +on Server Types and Security Modes</link>. +</para> + + <sect2> + <title>Stand-Alone Samba Server</title> + + <para> + <indexterm><primary>stand-alone server</primary></indexterm> + <indexterm><primary>Active Directory</primary></indexterm> + <indexterm><primary>NT4 Domain</primary></indexterm> + A stand-alone Samba server is an implementation that is not a member of a Windows NT4 Domain, + a Windows 200X Active Directory Domain, or of a Samba Domain. + </para> + + <para> + <indexterm><primary>IDMAP</primary></indexterm> + <indexterm><primary>identity</primary></indexterm> + By definition, this means that users and groups will be created and controlled locally and + the identity of a network user must match a local UNIX/Linux user login. The IDMAP facility + is therefore of little to no interest, winbind will not be necessary, and the IDMAP facility + will not be relevant or of interest. + </para> + + </sect2> + + <sect2> + <title>Domain Member Server or Domain Member Client</title> + + <para> + <indexterm><primary>PDC</primary></indexterm> + <indexterm><primary>BDC</primary></indexterm> + <indexterm><primary>NT4</primary></indexterm> + <indexterm><primary>SID</primary></indexterm> + <indexterm><primary>Active Directory</primary></indexterm> + Samba-3 can act as a Windows NT4 PDC or BDC thereby providing domain control protocols that + are compatible with Windows NT4. Samba-3 file and print sharing protocols are compatible with + all version of Microsoft Windows products. Windows NT4, as with Microsoft Active Directory, + extensively makes use of Windows security identifiers (SIDs). + </para> + + <para> + <indexterm><primary>MS Windows SID</primary></indexterm> + <indexterm><primary>UID</primary></indexterm> + <indexterm><primary>GID</primary></indexterm> + Samba-3 Domain Member servers and clients must interact correctly with MS Windows SIDs. Incoming + Windows SIDs must be translated to local UNIX UIDs and GIDs. Outgoing information from the Samba + server must provide to MS Windows clients and servers appropriate SIDs. + </para> + + <para> + <indexterm><primary>ADS</primary></indexterm> + <indexterm><primary>winbind</primary></indexterm> + A Samba member of a Windows networking domain (NT4-style or ADS) can be configured to handle + identity mapping in a variety of ways. The mechanism is will use depends on whether or not + the <command>winbindd</command> daemon is used, and how the winbind functionality is configured. + The configuration options are briefly described here: + </para> + + <variablelist> + <varlistentry><term>Winbind is not used, users and groups are local: &smbmdash; </term> + <listitem> + <para> + Where <command>winbindd</command> is not used Samba (<command>smbd</command>) + uses the underlying UNIX/Linux mechanisms to resolve the identity of incoming + network traffic. This will be done using the LoginID (account name) in the + session setup request and passing it to the getpwnam() system function call. + This call is implemented using the name service switch (NSS) mechanism on + modern UNIX/Linux systems. By saying <quote>users and groups are local</quote> + we are implying that they are stored only on the local system, in the + <filename>/etc/passwd</filename> and <filename>/etc/group</filename> respectively. + </para> + + <para> + For example, if an incoming SessionSetupAndX request is owned by the user + <constant>BERYLIUM\WambatW</constant>, a system call will be made to look up + the user <constant>WambatW</constant> in the <filename>/etc/passwd</filename> + file. + </para> + + <para> + This configuration may be used with stand-alone Samba servers, Domain Member + servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd + or a tdbsam based Samba passdb backend. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Winbind is not used, users and groups resolved via NSS: &smbmdash; </term> + <listitem> + <para> + In this situation user and group accounts are treated as if they are local + accounts, the only way in which this differs from having local accounts is + that the accounts are stored in a repository that can be shared. In practice + this means that they will reside in either a NIS type database or else in LDAP. + </para> + + <para> + This configuration may be used with stand-alone Samba servers, Domain Member + servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd + or a tdbsam based Samba passdb backend. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Winbind/NSS with the default local IDMAP table: &smbmdash; </term> + <listitem> + <para> + There are many sites that require only a simple Samba server, or a single Samba + server that is a member of a Windows NT4 Domain or an ADS Domain. A typical example + is an appliance like file server on which no local accounts are configured and + winbind is used to obtain account credentials from the domain controllers for the + domain. The domain control can be provided by Samba-3, MS Windows NT4 or MS Windows + Active Directory. + </para> + + <para> + Winbind is a great convenience in this situation. All that is needed is a range of + UID numbers and GID numbers that can be defined in the &smb.conf; file, the + <filename>/etc/nsswitch.conf</filename> file is configured to use <command>winbind</command> + which does all the difficult work of mapping incoming SIDs to appropriate UIDs and GIDs. + The SIDs are allocated a UID/GID in the order in which winbind receives them. + </para> + + <para> + This configuration is not convenient or practical in sites that have more than one + Samba server and that require the same UID or GID for the same user or group across + all servers. One of the hazards of this method is that in the event that the winbind + IDMAP file may become corrupted or lost, the repaired or rebuilt IDMAP file may allocate + UIDs and GIDs to differing users and groups from what was there previously with the + result that MS Windows files that are stored on the Samba server may now not belong to + to rightful owner. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Winbind/NSS uses RID based IDMAP: &smbmdash; </term> + <listitem> + <para> + <indexterm><primary>RID</primary></indexterm> + <indexterm><primary>idmap_rid</primary></indexterm> + <indexterm><primary>ADS</primary></indexterm> + <indexterm><primary>LDAP</primary></indexterm> + The IDMAP_RID facility is new to Samba version 3.0.8. It was added to make life easier + for a number of sites that are committed to use of MS ADS, who do not want to apply + an ADS schema extension, and who do not wish to install an LDAP directory server just for + the purpose of maintaining an IDMAP table. If you have a single ADS domain (not a forest of + domains, and not multiple domain trees) and you want a simple cookie-cutter solution to the + IDMAP table problem, then IDMAP_RID is an obvious choice. + </para> + + <para> + <indexterm><primary>idmap_rid</primary></indexterm> + <indexterm><primary>idmap uid</primary></indexterm> + <indexterm><primary>idmap gid</primary></indexterm> + <indexterm><primary>RID</primary></indexterm> + <indexterm><primary>SID</primary></indexterm> + <indexterm><primary>UID</primary></indexterm> + <indexterm><primary>idmap backend</primary></indexterm> + This facility requires the allocation of the <parameter>idmap uid</parameter> and the + <parameter>idmap gid</parameter> ranges, and within the <parameter>idmap uid</parameter> + it is possible to allocate a sub-set of this range for automatic mapping of the relative + identifier (RID) portion of the SID directly to the base of the UID plus the RID value. + For example, if the <parameter>idmap uid</parameter> range is <constant>1000-100000000</constant> + and the <parameter>idmap backend = idmap_rid:DOMAIN_NAME=1000-50000000</parameter>, and + a SID is encountered that has the value <constant>S-1-5-21-34567898-12529001-32973135-1234</constant>, + the resulting UID will be <constant>1000 + 1234 = 2234</constant>. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Winbind with an NSS/LDAP backend based IDMAP facility: &smbmdash; </term> + <listitem> + <para> + <indexterm><primary>Domain Member</primary></indexterm> + In this configuration <command>winbind</command> resolved SIDs to UIDs and GIDs from + the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter> ranges specified + in the &smb.conf; file, but instead of using a local winbind IDMAP table it is stored + in an LDAP directory so that all Domain Member machines (clients and servers) can share + a common IDMAP table. + </para> + + <para> + <indexterm><primary>idmap backend</primary></indexterm> + It is important that all LDAP IDMAP clients use only the master LDAP server as the + <parameter>idmap backend</parameter> facility in the &smb.conf; file does not correctly + handle LDAP redirects. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Winbind with NSS to resolve UNIX/Linux user and group IDs: &smbmdash; </term> + <listitem> + <para> + The use of LDAP as the passdb backend is a smart solution for PDC, BDC as well as for + Domain Member servers. It is a neat method for assuring that UIDs, GIDs and the matching + SIDs will be consistent across all servers. + </para> + + <para> + <indexterm><primary>LDAP</primary></indexterm> + <indexterm><primary>PADL</primary></indexterm> + The use of the LDAP based passdb backend requires use of the PADL nss_ldap utility, or + an equivalent. In this situation winbind is used to handle foreign SIDs; ie: SIDs from + stand-alone Windows clients (i.e.: not a member of our domain) as well as SIDs from + another domain. The foreign UID/GID is mapped from allocated ranges (idmap uid and idmap gid) + in precisely the same manner as when using winbind with a local IDMAP table. + </para> + + <para> + <indexterm><primary>nss_ldap</primary></indexterm> + <indexterm><primary>AD4UNIX</primary></indexterm> + <indexterm><primary>MMC</primary></indexterm> + The nss_ldap tool set can be used to access UIDs and GIDs via LDAP as well as via Active + Directory. In order to use Active Directory it is necessary to modify the ADS schema by + installing either the AD4UNIX schema extension or else use the Microsoft Services for UNIX + version 3.5 of later to extend the ADS schema so it maintains UNIX account credentials. + Where the ADS schema is extended a Microsoft Management Console (MMC) snap-in in also + installed to permit the UNIX credentials to be set and managed from the ADS User and Computer + management tool. Each account must be separately UNIX enabled before the UID and GID data can + be used by Samba. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </sect2> + + <sect2> + <title>Primary Domain Controller</title> + + <para> + <indexterm><primary>domain security</primary></indexterm> + <indexterm><primary>SID</primary></indexterm> + <indexterm><primary>RID</primary></indexterm> + <indexterm><primary>algorithmic mapping</primary></indexterm> + Microsoft Windows domain security systems generate the user and group security identifier (SID) as part + of the process of creation of an account. Windows does not have a concept of the UNIX UID or a GID, rather + it has its own type of security descriptor. When Samba is used as a Domain Controller, it provides a method + of producing a unique SID for each user and group. Samba generates a machine and a domain SID to which it + adds a relative identifier (RID) that is calculated algorithmically from a base value that can be specified + in the &smb.conf; file, plus twice (2X) the UID or GID. This method is called <quote>algorithmic mapping</quote>. + </para> + + <para> + <indexterm><primary>RID base</primary></indexterm> + For example, a user has a UID of 4321, and the algorithmic RID base has a value of 1000, the RID will + be <constant>1000 + (2 x 4321) = 9642</constant>. Thus, if the domain SID is + <constant>S-1-5-21-89238497-92787123-12341112</constant>, the resulting SID is + <constant>S-1-5-21-89238497-92787123-12341112-9642</constant>. + </para> + + <para> + <indexterm><primary>on-the-fly</primary></indexterm> + The foregoing type SID is produced by Samba as an automatic function and is either produced on-the-fly + (as in the case when using a <parameter>passdb backend = [tdbsam | smbpasswd]</parameter>, or may be stored + as a permanent part of an account in an LDAP based ldapsam. + </para> + + <para> + <indexterm><primary>SFU 3.5</primary></indexterm> + MS Active Directory Server (ADS) uses a directory schema that can be extended to accommodate additional + account attributes such as UIDs and GIDs. The installation of Microsoft Service for UNIX 3.5 will expand + the normal ADS schema to include UNIX account attributes. These must of course be managed separately + through a snap-in module to the normal ADS account management MMC interface. + </para> + + <para> + <indexterm><primary>PDC</primary></indexterm> + Security identifiers used within a domain must be managed to avoid conflict and to preserve itegrity. + In an NT4 domain context that PDC manages the distribution of all security credentials to the backup + domain controllers. At this time the only passdb backend for a Samba domain controller that is suitable + for such information is an LDAP backend. + </para> + + </sect2> + + <sect2> + <title>Backup Domain Controller</title> + + <para> + <indexterm><primary>BDC</primary></indexterm> + Backup Domain Controllers (BDCs) have read-only access to security credentials that are stored in LDAP. + Changes in user or group account information are passed by the BDC to the PDC. Only the PDC can write + changes to the directory. + </para> + + <para> + IDMAP information can however be written directly to the LDAP server so long as all domain controllers + have access to the master (writable) LDAP server. Samba-3 at this time does not handle LDAP redirects + in the IDMAP backend. This means that it is is unsafe to use a slave (replicate) LDAP server with + the IDMAP facility. + </para> + + </sect2> + +</sect1> + +<sect1> +<title>Examples of IDMAP Backend Usage</title> + +<para> +<indexterm><primary>Domain Member Server</primary><see>DMS</see></indexterm> +<indexterm><primary>Domain Member Client</primary><see>DMC</see></indexterm> +<indexterm><primary>DMS</primary></indexterm> +<indexterm><primary>DMC</primary></indexterm> +Anyone who wishes to use <command>winbind</command> will find the following example configurations helpful. +Remember that in the majority of cases <command>winbind</command> is of primary interest for use with +Domain Member Servers (DMSs) and Domain Member Clients (DMCs). +</para> + + <sect2> + <title>Default Winbind TDB</title> + + <para> + Two common configurations are used: + </para> + + <itemizedlist> + <listitem><para> + Networks that have an NT4 PDC (with or without BDCs) or a Samba PDC (with or without BDCs). + </para></listitem> + + <listitem><para> + Networks that use MS Windows 200X ADS. + </para></listitem> + </itemizedlist> + + <sect3> + <title>NT4 Style Domains (includes Samba Domains)</title> + + <para> + The following is a simple example of an NT4 DMS &smb.conf; file that shows only the global section. +<screen> +#Global parameters +[global] + workgroup = MEGANET2 + security = DOMAIN + idmap uid = 10000-20000 + idmap gid = 10000-20000 + template primary group = "Domain Users" + template shell = /bin/bash +</screen> + </para> + + <para> + <indexterm><primary>winbind</primary></indexterm> + <indexterm><primary>/etc/nsswitch.conf</primary></indexterm> + The use of <command>winbind</command> requires configuration of NSS. Edit the <filename>/etc/nsswitch.conf</filename> + so it includes the following entries: +<screen> +... +passwd: files winbind +shadow: files winbind +group: files winbind +... +hosts: files wins +... +</screen> + </para> + + <para> + The creation of the DMS requires the following steps: + </para> + + <procedure> + <step><para> + Create or install and &smb.conf; file with the above configuration. + </para></step> + + <step><para> + Execute: +<screen> +&rootprompt; net rpc join -UAdministrator%password +Joined domain MEGANET2. +</screen> + <indexterm><primary>join</primary></indexterm> + The success or failure of the join can be confirmed with the following command: +<screen> +&rootprompt; net rpc testjoin +Join to 'MIDEARTH' is OK +</screen> + A failed join would report an error message like the following: + <indexterm><primary>failed join</primary></indexterm> +<screen> +&rootprompt; net rpc testjoin +[2004/11/05 16:34:12, 0] utils/net_rpc_join.c:net_rpc_join_ok(66) +Join to domain 'MEGANET2' is not valid +</screen> + </para></step> + + <step><para> + Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown. + </para></step> + </procedure> + + </sect3> + + <sect3> + <title>ADS Domains</title> + + <para> + <indexterm><primary>domain join</primary></indexterm> + The procedure for joining and ADS domain is similar to the NT4 domain join, except the &smb.conf; file + will have the following contents: +<screen> +# Global parameters +[global] + workgroup = BUTTERNET + netbios name = GARGOYLE + realm = BUTTERNET.BIZ + security = ADS + template shell = /bin/bash + idmap uid = 500-10000000 + idmap gid = 500-10000000 + winbind use default domain = Yes + winbind nested groups = Yes + printer admin = "BUTTERNET\Domain Admins" +</screen> + </para> + + <para> + <indexterm><primary>KRB</primary></indexterm> + <indexterm><primary>kerberos</primary></indexterm> + <indexterm><primary>/etc/krb5.conf</primary></indexterm> + <indexterm><primary>MIT</primary></indexterm> + <indexterm><primary>MIT kerberos</primary></indexterm> + <indexterm><primary>Heimdal</primary></indexterm> + <indexterm><primary>Heimdal kerberos</primary></indexterm> + ADS DMS operation requires use of kerberos (KRB). For this to work the <filename>krb5.conf</filename> + must be configured. The exact requirements depends on which version of MIT or Heimdal kerberos is being + used. It is sound advice to use only the latest version, which at this time are MIT kerberos version + 1.3.5 and Heimdal 0.61. + </para> + + <para> + The creation of the DMS requires the following steps: + </para> + + <procedure> + <step><para> + Create or install and &smb.conf; file with the above configuration. + </para></step> + + <step><para> + Edit the <filename>/etc/nsswitch.conf</filename> file as shown above. + </para></step> + + <step><para> + Execute: + <indexterm><primary>net ads join</primary></indexterm> +<screen> +&rootprompt; net ads join -UAdministrator%password +Joined domain BUTTERNET. +</screen> + The success or failure of the join can be confirmed with the following command: +<screen> +&rootprompt; net ads testjoin +Using short domain name -- BUTTERNET +Joined 'GARGOYLE' to realm 'BUTTERNET.BIZ' +</screen> + </para> + + <para> + An invalid or failed join can be detected by executing: +<screen> +&rootprompt; net ads testjoin +GARGOYLE$@'s password: +[2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186) + ads_connect: No results returned +Join to domain is not valid +</screen> + <indexterm><primary>error message</primary></indexterm> + The specific error message may differ from the above as it depends on the type of failure that + may have occured. Increase the <parameter>log level</parameter> to 10, repeat the above test + and then examine the log files produced to identify the nature of the failure. + </para></step> + + <step><para> + Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown. + </para></step> + + </procedure> + + </sect3> + </sect2> + + <sect2> + <title>IDMAP_RID with Winbind</title> + + <para> + <indexterm><primary>idmap_rid</primary></indexterm> + <indexterm><primary>SID</primary></indexterm> + <indexterm><primary>RID</primary></indexterm> + <indexterm><primary>IDMAP</primary></indexterm> + The <command>idmap_rid</command> facility is a new tool that, unlike native winbind, creates a + predictable mapping of MS Windows SIDs to UNIX UIDs and GIDs. The key benefit of this method + of implementing the Samba IDMAP facility is that it eliminates the need to store the IDMAP data + in a central place. The down-side is that it can be used only within a single ADS Domain and + is not compatible with trusted domain implementations. + </para> + + <para> + <indexterm><primary>SID</primary></indexterm> + <indexterm><primary>allow trusted domains</primary></indexterm> + <indexterm><primary>idmap uid</primary></indexterm> + <indexterm><primary>idmap gid</primary></indexterm> + This alternate method of SID to UID/GID mapping can be achieved uses the idmap_rid + plug-in. This plug-in uses the RID of the user SID to derive the UID and GID by adding the + RID to a base value specified. This utility requires that the parameter + <quote>allow trusted domains = No</quote> must be specified, as it is not compatible + with multiple domain environments. The <parameter>idmap uid</parameter> and + <parameter>idmap gid</parameter> ranges must be specified. + </para> + + <para> + <indexterm><primary>idmap_rid</primary></indexterm> + <indexterm><primary>realm</primary></indexterm> + The idmap_rid facility can be used both for NT4/Samba style domains as well as with Active Directory. + To use this with an NT4 Domain the <parameter>realm</parameter> is not used, additionally the + method used to join the domain uses the <constant>net rpc join</constant> process. + </para> + + <para> + An example &smb.conf; file for and ADS domain environment is shown here: +<screen> +# Global parameters +[global] + workgroup = KPAK + netbios name = BIGJOE + realm = CORP.KPAK.COM + server string = Office Server + security = ADS + allow trusted domains = No + idmap backend = idmap_rid:KPAK=500-100000000 + idmap uid = 500-100000000 + idmap gid = 500-100000000 + template shell = /bin/bash + winbind use default domain = Yes + winbind enum users = No + winbind enum groups = No + winbind nested groups = Yes + printer admin = "Domain Admins" +</screen> + </para> + + <para> + <indexterm><primary>large domain</primary></indexterm> + <indexterm><primary>Active Directory</primary></indexterm> + <indexterm><primary>response</primary></indexterm> + <indexterm><primary>getent</primary></indexterm> + In a large domain with many users it is imperative to disable enumeration of users and groups. + For examplem, at a site that has 22,000 users in Active Directory the winbind based user and + group resolution is unavailable for nearly 12 minutes following first start-up of + <command>winbind</command>. Disabling of such enumeration resulted in instantaneous response. + The disabling of user and group enumeration means that it will not be possible to list users + or groups using the <command>getent passwd</command> and <command>getent group</command> + commands. It will be possible to perform the lookup for individual users, as shown in the procedure + below. + </para> + + <para> + <indexterm><primary>NSS</primary></indexterm> + <indexterm><primary>/etc/nsswitch.conf</primary></indexterm> + The use of this tool requires configuration of NSS as per the native use of winbind. Edit the + <filename>/etc/nsswitch.conf</filename> so it has the following parameters: +<screen> +... +passwd: files winbind +shadow: files winbind +group: files winbind +... +hosts: files wins +... +</screen> + </para> + + <para> + The following procedure can be used to utilize the idmap_rid facility: + </para> + + <procedure> + <step><para> + Create or install and &smb.conf; file with the above configuration. + </para></step> + + <step><para> + Edit the <filename>/etc/nsswitch.conf</filename> file as shown above. + </para></step> + + <step><para> + Execute: +<screen> +&rootprompt; net ads join -UAdministrator%password +Using short domain name -- KPAK +Joined 'BIGJOE' to realm 'CORP.KPAK.COM' +</screen> + </para> + + <para> + <indexterm><primary>failed join</primary></indexterm> + An invalid or failed join can be detected by executing: +<screen> +&rootprompt; net ads testjoin +BIGJOE$@'s password: +[2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186) + ads_connect: No results returned +Join to domain is not valid +</screen> + The specific error message may differ from the above as it depends on the type of failure that + may have occured. Increase the <parameter>log level</parameter> to 10, repeat the above test + and then examine the log files produced to identify the nature of the failure. + </para></step> + + <step><para> + Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown. + </para></step> + + <step><para> + Validate the operation of this configuration by executing: + <indexterm><primary></primary></indexterm> +<screen> +&rootprompt; getent passwd administrator +administrator:x:1000:1013:Administrator:/home/BE/administrator:/bin/bash +</screen> + </para></step> + </procedure> + + </sect2> + + <sect2> + <title>IDMAP Storage in LDAP using Winbind</title> + + <para> + <indexterm><primary>ADAM</primary></indexterm> + <indexterm><primary>ADS</primary></indexterm> + The storage of IDMAP information in LDAP can be used with both NT4/Samba-3 style domains as well as + with ADS domains. OpenLDAP is a commonly used LDAP server for this purpose, although any standards + complying LDAP server can be used. It is therefore possible to deploy this IDMAP configuration using + the Sun iPlanet LDAP server, Novell eDirectory, Microsoft ADS plus ADAM, and so on. + </para> + + <para> + The following example is for an ADS style domain: + </para> + + <para> +<screen> +# Global parameters +[global] + workgroup = SNOWSHOW + netbios name = GOODELF + realm = SNOWSHOW.COM + server string = Samba Server + security = ADS + log level = 1 ads:10 auth:10 sam:10 rpc:10 + ldap admin dn = cn=Manager,dc=SNOWSHOW,dc=COM + ldap idmap suffix = ou=Idmap + ldap suffix = dc=SNOWSHOW,dc=COM + idmap backend = ldap:ldap://ldap.snowshow.com + idmap uid = 150000-550000 + idmap gid = 150000-550000 + template shell = /bin/bash + winbind use default domain = Yes +</screen> + </para> + + <para> + <indexterm><primary>realm</primary></indexterm> + In the case of an NT4 or Samba-3 style Domain the <parameter>realm</parameter> is not used and the + command used to join the domain is: <command>net rpc join</command>. The above example also demonstrates + advanced error reporting techniques that are documented in <link linkend="dbglvl">the chapter called + Reporting Bugs</link>. + </para> + + <para> + <indexterm><primary>MIT kerberos</primary></indexterm> + <indexterm><primary>Heimdal kerberos</primary></indexterm> + <indexterm><primary>/etc/krb5.conf</primary></indexterm> + Where MIT kerberos is installed (version 1.3.4 or later) edit the <filename>/etc/krb5.conf</filename> + file so it has the following contents: +<screen> +[logging] + default = FILE:/var/log/krb5libs.log + kdc = FILE:/var/log/krb5kdc.log + admin_server = FILE:/var/log/kadmind.log + +[libdefaults] + default_realm = SNOWSHOW.COM + dns_lookup_realm = false + dns_lookup_kdc = true + +[appdefaults] + pam = { + debug = false + ticket_lifetime = 36000 + renew_lifetime = 36000 + forwardable = true + krb4_convert = false + } +</screen> + </para> + + <para> + Where Heimdal kerberos is installed edit the <filename>/etc/krb5.conf</filename> + file so it is either empty (i.e.: no contents) or it has the following contents: +<screen> +[libdefaults] + default_realm = SNOWSHOW.COM + clockskew = 300 + +[realms] + SNOWSHOW.COM = { + kdc = ADSDC.SHOWSHOW.COM + } + +[domain_realm] + .snowshow.com = SNOWSHOW.COM +</screen> + </para> + + <note><para> + Samba can not use the Heimdal libraries if there is no <filename>/etc/krb5.conf</filename> file. + So long as there is an empty file the Heimdal kerberos libraries will be usable. There is no + need to specify any settings as Samba using the Heimdal libraries can figure this out automatically. + </para></note> + + <para> + Edit the NSS control file <filename>/etc/nsswitch.conf</filename> so it has the following entries: +<screen> +... +passwd: files ldap +shadow: files ldap +group: files ldap +... +hosts: files wins +... +</screen> + </para> + + <para> + <indexterm><primary>PADL</primary></indexterm> + <indexterm><primary>/etc/ldap.conf</primary></indexterm> + You will need the <ulink url="http://www.padl.com">PADL</ulink> <command>nss_ldap</command> + tool set for this solution. Configure the <filename>/etc/ldap.conf</filename> file so it has + the information needed. The following is an example of a working file: +<screen> +host 192.168.2.1 +base dc=snowshow,dc=com +binddn cn=Manager,dc=snowshow,dc=com +bindpw not24get + +pam_password exop + +nss_base_passwd ou=People,dc=snowshow,dc=com?one +nss_base_shadow ou=People,dc=snowshow,dc=com?one +nss_base_group ou=Groups,dc=snowshow,dc=com?one +ssl no +</screen> + </para> + + <para> + The following procedure may be followed to affect a working configuration: + </para> + + <procedure> + <step><para> + Configure the &smb.conf; file as shown above. + </para></step> + + <step><para> + Create the <filename>/etc/krb5.conf</filename> file following the indications above. + </para></step> + + <step><para> + Configure the <filename>/etc/nsswitch.conf</filename> file as shown above. + </para></step> + + <step><para> + Download, build and install the PADL nss_ldap tool set. Configure the + <filename>/etc/ldap.conf</filename> file as shown above. + </para></step> + + <step><para> + Configure an LDAP server, initialize the directory with the top level entries needed by IDMAP + as shown in the following LDIF file: +<screen> +dn: dc=snowshow,dc=com +objectClass: dcObject +objectClass: organization +dc: snowshow +o: The Greatest Snow Show in Singapore. +description: Posix and Samba LDAP Identity Database + +dn: cn=Manager,dc=snowshow,dc=com +objectClass: organizationalRole +cn: Manager +description: Directory Manager + +dn: ou=Idmap,dc=snowshow,dc=com +objectClass: organizationalUnit +ou: idmap +</screen> + </para></step> + + <step><para> + Execute the command to join the Samba Domain Member Server to the ADS domain as shown here: +<screen> +&rootprompt; net ads testjoin +Using short domain name -- SNOWSHOW +Joined 'GOODELF' to realm 'SNOWSHOW.COM' +</screen> + </para></step> + + <step><para> + Store the LDAP server access password in the Samba <filename>secrets.tdb</filename> file as follows: +<screen> +&rootprompt; smbpasswd -w not24get +</screen> + </para></step> + + <step><para> + Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown. + </para></step> + </procedure> + + <para> + <indexterm><primary>diagnostic</primary></indexterm> + Follow the diagnositic procedures shown earlier in this chapter to identify success or failure of the join. + In many cases a failure is indicated by a silent return to the command prompt with no indication of the + reason for failure. + </para> + + </sect2> + + <sect2> + <title>IDMAP and NSS Using LDAP From ADS with RFC2307bis Schema Extension</title> + + <para> + <indexterm><primary>rfc2307bis</primary></indexterm> + <indexterm><primary>schema</primary></indexterm> + The use of this method is messy. The information provided in the following is for guidance only + and is very definitely not complete. This method does work; it is used in a number of large sites + and has an acceptable level of performance. + </para> + + <para> + The following is an example &smb.conf; file: +<screen> +# Global parameters +[global] + workgroup = BOBBY + realm = BOBBY.COM + security = ADS + idmap uid = 150000-550000 + idmap gid = 150000-550000 + template shell = /bin/bash + winbind cache time = 5 + winbind use default domain = Yes + winbind trusted domains only = Yes + winbind nested groups = Yes +</screen> + </para> + + <para> + <indexterm><primary>nss_ldap</primary></indexterm> + The DMS must be joined to the domain using the usual procedure. Additionally, it is necessary + to build and install the PADL nss_ldap tool set. Be sure to build this tool set with the + following: +<screen> +./configure --enable-rfc2307bis --enable-schema-mapping +make install +</screen> + </para> + + <para> + <indexterm><primary>/etc/nsswitch.conf</primary></indexterm> + The following <filename>/etc/nsswitch.conf</filename> file contents are required: +<screen> +... +passwd: files ldap +shadow: files ldap +group: files ldap +... +hosts: files wins +... +</screen> + </para> + + <para> + <indexterm><primary>/etc/ldap.conf</primary></indexterm> + <indexterm><primary>nss_ldap</primary></indexterm> + The <filename>/etc/ldap.conf</filename> file must be configured also. Refer to the PADL documentation + and source code for nss_ldap to specific instructions. + </para> + + <para> + The next step involves preparation on the ADS schema. This is briefly discussed in the remaining + part of this chapter. + </para> + + <sect3> + <title>IDMAP, Active Directory and MS Services for UNIX 3.5</title> + + <para> + <indexterm><primary>SFU</primary></indexterm> + The Microsoft Windows Service for UNIX (SFU) version 3.5 is available for free + <ulink url="http://www.microsoft.com/windows/sfu/">download</ulink> + from the Microsoft Web site. You will need to download this tool and install it following + Microsoft instructions. + </para> + + </sect3> + + <sect3> + <title>IDMAP, Active Directory and AD4UNIX</title> + + <para> + Instructions for obtaining and installing the AD4UNIX tool set can be found from the + <ulink url="http://www.geekcomix.com/cgi-bin/classnotes/wiki.pl?LDAP01/An_Alternative_Approach"> + Geekcomix</ulink> web site. + </para> + + </sect3> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Install.xml b/docs/Samba3-HOWTO/TOSHARG-Install.xml new file mode 100644 index 0000000000..1cec899cdd --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Install.xml @@ -0,0 +1,382 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="install"> +<chapterinfo> + &author.tridge; + &author.jelmer; + &author.jht; + &author.kauer; + &author.danshearer; + <!-- Isn't some of this written by others as well? --> + +</chapterinfo> + +<title>How to Install and Test SAMBA</title> + +<sect1> + <title>Obtaining and Installing Samba</title> + + <para> + Binary packages of Samba are included in almost any Linux or + UNIX distribution. There are also some packages available at + <ulink url="http://samba.org/">the Samba home-page</ulink>. Refer to + the manual of your operating system for details on installing packages + for your specific operating system. + </para> + + <para>If you need to compile Samba from source, check + <link linkend="compiling">How to compile Samba.</link> + </para> + +</sect1> + +<sect1> + <title>Configuring Samba (smb.conf)</title> + + <para> + Samba's configuration is stored in the &smb.conf; file, which + 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 + tools that are available, such as the Web-based interface SWAT, that + is included with Samba. + </para> + + <sect2> + <title>Configuration file syntax</title> + + <para>The &smb.conf; file uses the same syntax as the various old + .ini files in Windows 3.1: Each file consists of various sections, + which are started by putting the section name between brackets ([]) + on a new line. Each contains zero or more key/value-pairs separated by an + equality sign (=). The file is just a plain-text file, so you can + open and edit it with your favorite editing tool.</para> + + <para>Each section in the &smb.conf; file represents a share + on the Samba server. The section <quote>global</quote> is special, since it + contains settings that apply to the whole Samba server and not + to one share in particular.</para> + +<para><link linkend="smbconfminimal">Following example</link> contains a very minimal &smb.conf;. + <indexterm><primary>minimal configuration</primary></indexterm> +</para> + + <smbconfexample id="smbconfminimal"> + <title>A minimal smb.conf</title> + + <smbconfsection name="[global]"/> + <smbconfoption name="workgroup">WKG</smbconfoption> + <smbconfoption name="netbios name">MYNAME</smbconfoption> + <smbconfsection name="[share1]"/> + <smbconfoption name="path">/tmp</smbconfoption> + + <smbconfsection name="[share2]"/> + <smbconfoption name="path">/my_shared_folder</smbconfoption> + <smbconfoption name="comment">Some random files</smbconfoption> + </smbconfexample> + +</sect2> + +<sect2> + <title>Starting Samba</title> + + <para> + Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services. + An example of a service is the Apache Web server for which the daemon is called <command>httpd</command>. In the case of Samba there + are three daemons, two of which are needed as a minimum. + </para> + + <para> + The Samba server is made up of the following daemons: + </para> + + <variablelist> + <varlistentry><term>nmbd</term> + <listitem><para> + <indexterm><primary>smbd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm> + This daemon handles all name registration and resolution requests. It is the primary vehicle involved + in network browsing. It handles all UDP based protocols. The <command>nmbd</command> daemon should + be the first command started as part of the Samba start-up process. + </para></listitem> + </varlistentry> + + <varlistentry><term>smbd</term> + <listitem><para> + <indexterm><primary>nmbd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm> + This daemon handles all TCP/IP based connection services for file and print based operations. It also + manages local authentication. It should be started immediately following the start-up of <command>nmbd</command>. + </para></listitem> + </varlistentry> + + <varlistentry><term>winbindd</term> + <listitem><para> + <indexterm><primary>winbindd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm> + This daemon should be started when Samba is a member of a Windows NT4 or ADS Domain. It is also needed when + Samba has trust relationships with another Domain. The <command>winbindd</command> daemon will check the + &smb.conf; file for the presence of the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter> + parameters. If they are not found <command>winbindd</command> will bail-out and refuse to start. + </para></listitem> + </varlistentry> + </variablelist> + + <para> + When Samba has been packaged by an operating system vendor the start-up process is typically a custom feature of its + integration into the platform as a whole. Please refer to your operating system platform administration manuals for + specific information pertaining to correct management of Samba start-up. + </para> + +</sect2> + +<sect2> + <title>Example Configuration</title> + + <para> + There are sample configuration files in the examples subdirectory in the + distribution. It is suggested you read them carefully so you can see how the options + go together in practice. See the man page for all the options. + It might be worthwhile to start out with the smb.conf.default + configuration file and adapt it to your needs. It contains plenty of + comments. + </para> + + <para> + The simplest useful configuration file would contain something like shown in + <link linkend="simple-example">the next example</link>. + </para> + + <para> + <indexterm><primary>simple configuration</primary></indexterm> + <smbconfexample id="simple-example"> + <title>Another simple smb.conf File</title> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> + +<smbconfsection name="[homes]"/> +<smbconfoption name="guest ok">no</smbconfoption> +<smbconfoption name="read only">no</smbconfoption> + </smbconfexample> + </para> + + <para> + This will allow connections by anyone with an account on the server, using either + their login name or <smbconfsection name="homes"/> as the service name. + (Note: The workgroup that Samba should appear in must also be set. The default + workgroup name is WORKGROUP.) + </para> + + <para> + Make sure you put the &smb.conf; file in the correct place. + </para> + + <para> + For more information about security settings for the + <smbconfsection name="[homes]"/> share please refer to + <link linkend="securing-samba">Securing Samba</link> chapter. + </para> + +<sect3> + <title>Test Your Config File with <command>testparm</command></title> + + <para> + It's important to validate the contents of the &smb.conf; file using the &testparm; program. + If testparm runs correctly, it will list the loaded services. If not, it will give an error message. + Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command: + </para> + + <screen> + &rootprompt; testparm /etc/samba/smb.conf + </screen> + + <para>Testparm will parse your configuration file and report + any unknown parameters or incorrect syntax. </para> + + + + <para> + Always run testparm again whenever the &smb.conf; file is changed! + </para> + +</sect3> +</sect2> + +<sect2> + <title>SWAT</title> + + <para> + <indexterm><primary>swat</primary></indexterm> + SWAT is a Web-based interface that can be used to facilitate the configuration of Samba. + SWAT might not be available in the Samba package that shipped with your platform, + but in a separate package. Please read the SWAT man page + on compiling, installing and configuring SWAT from source. + </para> + + <para> + To launch SWAT, just run your favorite Web browser and point it to + <ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>. + Replace <replaceable>localhost</replaceable> with the name of the computer on which + Samba is running if that is a different computer than your browser. + </para> + + <para> + SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote + machine leaves your connection open to password sniffing as passwords will be sent over the wire in the clear. + </para> + + <para>More information about SWAT can be found in <link linkend="SWAT">corresponding chapter</link>.</para> + +</sect2> + +</sect1> + +<sect1> + <title>List Shares Available on the Server</title> + + <para> + To list shares that are available from the configured Samba server execute the + following command: + </para> + +<para><screen> +&prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput> +</screen></para> + + <para>You should see a list of shares available on your server. If you do not, then + something is incorrectly configured. This method can also be used to see what shares + are available on other SMB servers, such as Windows 2000.</para> + + <para>If you choose user-level security you may find that Samba requests a password + before it will list the shares. See the <command>smbclient</command> man page for details. + You can force it to list the shares without a password by adding the option + <option>-N</option> to the command line. </para> +</sect1> + +<sect1> + <title>Connect with a UNIX Client</title> + + <para> + Enter the following command: +<screen> +&prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput> +</screen></para> + + <para>Typically <replaceable>yourhostname</replaceable> is the name of the host on which &smbd; + has been installed. The <replaceable>aservice</replaceable> is any service that has been defined in the &smb.conf; + file. Try your user name if you just have a <smbconfsection name="[homes]"/> section in the &smb.conf; file.</para> + + <para>Example: If the UNIX host is called <replaceable>bambi</replaceable> and a valid login name + is <replaceable>fred</replaceable>, you would type:</para> + +<para><screen> +&prompt;<userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable></userinput> +</screen></para> +</sect1> + +<sect1> + <title>Connect from a Remote SMB Client</title> + + <para>Now that Samba is working correctly locally, you can try to + access it from other clients. Within a few minutes, the Samba host + should be listed in the Network Neighborhood on all Windows + clients of its subnet. Try browsing the server from another client + or 'mounting' it.</para> + + <para>Mounting disks from a DOS, Windows or OS/2 client can be done by running a command such as:</para> + + <para><screen> +&dosprompt;<userinput>net use d: \\servername\service</userinput> +</screen></para> + + <para>Try printing, e.g.</para> + + <para> +<screen> +&dosprompt;<userinput>net use lpt1: \\servername\spoolservice</userinput> +</screen></para> + +<para> +<screen>&dosprompt;<userinput>print filename</userinput> +</screen></para> +</sect1> + +<sect1> + <title>What If Things Don't Work?</title> + + <para>You might want to read <link linkend="diagnosis">The Samba Checklist</link>. + If you are still stuck, refer to <link linkend="problems">Analyzing and Solving Samba Problems</link> chapter. + Samba has been successfully installed at thousands of sites worldwide. + It is unlikely that your particular problem is unique, so it might be + productive to perform an Internet search to see if someone else has encountered + your problem and has found a way to overcome it.</para> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +The following questions and issues are raised repeatedly on the Samba mailing list. +</para> + +<sect2> + <title>Large Number of smbd Processes</title> + +<para> +Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon, +&smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with Domain Controllers. +</para> + +<para> +If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of + &nmbd; running on your system. If it is running as a WINS server then there will be +two instances &smbmdash; one to handle the WINS requests. +</para> + +<para> +&smbd; handles all connection requests. It spawns a new process for each client +connection made. That is why you may see so many of them, one per client connection. +</para> + +<para> +&winbindd; will run as one or two daemons, depending on whether or not it is being +run in <emphasis>split mode</emphasis> (in which case there will be two instances). +</para> + +</sect2> + + <sect2> + <title>Error Message: open_oplock_ipc</title> + + <para>An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to get local UDP socket + for address 100007f. Error was Cannot assign requested.</quote></para> + + <para>Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback + device is an internal (virtual) network device with the IP address <emphasis>127.0.0.1</emphasis>. + Read your OS documentation for details on how to configure the loopback on your system.</para> + + </sect2> + + <sect2> + <title><quote><errorname>The network name cannot be found</errorname></quote></title> + + <para> + This error can be caused by one of these mis-configurations: + </para> + + <itemizedlist> + <listitem><para>You specified an non-existing path + for the share in &smb.conf;.</para></listitem> + + <listitem><para>The user you are trying to access the share with does not + have sufficient permissions to access the path for + the share. Both read (r) and access (x) should be possible.</para></listitem> + + <listitem><para>The share you are trying to access does not exist.</para></listitem> + </itemizedlist> + + </sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml b/docs/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml new file mode 100644 index 0000000000..0fa90c9cb2 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml @@ -0,0 +1,715 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="integrate-ms-networks"> + +<chapterinfo> + &author.jht; + <pubdate> (Jan 01 2001) </pubdate> +</chapterinfo> + +<title>Integrating MS Windows Networks with Samba</title> + +<para> +<indexterm><primary>NetBIOS</primary></indexterm> +This section deals with NetBIOS over TCP/IP name to IP address resolution. If +your MS Windows clients are not configured to use NetBIOS over TCP/IP, then this +section does not apply to your installation. If your installation +involves the use of +NetBIOS over TCP/IP then this section may help you to resolve networking problems. +</para> + +<note> +<para> +NetBIOS over TCP/IP has nothing to do with NetBEUI. NetBEUI is NetBIOS +over Logical Link Control (LLC). On modern networks it is highly advised +to not run NetBEUI at all. Note also there is no such thing as +NetBEUI over TCP/IP &smbmdash; the existence of such a protocol is a complete +and utter misapprehension. +</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 administrators 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 +its 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 +name resolution and uses TCP port 139 for NetBIOS session services. When NetBIOS over +TCP/IP is disabled on MS Windows 2000 and later clients, then only the TCP port 445 will be +used and the UDP port 137 and TCP port 139 will not. +</para> + +<note> +<para> +When using Windows 2000 or later clients, if NetBIOS over TCP/IP is not disabled, then +the client will use UDP port 137 (NetBIOS Name Service, also known as the Windows Internet +Name Service or WINS), TCP port 139 and TCP port 445 (for actual file and print traffic). +</para> +</note> + +<para> +When NetBIOS over TCP/IP is disabled, the use of DNS is essential. Most installations that +disable NetBIOS over TCP/IP today use MS Active Directory Service (ADS). ADS requires +<indexterm><primary>DNS</primary><secondary>Dynamic</secondary></indexterm> +Dynamic DNS with Service Resource Records (SRV RR) and with Incremental Zone Transfers (IXFR). +<indexterm><primary>DHCP</primary></indexterm> +Use of DHCP with ADS is recommended as a further means of maintaining central control +over the client workstation network configuration. +</para> + +</sect1> + +<sect1> +<title>Name Resolution in a Pure UNIX/Linux World</title> + +<para> +The key configuration files covered in this section are: +</para> + +<itemizedlist> + <listitem><para><filename>/etc/hosts</filename></para></listitem> + <listitem><para><filename>/etc/resolv.conf</filename></para></listitem> + <listitem><para><filename>/etc/host.conf</filename></para></listitem> + <listitem><para><filename>/etc/nsswitch.conf</filename></para></listitem> +</itemizedlist> + +<sect2> +<title><filename>/etc/hosts</filename></title> + +<para> +This file contains a static list of IP addresses and names. +</para> +<para><programlisting> +127.0.0.1 localhost localhost.localdomain +192.168.1.1 bigbox.quenya.org bigbox alias4box +</programlisting></para> + +<para> +The purpose of <filename>/etc/hosts</filename> is to provide a +name resolution mechanism so users do not need to remember +IP addresses. +</para> + +<para> +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). For example, 168.192.1.1. +</para> + +<para> +<indexterm><primary>MAC Addresses</primary></indexterm> +MAC Addresses use 48 bits (or 6 bytes) and are typically represented +as two-digit hexadecimal numbers separated by colons: 40:8e:0a:12:34:56. +</para> + +<para> +Every network interface must have a MAC address. Associated with +a MAC address may be one or more IP addresses. There is no +relationship between an IP address and a MAC address; all such assignments +are arbitrary or discretionary in nature. At the most basic level, all +network communications take place using MAC addressing. Since MAC +addresses must be globally unique and generally remain fixed for +any particular interface, the assignment of an IP address makes sense +from a network management perspective. More than one IP address can +be assigned per MAC address. One address must be the primary IP +address &smbmdash; +this is the address that will be returned in the ARP reply. +</para> + +<para> +When a user or a process wants to communicate with another machine, +the protocol implementation ensures that the <quote>machine name</quote> or <quote>host +name</quote> is resolved to an IP address in a manner that is controlled +by the TCP/IP configuration control files. The file +<filename>/etc/hosts</filename> is one such file. +</para> + +<para> +When the IP address of the destination interface has been +determined, a protocol called ARP/RARP is used to identify +the MAC address of the target interface. ARP stands for Address +Resolution Protocol and is a broadcast-oriented method that +uses User Datagram Protocol (UDP) to send a request to all +interfaces on the local network segment using the all 1s MAC +address. Network interfaces are programmed to respond to two +MAC addresses only; their own unique address and the address +ff:ff:ff:ff:ff:ff. The reply packet from an ARP request will +contain the MAC address and the primary IP address for each +interface. +</para> + +<para> +<indexterm><primary>/etc/hosts</primary></indexterm> +The <filename>/etc/hosts</filename> file is foundational to all +UNIX/Linux TCP/IP installations and as a minimum will contain +the localhost and local network interface IP addresses and the +primary names by which they are known within the local machine. +This file helps to prime the pump so a basic level of name +resolution can exist before any other method of name resolution +becomes available. +</para> + +</sect2> + + +<sect2> +<title><filename>/etc/resolv.conf</filename></title> + +<para> +This file tells the name resolution libraries: +</para> + +<itemizedlist> + <listitem><para>The name of the domain to which the machine + belongs. + </para></listitem> + + <listitem><para>The name(s) of any domains that should be + automatically searched when trying to resolve unqualified + host names to their IP address. + </para></listitem> + + <listitem><para>The name or IP address of available Domain + Name Servers that may be asked to perform name-to-address + translation lookups. + </para></listitem> +</itemizedlist> + +</sect2> + + +<sect2> +<title><filename>/etc/host.conf</filename></title> + + +<para> +<indexterm><primary>/etc/host.conf</primary></indexterm> +<filename>/etc/host.conf</filename> is the primary means by +which the setting in <filename>/etc/resolv.conf</filename> may be effected. It is a +critical configuration file. This file controls the order by +which name resolution may proceed. The typical structure is: +</para> + +<para><programlisting> +order hosts,bind +multi on +</programlisting></para> + +<para> +then both addresses should be returned. Please refer to the +man page for <filename>host.conf</filename> for further details. +</para> + + +</sect2> + + + +<sect2> +<title><filename>/etc/nsswitch.conf</filename></title> + + +<para> +<indexterm><primary>/etc/nsswitch.conf</primary></indexterm> +This file controls the actual name resolution targets. The +file typically has resolver object specifications as follows: +</para> + + +<para><programlisting> +# /etc/nsswitch.conf +# +# Name Service Switch configuration file. +# + +passwd: compat +# Alternative entries for password authentication are: +# passwd: compat files nis ldap winbind +shadow: compat +group: compat + +hosts: files nis dns +# Alternative entries for host name resolution are: +# hosts: files dns nis nis+ hesiod db compat ldap wins +networks: nis files dns + +ethers: nis files +protocols: nis files +rpc: nis files +services: nis files +</programlisting></para> + +<para> +Of course, each of these mechanisms requires that the appropriate +facilities and/or services are correctly configured. +</para> + +<para> +It should be noted that unless a network request/message must be +sent, TCP/IP networks are silent. All TCP/IP communications assume a +principal of speaking only when necessary. +</para> + + +<para> +<indexterm><primary>libnss_wins.so</primary></indexterm> +Starting with version 2.2.0, Samba has Linux support for extensions to +the name service switch infrastructure so 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 (i.e., <userinput>make +nsswitch/libnss_wins.so</userinput>). The resulting library should +then be installed in the <filename>/lib</filename> directory and +the <parameter>wins</parameter> parameter needs to be added to the <quote>hosts:</quote> line in +the <filename>/etc/nsswitch.conf</filename> file. At this point, it +will be possible to ping any MS Windows machine by its NetBIOS +machine name, as long as that machine is within the workgroup to +which both the Samba machine and the MS Windows machine belong. +</para> + +</sect2> +</sect1> + + +<sect1> +<title>Name Resolution as Used within MS Windows Networking</title> + +<para> +MS Windows networking is predicated about the name each machine +is given. This name is known variously (and inconsistently) as +the <quote>computer name,</quote> <quote>machine name,</quote> <quote>networking name,</quote> <quote>netbios name,</quote> +or <quote>SMB name.</quote> All terms mean the same thing with the exception of +<quote>netbios name</quote> that can also apply to the name of the workgroup or the +domain name. The terms <quote>workgroup</quote> and <quote>domain</quote> are really just a +simple name with which the machine is associated. All NetBIOS names +are exactly 16 characters in length. The 16<superscript>th</superscript> character is reserved. +It is used to store a one-byte value that indicates service level +information for the NetBIOS name that is registered. A NetBIOS machine +name is, therefore, registered for each service type that is provided by +the client/server. +</para> + +<para> +<link linkend="uniqnetbiosnames">Unique NetBIOS Names</link> and <link linkend="netbiosnamesgrp">Group Names</link> tables +list typical NetBIOS name/service type registrations. +</para> + +<table frame="all" id="uniqnetbiosnames"> +<title>Unique NetBIOS Names</title> +<tgroup cols="2"> +<colspec align="left"/> +<colspec align="justify"/> +<tbody> +<row><entry>MACHINENAME<00></entry><entry>Server Service is running on MACHINENAME</entry></row> +<row><entry>MACHINENAME<03></entry><entry>Generic Machine Name (NetBIOS name)</entry></row> +<row><entry>MACHINENAME<20></entry><entry>LanMan Server service is running on MACHINENAME</entry></row> +<row><entry>WORKGROUP<1b></entry><entry>Domain Master Browser</entry></row> +</tbody> +</tgroup> +</table> + +<table frame="all" id="netbiosnamesgrp"> +<title>Group Names</title> +<tgroup cols="2"> +<colspec align="left"/> +<colspec align="justify"/> +<tbody> +<row><entry>WORKGROUP<03></entry><entry>Generic Name registered by all members of WORKGROUP</entry></row> +<row><entry>WORKGROUP<1c></entry><entry>Domain Controllers / Netlogon Servers</entry></row> +<row><entry>WORKGROUP<1d></entry><entry>Local Master Browsers</entry></row> +<row><entry>WORKGROUP<1e></entry><entry>Browser Election Service</entry></row> +</tbody> +</tgroup> +</table> + +<para> +<indexterm><primary>NetBIOS</primary></indexterm> +It should be noted that all NetBIOS machines register their own +names as per the above. This is in vast contrast to TCP/IP +installations where traditionally the system administrator will +determine in the <filename>/etc/hosts</filename> or in the DNS database what names +are associated with each IP address. +</para> + +<para> +<indexterm><primary>NetBIOS</primary></indexterm> +One further point of clarification should be noted. The <filename>/etc/hosts</filename> +file and the DNS records do not provide the NetBIOS name type information +that MS Windows clients depend on to locate the type of service that may +be needed. An example of this is what happens when an MS Windows client +wants to locate a domain logon server. It finds this service and the IP +address of a server that provides it by performing a lookup (via a +NetBIOS broadcast) for enumeration of all machines that have +registered the name type *<1c>. A logon request is then sent to each +IP address that is returned in the enumerated list of IP addresses. +Whichever machine first replies, it then ends up providing the logon services. +</para> + +<para> +The name <quote>workgroup</quote> or <quote>domain</quote> really can be confusing since these +have the added significance of indicating what is the security +architecture of the MS Windows network. The term <quote>workgroup</quote> indicates +that the primary nature of the network environment is that of a +peer-to-peer design. In a WORKGROUP, all machines are responsible for +their own security, and generally such security is limited to the use of +just a password (known as Share Level security). In most situations +with peer-to-peer networking, the users who control their own machines +will simply opt to have no security at all. It is possible to have +User Level Security in a WORKGROUP environment, thus requiring the use +of a user name and a matching password. +</para> + +<para> +MS Windows networking is thus predetermined to use machine names +for all local and remote machine message passing. The protocol used is +called Server Message Block (SMB) and this is implemented using +the NetBIOS protocol (Network Basic Input Output System). NetBIOS can +be encapsulated using LLC (Logical Link Control) protocol &smbmdash; in which case +the resulting protocol is called NetBEUI (Network Basic Extended User +Interface). NetBIOS can also be run over IPX (Inter-networking Packet +Exchange) protocol as used by Novell NetWare, and it can be run +over TCP/IP protocols &smbmdash; in which case the resulting protocol is called +NBT or NetBT, the NetBIOS over TCP/IP. +</para> + +<para> +MS Windows machines use a complex array of name resolution mechanisms. +Since we are primarily concerned with TCP/IP, this demonstration is +limited to this area. +</para> + +<sect2> +<title>The NetBIOS Name Cache</title> + +<para> +All MS Windows machines employ an in-memory buffer in which is +stored the NetBIOS names and IP addresses for all external +machines that machine has communicated with over the +past 10-15 minutes. It is more efficient to obtain an IP address +for a machine from the local cache than it is to go through all the +configured name resolution mechanisms. +</para> + +<para> +If a machine whose name is in the local name cache has been shut +down before the name had been expired and flushed from the cache, then +an attempt to exchange a message with that machine will be subject +to time-out delays. Its name is in the cache, so a name resolution +lookup will succeed, but the machine cannot respond. This can be +frustrating for users but is a characteristic of the protocol. +</para> + +<para> +<indexterm><primary>nbtstat</primary></indexterm> +<indexterm><primary>nmblookup</primary></indexterm> +The MS Windows utility that allows examination of the NetBIOS +name cache is called <quote>nbtstat</quote>. The Samba equivalent of this +is called <command>nmblookup</command>. +</para> + +</sect2> + +<sect2> +<title>The LMHOSTS File</title> + +<para> +<indexterm><primary>LMHOSTS</primary></indexterm> +This file is usually located in MS Windows NT 4.0 or Windows 200x/XP in the directory +<filename>%SystemRoot%\SYSTEM32\DRIVERS\ETC</filename> and contains the IP Address +and the machine name in matched pairs. The <filename>LMHOSTS</filename> file +performs NetBIOS name to IP address mapping. +</para> + +<para> +It typically looks like this: +</para> + +<para><programlisting> +# Copyright (c) 1998 Microsoft Corp. +# +# This is a sample LMHOSTS file used by the Microsoft Wins Client (NetBIOS +# over TCP/IP) stack for Windows98 +# +# This file contains the mappings of IP addresses to NT computer names +# (NetBIOS) names. Each entry should be kept on an individual line. +# The IP address should be placed in the first column followed by the +# corresponding computer name. The address and the computer name +# should be separated by at least one space or tab. The "#" character +# is generally used to denote the start of a comment (see the exceptions +# below). +# +# This file is compatible with Microsoft LAN Manager 2.x TCP/IP lmhosts +# files and offers the following extensions: +# +# #PRE +# #DOM:<domain> +# #INCLUDE <filename> +# #BEGIN_ALTERNATE +# #END_ALTERNATE +# \0xnn (non-printing character support) +# +# Following any entry in the file with the characters "#PRE" will cause +# the entry to be pre-loaded into the name cache. By default, entries are +# not pre-loaded, but are parsed only after dynamic name resolution fails. +# +# Following an entry with the "#DOM:<domain>" tag will associate the +# entry with the domain specified by <domain>. This effects how the +# browser and logon services behave in TCP/IP environments. To preload +# the host name associated with #DOM entry, it is necessary to also add a +# #PRE to the line. The <domain> is always pre-loaded although it will not +# be shown when the name cache is viewed. +# +# Specifying "#INCLUDE <filename>" will force the RFC NetBIOS (NBT) +# software to seek the specified <filename> and parse it as if it were +# local. <filename> is generally a UNC-based name, allowing a +# centralized lmhosts file to be maintained on a server. +# It is ALWAYS necessary to provide a mapping for the IP address of the +# server prior to the #INCLUDE. This mapping must use the #PRE directive. +# In addition the share "public" in the example below must be in the +# LanMan Server list of "NullSessionShares" in order for client machines to +# be able to read the lmhosts file successfully. This key is under +# \machine\system\currentcontrolset\services\lanmanserver\ +# parameters\nullsessionshares +# in the registry. Simply add "public" to the list found there. +# +# The #BEGIN_ and #END_ALTERNATE keywords allow multiple #INCLUDE +# statements to be grouped together. Any single successful include +# will cause the group to succeed. +# +# Finally, non-printing characters can be embedded in mappings by +# first surrounding the NetBIOS name in quotations, then using the +# \0xnn notation to specify a hex value for a non-printing character. +# +# The following example illustrates all of these extensions: +# +# 102.54.94.97 rhino #PRE #DOM:networking #net group's DC +# 102.54.94.102 "appname \0x14" #special app server +# 102.54.94.123 popular #PRE #source server +# 102.54.94.117 localsrv #PRE #needed for the include +# +# #BEGIN_ALTERNATE +# #INCLUDE \\localsrv\public\lmhosts +# #INCLUDE \\rhino\public\lmhosts +# #END_ALTERNATE +# +# In the above example, the "appname" server contains a special +# character in its name, the "popular" and "localsrv" server names are +# pre-loaded, and the "rhino" server name is specified so it can be used +# to later #INCLUDE a centrally maintained lmhosts file if the "localsrv" +# system is unavailable. +# +# Note that the whole file is parsed including comments on each lookup, +# 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> + +</sect2> + +<sect2> +<title>HOSTS File</title> + +<para> +This file is usually located in MS Windows NT 4.0 or Windows 200x/XP in +the directory <filename>%SystemRoot%\SYSTEM32\DRIVERS\ETC</filename> and contains +the IP Address and the IP hostname in matched pairs. It can be +used by the name resolution infrastructure in MS Windows, depending +on how the TCP/IP environment is configured. This file is in +every way the equivalent of the UNIX/Linux <filename>/etc/hosts</filename> file. +</para> +</sect2> + + +<sect2> +<title>DNS Lookup</title> + + +<para> +<indexterm><primary>DNS</primary></indexterm> +This capability is configured in the TCP/IP setup area in the network +configuration facility. If enabled, an elaborate name resolution sequence +is followed, the precise nature of which is dependant on how the NetBIOS +Node Type parameter is configured. A Node Type of 0 means that +NetBIOS broadcast (over UDP broadcast) is used if the name +that is the subject of a name lookup is not found in the NetBIOS name +cache. If that fails then DNS, HOSTS and LMHOSTS are checked. If set to +Node Type 8, then a NetBIOS Unicast (over UDP Unicast) is sent to the +WINS Server to obtain a lookup before DNS, HOSTS, LMHOSTS, or broadcast +lookup is used. +</para> + +</sect2> + +<sect2> +<title>WINS Lookup</title> + + +<para> +<indexterm><primary>WINS</primary></indexterm> +A WINS (Windows Internet Name Server) service is the equivalent of the +rfc1001/1002 specified NBNS (NetBIOS Name Server). A WINS server stores +the names and IP addresses that are registered by a Windows client +if the TCP/IP setup has been given at least one WINS Server IP Address. +</para> + +<para> +To configure Samba to be a WINS server, the following parameter needs +to be added to the &smb.conf; file: +</para> + +<para><smbconfblock> +<smbconfoption name="wins support">Yes</smbconfoption> +</smbconfblock></para> + +<para> +To configure Samba to use a WINS server, the following parameters are +needed in the &smb.conf; file: +</para> + +<para><smbconfblock> +<smbconfoption name="wins support">No</smbconfoption> +<smbconfoption name="wins server">xxx.xxx.xxx.xxx</smbconfoption> +</smbconfblock></para> + +<para> +where <replaceable>xxx.xxx.xxx.xxx</replaceable> is the IP address +of the WINS server. +</para> + +<para>For information about setting up Samba as a WINS server, read +<link linkend="NetworkBrowsing">Network Browsing</link>.</para> + +</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 keyboard mishaps, forgetfulness, simple mistakes, and +carelessness. Of course, no one is ever deliberately careless! +</para> + + <sect2> + <title>Pinging Works Only in One Way</title> + + <para> + <quote>I can ping my Samba server from Windows, but I cannot ping my Windows + machine from the Samba server.</quote> + </para> + + <para> + <emphasis>Answer:</emphasis> 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 netmask 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 &smbmdash; logically a different network. + </para> + + </sect2> + + <sect2> + <title>Very Slow Network Connections</title> + + <para> + A common cause of slow network response includes: + </para> + + <itemizedlist> + <listitem><para>Client is configured to use DNS and the DNS server is down.</para></listitem> + <listitem><para>Client is configured to use remote DNS server, but the + 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> + <quote>The name of the Samba server was changed, Samba was restarted, Samba server cannot be + ping-ed by new name from MS Windows NT4 Workstation, but it does still respond to ping using + the old name. Why?</quote> + </para> + + <para> + From this description, three things are 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 <command>cmd</command> shell and then: + </para> + + <para> +<screen> +&dosprompt;<userinput>nbtstat -n</userinput> + + NetBIOS Local Name Table + + Name Type Status +------------------------------------------------ +&example.workstation.windows; <03> UNIQUE Registered +ADMINISTRATOR <03> UNIQUE Registered +&example.workstation.windows; <00> UNIQUE Registered +SARDON <00> GROUP Registered +&example.workstation.windows; <20> UNIQUE Registered +&example.workstation.windows; <1F> UNIQUE Registered + + +&dosprompt;nbtstat -c + + NetBIOS Remote Cache Name Table + + Name Type Host Address Life [sec] +-------------------------------------------------------------- +&example.server.samba; <20> UNIQUE 192.168.1.1 240 + +&dosprompt; +</screen> + </para> + + <para> + In the above example, &example.server.samba; is the Samba server and &example.workstation.windows; is the MS Windows NT4 Workstation. + The first listing shows the contents of the Local Name Table (i.e., Identity information on + the MS Windows workstation) and 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/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml b/docs/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml new file mode 100644 index 0000000000..18f0d28454 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml @@ -0,0 +1,497 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="InterdomainTrusts"> +<chapterinfo> + &author.jht; + &author.mimir; + <author>&person.jelmer;<contrib>drawing</contrib></author> + <author> + <firstname>Stephen</firstname><surname>Langasek</surname> + <affiliation> + <address><email>vorlon@netexpress.net</email></address> + </affiliation> + </author> + <pubdate>April 3, 2003</pubdate> +</chapterinfo> + +<title>Interdomain Trust Relationships</title> + + +<para> +<indexterm><primary>Interdomain Trusts</primary></indexterm> +<indexterm><primary>LDAP</primary></indexterm> +<indexterm><primary>trusts</primary></indexterm> +<indexterm><primary>samba-to-samba trusts</primary></indexterm> +<indexterm><primary>Active Directory</primary></indexterm> +Samba-3 supports NT4-style domain trust relationships. This is a feature that many sites +will want to use if they migrate to Samba-3 from an NT4-style domain and do not want to +adopt Active Directory or an LDAP-based authentication backend. This section explains +some background information regarding trust relationships and how to create them. It is now +possible for Samba-3 to trust NT4 (and vice versa), as well as to create Samba-to-Samba +trusts. +</para> + +<para> +<indexterm><primary>winbind</primary></indexterm> +<indexterm><primary>UID range</primary></indexterm> +<indexterm><primary>GID range</primary></indexterm> +The use of interdomain trusts requires use of <command>winbind</command>. Thus the +<command>winbindd</command> daemon must be running. Winbind operation in this mode is +dependant on the specification of a valid UID range and a valid GID range in the &smb.conf; file. +These are specified respectively using +<smbconfoption name="idmap uid">10000-20000</smbconfoption> and +<smbconfoption name="idmap gid">10000-20000</smbconfoption>. +</para> + +<note><para> +The use of winbind is necessary only when Samba is the trusting Domain, not when it is the +trusted Domain. +</para></note> + +<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 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 its 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 simply 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> +MS Windows NT3/4 type security domains employ a non-hierarchical security structure. +The limitations of this architecture as it effects the scalability of MS Windows networking +in large organizations is well known. Additionally, the flat namespace that results from +this design significantly impacts the delegation of administrative responsibilities in +large and diverse organizations. +</para> + +<para> +Microsoft developed Active Directory Service (ADS), based on Kerberos and LDAP, as a means +of circumventing the limitations of the older technologies. Not every organization is ready +or willing to embrace ADS. For small companies the older NT4-style domain security paradigm +is quite adequate, there remains an entrenched user base for whom there is no direct +desire to go through a disruptive change to adopt ADS. +</para> + +<para> +With MS Windows NT, Microsoft introduced the ability to allow differing security domains +to effect a mechanism so users from one domain may be given access rights and privileges +in another domain. The language that describes this capability is couched in terms of +<emphasis>Trusts</emphasis>. Specifically, one domain will <emphasis>trust</emphasis> the users +from another domain. The domain from which users are available to another security domain is +said to be a trusted domain. The domain in which those users have assigned rights and privileges +is the trusting domain. With NT3.x/4.0 all trust relationships are always in one direction only, +thus if users in both domains are to have privileges and rights in each others' domain, then it is +necessary to establish two relationships, one in each direction. +</para> + +<para> +In an NT4-style MS security domain, all trusts are non-transitive. This means that if there +are three domains (let's call them RED, WHITE and BLUE) where RED and WHITE have a trust +relationship, and WHITE and BLUE have a trust relationship, then it holds that there is no +implied trust between the RED and BLUE domains. Relationships are explicit and not +transitive. +</para> + +<para> +New to MS Windows 2000 ADS security contexts is the fact that trust relationships are two-way +by default. Also, all inter-ADS domain trusts are transitive. In the case of the RED, WHITE and BLUE +domains above, with Windows 2000 and ADS the RED and BLUE domains can trust each other. This is +an inherent feature of ADS domains. Samba-3 implements MS Windows NT4-style Interdomain trusts +and interoperates with MS Windows 200x ADS security domains in similar manner to MS Windows NT4-style domains. +</para> + +</sect1> + +<sect1> +<title>Native MS Windows NT4 Trusts Configuration</title> + +<para> +There are two steps to creating an interdomain trust relationship. To effect a two-way trust +relationship, it is necessary for each domain administrator to create a trust account for the +other domain to use in verifying security credentials. +<indexterm><primary>Interdomain Trusts</primary><secondary>creating</secondary></indexterm> +</para> + + +<sect2> +<title>Creating an NT4 Domain Trust</title> + +<para> +For MS Windows NT4, all domain trust relationships are configured using the +<application>Domain User Manager</application>. 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>. Next to the lower box labeled +<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 +to enter the name of the remote domain that will be able to assign access rights to users in +your domain. You will also need to enter a password for this trust relationship, which the +trusting domain will use when authenticating users from the trusted domain. +The password needs to be typed twice (for standard confirmation). +</para> + +</sect2> + + +<sect2> +<title>Completing an NT4 Domain Trust</title> + +<para> +<indexterm><primary>Interdomain Trusts</primary><secondary>Completing</secondary></indexterm> +A trust relationship will work only when the other (trusting) domain makes the appropriate connections +with the trusted domain. To consummate the trust relationship, the administrator will launch the +Domain User Manager from the menu select <guilabel>Policies</guilabel>, then select +<guilabel>Trust Relationships</guilabel>, click on the <guibutton>Add</guibutton> button +next to the box that is labeled <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> + +<sect2> +<title>Inter-Domain Trust Facilities</title> + + +<para> +<indexterm><primary>Interdomain Trusts</primary><secondary>Facilities</secondary></indexterm> +A two-way trust relationship is created when two one-way trusts are created, one in each direction. +Where a one-way trust has been established between two MS Windows NT4 domains (let's call them +DomA and DomB), the following facilities are created: +</para> + +<image id="trusts1"> + <imagedescription>Trusts overview.</imagedescription> + <imagefile>trusts1</imagefile> +</image> + +<itemizedlist> + <listitem><para> + DomA (completes the trust connection) <parameter>Trusts</parameter> DomB. + </para></listitem> + + <listitem><para> + DomA is the <parameter>Trusting</parameter> domain. + </para></listitem> + + <listitem><para> + DomB is the <parameter>Trusted</parameter> domain (originates the trust account). + </para></listitem> + + <listitem><para> + Users in DomB can access resources in DomA. + </para></listitem> + + <listitem><para> + Users in DomA cannot access resources in DomB. + </para></listitem> + + <listitem><para> + Global groups from DomB can be used in DomA. + </para></listitem> + + <listitem><para> + Global groups from DomA cannot be used in DomB. + </para></listitem> + + <listitem><para> + DomB does appear in the logon dialog box on client workstations in DomA. + </para></listitem> + + <listitem><para> + DomA does not appear in the logon dialog box on client workstations in DomB. + </para></listitem> +</itemizedlist> + +<itemizedlist> + <listitem><para> + Users/Groups in a trusting domain cannot be granted rights, permissions or access + to a trusted domain. + </para></listitem> + + <listitem><para> + The trusting domain can access and use accounts (Users/Global Groups) in the + trusted domain. + </para></listitem> + + <listitem><para> + Administrators of the trusted domain can be granted administrative rights in the + trusting domain. + </para></listitem> + + <listitem><para> + Users in a trusted domain can be given rights and privileges in the trusting + domain. + </para></listitem> + + <listitem><para> + Trusted domain Global Groups can be given rights and permissions in the trusting + domain. + </para></listitem> + + <listitem><para> + Global Groups from the trusted domain can be made members in Local Groups on + MS Windows Domain Member machines. + </para></listitem> +</itemizedlist> + +</sect2> + +</sect1> + +<sect1> +<title>Configuring Samba NT-Style Domain Trusts</title> + +<para> +This description is meant to be a fairly short introduction about how to set up a Samba server so +that it can participate in interdomain trust relationships. Trust relationship support in Samba +is at an early stage, so do not be surprised if something does not function as it should. +</para> + +<para> +Each of the procedures described below assumes the peer domain in the trust relationship is +controlled by a Windows NT4 server. However, the remote end could just as well be another +Samba-3 domain. It can be clearly seen, after reading this document, that combining +Samba-specific parts of what's written below leads to trust between domains in a purely Samba +environment. +</para> + +<sect2 id="samba-trusted-domain"> +<title>Samba as the Trusted Domain</title> + +<para> +In order to set the Samba PDC to be the trusted party of the relationship, you first need +to create a special account for the domain that will be the trusting party. To do that, +you can use the <command>smbpasswd</command> utility. Creating the trusted domain account is +similar to creating a trusted machine account. Suppose, your domain is +called SAMBA, and the remote domain is called RUMBA. The first step +will be to issue this command from your favorite shell: +</para> + +<para> +<screen> +&rootprompt; <userinput>smbpasswd -a -i rumba</userinput> +New SMB password: <userinput>XXXXXXXX</userinput> +Retype SMB password: <userinput>XXXXXXXX</userinput> +Added user rumba$ +</screen> + +where <option>-a</option> means to add a new account into the +passdb database and <option>-i</option> means: <quote>create this +account with the Inter-Domain trust flag</quote>. +</para> + +<para> +The account name will be <quote>rumba$</quote> (the name of the remote domain). +If this fails, you should check that the trust account has been added to the system +password database (<filename>/etc/passwd</filename>). If it has not been added, you +can add it manually and then repeat the step above. +</para> + +<para> +After issuing this command, you will be asked to enter the password for +the account. You can use any password you want, but be aware that Windows NT will +not change this password until seven days following account creation. +After the command returns successfully, you can look at the entry for the new account +(in the standard way as appropriate for your configuration) and see that accounts name is +really RUMBA$ and it has the <quote>I</quote> flag set in the flags field. Now you are ready to confirm +the trust by establishing it from Windows NT Server. +</para> + + +<para> +<indexterm><primary>User Manager</primary></indexterm> +Open <application>User Manager for Domains</application> and from the +<guimenu>Policies</guimenu> menu, select <guimenuitem>Trust Relationships...</guimenuitem>. +Beside the <guilabel>Trusted domains</guilabel> list box click the +<guimenu>Add...</guimenu> button. You will be prompted for +the trusted domain name and the relationship password. Type in SAMBA, as this is +the name of the remote domain and the password used at the time of account creation. +Click on <guibutton>OK</guibutton> and, if everything went without incident, you will see +the <computeroutput>Trusted domain relationship successfully +established</computeroutput> message. +</para> + +</sect2> +<sect2> +<title>Samba as the Trusting Domain</title> + +<para> +This time activities are somewhat reversed. Again, we'll assume that your domain +controlled by the Samba PDC is called SAMBA and the NT-controlled domain is called RUMBA. +</para> + +<para> +The very first step is to add an account for the SAMBA domain on RUMBA's PDC. +</para> + + +<para> +<indexterm><primary>User Manager</primary></indexterm> +Launch the <application>Domain User Manager</application>, then from the menu select +<guimenu>Policies</guimenu>, <guimenuitem>Trust Relationships</guimenuitem>. +Now, next to the <guilabel>Trusted Domains</guilabel> box press the <guibutton>Add</guibutton> +button and type in the name of the trusted domain (SAMBA) and the password to use in securing +the relationship. +</para> + +<para> +The password can be arbitrarily chosen. It is easy to change the password +from the Samba server whenever you want. After confirming the password your account is +ready for use. Now its Samba's turn. +</para> + +<para> +Using your favorite shell while being logged in as root, issue this command: +</para> + +<para> +&rootprompt;<userinput>net rpc trustdom establish rumba</userinput> +</para> + +<para> +You will be prompted for the password you just typed on your Windows NT4 Server box. +An error message <errorname>`NT_STATUS_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT'</errorname> +that may be reported periodically is of no concern and may safely be ignored. +It means the 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), but eventually you should see +the <computeroutput>Success</computeroutput> message. Congratulations! Your trust +relationship has just been established. +</para> + +<note><para> +You have to run this command as root because you must have write access to +the <filename>secrets.tdb</filename> file. +</para></note> + +</sect2> +</sect1> + +<sect1> +<title>NT4-Style Domain Trusts with Windows 2000</title> +<para> +Although <application>Domain User Manager</application> is not present in Windows 2000, it is +also possible to establish an NT4-style trust relationship with a Windows 2000 domain +controller running in mixed mode as the trusting server. It should also be possible for +Samba to trust a Windows 2000 server, however, more testing is still needed in this area. +</para> + +<para> +After <link linkend="samba-trusted-domain">creating the interdomain trust account on the +Samba server</link> as described above, open <application>Active Directory Domains and +Trusts</application> on the AD controller of the domain whose resources you wish Samba users +to have access to. Remember that since NT4-style trusts are not transitive, if you want +your users to have access to multiple mixed-mode domains in your AD forest, you will need to +repeat this process for each of those domains. With <application>Active Directory Domains +and Trusts</application> open, right-click on the name of the Active Directory domain that +will trust our Samba domain and choose <guimenuitem>Properties</guimenuitem>, then click on +the <guilabel>Trusts</guilabel> tab. In the upper part of the panel, you will see a list box +labeled <guilabel>Domains trusted by this domain:</guilabel>, and an +<guilabel>Add...</guilabel> button next to it. Press this button and just as with NT4, you +will be prompted for the trusted domain name and the relationship password. Press OK and +after a moment, Active Directory will respond with <computeroutput>The trusted domain has +been added and the trust has been verified.</computeroutput> Your Samba users can now be +granted access to resources in the AD domain. +</para> +</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>Browsing of Trusted Domain Fails</title> + +<para> +Browsing from a machine in a trusted Windows 200x Domain to a Windows 200x member of +a trusting samba domain, I get the following error: +</para> + +<screen> +The system detected a possible attempt to compromise security. Please ensure that +you can contact the server that authenticated you. +</screen> + +<para> +The event logs on the box I'm trying to connect to have entries regarding group +policy not being applied because it is a member of a down-level domain. +</para> + +<para><emphasis>Answer: </emphasis> If there is a computer account in the Windows +200x Domain for the machine in question, and it is disabled, this problem can +occur. If there is no computer account (removed or never existed), or if that +account is still intact (i.e.: you just joined it to another domain) everything +seems to be fine. By default, when you un-join a domain (the Windows 200x +Domain), the computer tries to automatically disable the computer account in +the domain. If you are running as an account which has privileges to do this +when you un-join the machine, it is done, otherwise it is not done. +</para> + +</sect2> + +<sect2> +<title>Problems With LDAP ldapsam And The smbldap-tools</title> + +<para> +If you use the <command>smbldap-useradd</command> script to create a trust +account to set up Interdomain trusts the process of setting up the trust will +fail. The account that was created in the LDAP database will have an account +flags field that has <constant>[W ]</constant>, when it must have +<constant>[I ]</constant> for Interdomain trusts to work. +</para> + +<para><emphasis>Answer: </emphasis>Here is a simple solution. +Create a machine account as follows: +<screen> +&rootprompt; smbldap-useradd -w domain_name +</screen> +Then set the desired trust account password as shown here: +<screen> +&rootprompt; smbldap-passwd domain_name\$ +</screen> +Using a text editor, create the following file: +<screen> +dn: uid=domain_name$,ou=People,dc={your-domain},dc={your-top-level-domain} +changetype: modify +sambaAcctFlags: [I ] +</screen> +Then apply the text file to the LDAP database as follows: +<screen> +&rootprompt; ldapmodify -x -h localhost \ + -D "cn=Manager,dc={your-domain},dc={your-top-level-domain}" \ + -W -f /path-to/foobar +</screen> +Create a single-sided trust under the NT4 Domain User Manager, then execute: +<screen> +&rootprompt; net rpc trustdom establish domain_name +</screen> +</para> + +<para> +It works with Samba-3 and NT4 Domains, and also with Samba-3 and Windows 200x ADS in mixed mode. +Both DC's, samba and NT, must have the same WINS server otherwise +the trust will never work. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-IntroSMB.xml b/docs/Samba3-HOWTO/TOSHARG-IntroSMB.xml new file mode 100644 index 0000000000..547a55f43a --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-IntroSMB.xml @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE preface PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<preface id="IntroSMB"> +<prefaceinfo> + &author.jht; + <pubdate>June 29, 2003</pubdate> +</prefaceinfo> + +<title>Preface and Introduction</title> + +<para><quote> +A man's gift makes room for him before great men. Gifts are like hooks that can catch +hold of the mind taking it beyond the reach of forces that otherwise might constrain it. +</quote> --- Anon. +</para> + + +<para> +This is a book about Samba. It is a tool, a derived work of the labors +of many and of the diligence and goodwill of more than a few. +This book contains material that has been contributed in a persistent belief +that each of us can add value to our neighbors as well as to those who will +follow us. +</para> + +<para> +This book is designed to meet the needs of the Microsoft network administrator. +UNIX administrators will benefit from this book also, though they may complain +that it is hard to find the information they think they need. So if you are a +Microsoft certified specialist, this book should meet your needs rather well. +If you are a UNIX or Linux administrator, there is no need to feel badly &smbmdash; you +should have no difficulty finding answers to your current concerns also. +</para> + +<sect1> +<title>What Is Samba?</title> + + <para> + Samba is a big, complex project. The Samba project is ambitious and exciting. + The team behind Samba is a group of some thirty individuals who are spread + the world over and come from an interesting range of backgrounds. This team + includes scientists, engineers, programmers, business people, and students. + </para> + + <para> + Team members were drawn into active participation through the desire to help + deliver an exciting level of transparent interoperability between Microsoft + Windows and the non-Microsoft information + technology world. + </para> + + <para> + The slogan that unites the efforts behind the Samba project says: + <emphasis>Samba, Opening Windows to a Wider World!</emphasis> The goal + behind the project is one of removing barriers to interoperability. + </para> + + <para> + Samba provides file and print services for Microsoft Windows clients. These + services may be hosted off any TCP/IP-enabled platform. The original deployment + platforms were UNIX and Linux, though today it is in common use across + a broad variety of systems. + </para> + + <para> + The Samba project includes not only an impressive feature set in file and print + serving capabilities, but has been extended to include client functionality, + utilities to ease migration to Samba, tools to aid interoperability with + Microsoft Windows, and administration tools. + </para> + + <para> + The real people behind Samba are users like you. You have inspired the + developers (the Samba Team) to do more than any of them imagined could or should + be done. User feedback drives Samba development. Samba-3 in particular incorporates + a huge amount of work done as a result of user requests, suggestions and direct + code contributions. + </para> + +</sect1> + +<sect1> +<title>Why This Book?</title> + + <para> + There is admittedly a large number of Samba books on the market today and + each book has its place. Despite the apparent plethora of books, Samba + as a project continues to receive much criticism for failing to provide + sufficient documentation. Samba is also criticized for being too complex + and too difficult to configure. In many ways this is evidence of the + success of Samba as there would be no complaints if it was not successful. + </para> + + <para> + The Samba Team members work predominantly with UNIX and Linux, so + it is hardly surprising that existing Samba documentation should reflect + that orientation. The original HOWTO text documents were intended to provide + some tips, a few golden nuggets, and if they helped anyone then that was + just wonderful. But the HOWTO documents lacked structure and context. They were + isolated snapshots of information that were written to pass information + on to someone else who might benefit. They reflected a need to transmit + more information that could be conveniently put into manual pages. + </para> + + <para> + The original HOWTO documents were written by different authors. Most HOWTO + documents are the result of feedback and contributions from numerous + authors. In this book we took care to preserve as much original content as + possible. As you read this book you will note that chapters were written by + multiple authors, each of whom has his own style. This demonstrates + the nature of the Open Source software development process. + </para> + + <para> + Out of the original HOWTO documents sprang a collection of unofficial + HOWTO documents that are spread over the Internet. It is sincerely intended + that this work will <emphasis>not</emphasis> replace the valuable unofficial + HOWTO work that continues to flourish. If you are involved in unofficial + HOWTO production then please continue your work! + </para> + + <para> + Those of you who have dedicated your labors to the production of unofficial + HOWTOs, to Web page information regarding Samba, or to answering questions + on the mailing lists or elsewhere, may be aware that this is a labor + of love. We would like to know about your contribution and willingly receive + the precious pearls of wisdom you have collected. Please email your contribution to + <ulink noescape="1" url="mailto:jht@samba.org">John H. Terpstra (jht@samba.org)</ulink>. + As a service to other users we will gladly adopt material that is technically accurate. + </para> + + <para> + Existing Samba books are largely addressed to the UNIX administrator. + From the perspective of this target group the existing books serve + an adequate purpose, with one exception &smbmdash; now that Samba-3 is out + they need to be updated! + </para> + + <para> + This book, the <emphasis>Official Samba-3 HOWTO and Reference Guide</emphasis>, + includes the Samba-HOWTO-Collection.pdf that ships with Samba. + These documents have been written with a new design intent and purpose. + </para> + + <para> + Over the past two years many Microsoft network administrators have adopted + Samba and have become interested in its deployment. Their information needs + are very different from that of the UNIX administrator. This book has been + arranged and the information presented from the perspective of someone with previous + Microsoft Windows network administrative training and experience. + </para> + +</sect1> + +<sect1> +<title>Book Structure and Layout</title> + + <para> + This book is presented in six parts: + </para> + + <variablelist> + <varlistentry><term>General Installation</term> + <listitem><para> + Designed to help you get Samba-3 running quickly. + The Fast Start chapter is a direct response to requests from + Microsoft network administrators for some sample configurations + that <emphasis>just work</emphasis>. + </para></listitem> + </varlistentry> + + <varlistentry><term>Server Configuration Basics</term> + <listitem><para> + The purpose of this section is to aid the transition from existing + Microsoft Windows network knowledge to Samba terminology and norms. + The chapters in this part each cover the installation of one type of + Samba server. + </para></listitem> + </varlistentry> + + <varlistentry><term>Advanced Configuration</term> + <listitem><para> + The mechanics of network browsing have long been the Achilles heel of + all Microsoft Windows users. Samba-3 introduces new user and machine + account management facilities, a new way to map UNIX groups and Windows + groups, Interdomain trusts, new loadable file system drivers (VFS), and + more. New with this document is expanded printing documentation, as well + as a wealth of information regarding desktop and user policy handling, + use of desktop profiles, and techniques for enhanced network integration. + This section makes up the core of the book. Read and enjoy. + </para></listitem> + </varlistentry> + + <varlistentry><term>Migration and Updating</term> + <listitem><para> + A much requested addition to the book is information on how to migrate + from Microsoft Windows NT4 to Samba-3, as well as an overview of what the + issues are when moving from Samba-2.x to Samba-3. + </para></listitem> + </varlistentry> + + <varlistentry><term>Troubleshooting</term> + <listitem><para> + This short section should help you when all else fails. + </para></listitem> + </varlistentry> + + <varlistentry><term>Appendix</term> + <listitem><para> + Here you will find a collection of things that are either too peripheral + for most users, or are a little left of field to be included in the + main body of information. + </para></listitem> + </varlistentry> + </variablelist> + +<para> +Welcome to Samba-3 and the first published document to help you and your users to enjoy a whole +new world of interoperability between Microsoft Windows and the rest of the world. +</para> + +</sect1> + +</preface> diff --git a/docs/Samba3-HOWTO/TOSHARG-LargeFile.xml b/docs/Samba3-HOWTO/TOSHARG-LargeFile.xml new file mode 100644 index 0000000000..44f054236e --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-LargeFile.xml @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="largefile"> +<chapterinfo> + &author.jeremy; + &author.jht; + <pubdate>March 5, 2005</pubdate> +</chapterinfo> +<title>Handling Large Directories</title> + +<para> +Samba-3.0.12 implements a solution for sites that have experienced performance degradation do to the +problem of using Samba-3 with applications that need large numbers of files (100,000 or more) per directory. +</para> + +<para> +The key was fixing the directory handling to read only the current list requested instead of the old +(up to samba-3.0.11) behaviour of reading the entire directory into memory before doling out names. +Normally this would have broken OS/2 applications which have very strange delete semantics, but by +stealing logic from Samba4 (thanks tridge) the current code in 3.0.12 handles this correctly. +</para> + +<para> +To set up an application that needs large number of files per directory in a way that does not +damage performance unduly follow these steps: +</para> + +<para> +Firstly, you need to canonicalize all the files in the directory to have one case, upper or lower - take your +pick (I chose upper as all my files were already upper case names). Then set up a new custom share for the +application as follows: +<screen> +[bigshare] + path = /home/jeremy/tmp/manyfilesdir + read only = no + case sensitive = True + default case = upper + preserve case = no + short preserve case = no +</screen> +</para> + +<para> +Of course, use your own path and settings, but set the case options to match the case of all the files in your +directory. The path should point at the large directory needed for the application - any new files created in +there and in any paths under it will be forced by smbd into upper case - but smbd will no longer have to scan +the directory for names - it knows that if a file does not exist in upper case then it doesn't exist at all. +</para> + +<para> +The secret to this is really in the <smbconfoption name="case sensitive">True</smbconfoption> +line. This tells smbd never to scan for case-insensitive versions of names. So if an application asks for a file +called <filename>FOO</filename>, and it can not be found by a simple stat call, then smbd will return file not +found immediately without scanning the containing directory for a version of a different case. The other +<filename>xxx case xxx</filename> lines make this work by forcing a consistent case on all files created by smbd. +</para> + +<para> +Remember, all files and directories under the <parameter>path</parameter> directory must be in upper case +with this &smb.conf; stanza as smbd will not be able to find lower case filenames with these settings. Also +note this is done on a per-share basis, allowing this to be set only for a share servicing an application with +this problematic behaviour (using large numbers of entries in a directory) - the rest of your smbd shares +don't need to be affected. +</para> + +<para> +This makes smbd much faster when dealing with large directories. My test case has over 100,000 files and +smbd now deals with this very efficiently. +</para> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml b/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml new file mode 100644 index 0000000000..4f65b8c0a7 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml @@ -0,0 +1,527 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="NT4Migration"> +<chapterinfo> + &author.jht; + <pubdate>April 3, 2003</pubdate> +</chapterinfo> + +<title>Migration from NT4 PDC to Samba-3 PDC</title> + +<para> +This is a rough guide to assist those wishing to migrate from NT4 Domain Control to +Samba-3-based Domain Control. +</para> + +<sect1> +<title>Planning and Getting Started</title> + +<para> +In the IT world there is often a saying that all problems are encountered because of +poor planning. The corollary to this saying is that not all problems can be anticipated +and planned for. Then again, good planning will anticipate most show-stopper-type situations. +</para> + +<para> +Those wishing to migrate from MS Windows NT4 Domain Control to a Samba-3 Domain Control +environment would do well to develop a detailed migration plan. So here are a few pointers to +help migration get under way. +</para> + +<sect2> +<title>Objectives</title> + +<para> +The key objective for most organizations will be to make the migration from MS Windows NT4 +to Samba-3 Domain Control as painless as possible. One of the challenges you may experience +in your migration process may well be one of convincing management that the new environment +should remain in place. Many who have introduced open source technologies have experienced +pressure to return to a Microsoft-based platform solution at the first sign of trouble. +</para> + +<para> +Before attempting a migration to a Samba-3 controlled network, make every possible effort to +gain all-round commitment to the change. Know precisely <emphasis>why</emphasis> the change +is important for the organization. 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 organization's dependency on Microsoft.</para></listitem> +</itemizedlist> + +<para> +Make sure everyone knows that Samba-3 is not MS Windows NT4. Samba-3 offers +an alternative solution that is both different from MS Windows NT4 and offers +advantages compared with it. Gain recognition that Samba-3 lacks many of the +features that Microsoft has promoted as core values in migration from MS Windows NT4 to +MS Windows 2000 and beyond (with or without Active Directory services). +</para> + +<para> +What are the features that Samba-3 cannot provide? +</para> + +<itemizedlist> + <listitem><para>Active Directory Server.</para></listitem> + <listitem><para>Group Policy Objects (in Active Directory).</para></listitem> + <listitem><para>Machine Policy Objects.</para></listitem> + <listitem><para>Logon Scripts in Active Directory.</para></listitem> + <listitem><para>Software Application and Access Controls in Active Directory.</para></listitem> +</itemizedlist> + +<para> +The features that Samba-3 does provide and that may be of compelling interest to your site +include: +</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 (can run more than one SMB/CIFS 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-sign-on architecture.</para></listitem> + <listitem><para>Ability to distribute authentication systems for absolute minimum wide area network bandwidth demand.</para></listitem> +</itemizedlist> + +<para> +Before migrating a network from MS Windows NT4 to Samba-3, consider all necessary factors. Users +should be educated about changes they may experience so the change will be a welcome one +and not become an obstacle to the work they need to do. The following are factors that will +help ensure a successful migration: +</para> + +<sect3> +<title>Domain Layout</title> + +<para> +Samba-3 can be configured as a Domain Controller, a back-up Domain Controller (probably best called +a secondary controller), a Domain Member, or as a stand-alone Server. The Windows network security +domain context should be sized and scoped before implementation. Particular attention needs to be +paid to the location of the primary Domain Controller (PDC) as well as backup controllers (BDCs). +One way in which Samba-3 differs from Microsoft technology is that if one chooses to use an LDAP +authentication backend, then the same database can be used by several different domains. In a +complex organization, there can be a single LDAP database, which itself can be distributed (have +a master server and multiple slave servers) that can simultaneously serve multiple domains. +</para> + +<para> +From a design perspective, the number of users per server as well as the number of servers per +domain should be scaled taking into consideration server capacity and network bandwidth. +</para> + +<para> +A physical network segment may house several domains. Each may span multiple network segments. +Where domains span routed network segments, consider and test the performance implications of +the design and layout of a network. A centrally located Domain Controller that is designed to +serve multiple routed network segments may result in severe performance problems. Check the +response time (ping timing) between the remote segment and the PDC. If +it's long (more than 100 ms), +locate a backup controller (BDC) on the remote segment to serve as the local authentication and +access control server. +</para> +</sect3> + +<sect3> +<title>Server Share and Directory Layout</title> + +<para> +There are cardinal rules to effective network design that cannot be broken with impunity. +The most important rule: Simplicity is king in every well-controlled network. Every part of +the infrastructure must be managed; the more complex it is, the greater will be the demand +of keeping systems secure and functional. +</para> + +<para> +Keep in mind the nature of how data must be shared. Physical disk space layout should be considered +carefully. Some data must be backed up. The simpler the disk layout the easier it will be to +keep track of backup needs. Identify what backup media will meet your needs; consider backup to tape, +CD-ROM or (DVD-ROM), or other offline storage medium. Plan and implement for minimum +maintenance. Leave nothing to chance in your design; above all, do not leave backups to chance: +Backup, test, and validate every backup, create a disaster recovery plan and prove that it works. +</para> + +<para> +Users should be grouped according to data access control needs. File and directory access +is best controlled via group permissions and the use of the <quote>sticky bit</quote> on group controlled +directories may substantially avoid file access complaints from Samba share users. +</para> + +<para> +Inexperienced network administrators often attempt elaborate techniques to set access +controls on files, directories, shares, as well as in share definitions. +Keep your design and implementation simple and document your design extensively. Have others +audit your documentation. Do not create a complex mess that your successor will not understand. +Remember, job security through complex design and implementation may cause loss of operations +and downtime to users as the new administrator learns to untangle your knots. Keep access +controls simple and effective and make sure that users will never be interrupted by obtuse +complexity. +</para> +</sect3> + +<sect3> +<title>Logon Scripts</title> + +<para> +Logon scripts can help to ensure that all users gain the share and printer connections they need. +</para> + +<para> +Logon scripts can be created on-the-fly so all commands executed are specific to the +rights and privileges granted to the user. The preferred controls should be affected through +group membership so group information can be used to create a custom logon script using +the <smbconfoption name="root preexec"/> parameters to the <smbconfsection name="NETLOGON"/> share. +</para> + +<para> +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 Knowledge Base article KB189105 that +deals with how to add printers without user intervention via the logon script process. +</para> +</sect3> + +<sect3> +<title>Profile Migration/Creation</title> + +<para> +User and Group Profiles may be migrated using the tools described in the section titled Desktop Profile +Management. +</para> + + +<para> +<indexterm><primary>SID</primary></indexterm> +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 <filename>NTuser.DAT</filename> file +to be changed to the SID of the Samba-3 domain. +</para> +</sect3> + +<sect3> +<title>User and Group Accounts</title> + +<para> +It is possible to migrate all account settings from an MS Windows NT4 domain to Samba-3. Before +attempting to migrate user and group accounts, it is STRONGLY advised to create in Samba-3 the +groups that are present on the MS Windows NT4 domain <emphasis>AND</emphasis> to map them to +suitable UNIX/Linux groups. By following this simple advice, all user and group attributes +should migrate painlessly. +</para> +</sect3> + +</sect2> + +<sect2> +<title>Steps in Migration Process</title> + +<para> +The approximate migration process is described below. +</para> + +<itemizedlist> +<listitem><para> +You have an NT4 PDC that has the users, groups, policies and profiles to be migrated. +</para></listitem> + +<listitem><para> +Samba-3 set up as a DC with netlogon share, profile share, and so on. Configure the &smb.conf; file +to function as a BDC, i.e., <parameter>domain master = No</parameter>. +</para></listitem> +</itemizedlist> + +<procedure><title>The Account Migration Process</title> + <step><para> +<indexterm><primary>pdbedit</primary></indexterm> + Create a BDC account in the old NT4 domain for the Samba server using NT Server Manager.</para> + <substeps><step><para>Samba must not be running.</para></step></substeps></step> + + + <step><para> +<indexterm><primary>net</primary><secondary>rpc</secondary></indexterm> + <userinput>net rpc join -S <replaceable>NT4PDC</replaceable> -w <replaceable>DOMNAME</replaceable> -U Administrator%<replaceable>passwd</replaceable></userinput></para></step> + + <step><para><userinput>net rpc vampire -S <replaceable>NT4PDC</replaceable> -U administrator%<replaceable>passwd</replaceable></userinput></para></step> + + <step><para><userinput>pdbedit -L</userinput></para> + <substeps><step><para>Note &smbmdash; did the users migrate?</para></step></substeps> + </step> + + + <step><para> +<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm> +<indexterm><primary>initGroups.sh</primary></indexterm> + Now assign each of the UNIX groups to NT groups: + (It may be useful to copy this text to a script called <filename>initGroups.sh</filename>) + <smbfile name="initGroups.sh"> + <programlisting> +#!/bin/bash +#### Keep this as a shell script for future re-use + +# First assign well known domain global groups +net groupmap modify ntgroup="Domain Admins" unixgroup=root +net groupmap modify ntgroup="Domain Users" unixgroup=users +net groupmap modify ntgroup="Domain Guests" unixgroup=nobody + +# Now for our added domain global groups +net groupmap add ntgroup="Designers" unixgroup=designers type=d rid=3200 +net groupmap add ntgroup="Engineers" unixgroup=engineers type=d rid=3210 +net groupmap add ntgroup="QA Team" unixgroup=qateam type=d rid=3220 +</programlisting> +</smbfile> + </para></step> + + <step><para><userinput>net groupmap list</userinput></para> + <substeps><step><para>Check that all groups are recognized.</para></step></substeps> + </step> +</procedure> + +<para> +Migrate all the profiles, then migrate all policy files. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Migration Options</title> + +<para> +Sites that wish to migrate from MS Windows NT4 Domain Control to a Samba-based solution +generally fit into three basic categories. <link linkend="majtypes">Following table</link> shows the possibilities. +</para> + +<table frame="all" id="majtypes"><title>The Three Major Site Types</title> +<tgroup cols="2"> + <colspec align="left"/> + <colspec align="justify"/> + <thead> + <row><entry>Number of Users</entry><entry>Description</entry></row> + </thead> + <tbody> + <row><entry>< 50</entry><entry><para>Want simple conversion with no pain.</para></entry></row> + <row><entry>50 - 250</entry><entry><para>Want new features, can manage some in-house complexity.</para></entry></row> + <row><entry>> 250</entry><entry><para>Solution/Implementation must scale well, complex needs. Cross-departmental decision process. Local expertise in most areas.</para></entry></row> + </tbody> +</tgroup> +</table> + +<sect2> +<title>Planning for Success</title> + +<para> +There are three basic choices for sites that intend to migrate from MS Windows NT4 +to Samba-3: +</para> + +<itemizedlist> + <listitem><para> + Simple conversion (total replacement). + </para></listitem> + + <listitem><para> + Upgraded conversion (could be one of integration). + </para></listitem> + + <listitem><para> + Complete redesign (completely new solution). + </para></listitem> +</itemizedlist> + +<para> +Minimize down-stream problems by: +</para> + +<itemizedlist> + <listitem><para> + Taking sufficient time. + </para></listitem> + + <listitem><para> + Avoiding Panic. + </para></listitem> + + <listitem><para> + Testing all assumptions. + </para></listitem> + + <listitem><para> + Testing the full roll-out program, including workstation deployment. + </para></listitem> +</itemizedlist> + +<para><link linkend="natconchoices">Following table</link> lists the conversion choices given the type of migration +being contemplated. +</para> + +<table frame="all" id="natconchoices"><title>Nature of the Conversion Choices</title> +<tgroup cols="3"> + <colspec align="justify" colwidth="1*"/> + <colspec align="justify" colwidth="1*"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row><entry>Simple</entry><entry>Upgraded</entry><entry>Redesign</entry></row> + </thead> + <tbody> + <row> + <entry><para>Make use of minimal OS specific features.</para></entry> + <entry><para>Translate NT4 features to new host OS features.</para></entry> + <entry><para>Decide:</para></entry> + </row> + <row> + <entry><para>Move all accounts from NT4 into Samba-3</para></entry> + <entry><para>Copy and improve</para></entry> + <entry><para>Authentication regime (database location and access)</para></entry> + </row> + <row> + <entry><para>Make least number of operational changes</para></entry> + <entry><para>Make progressive improvements</para></entry> + <entry><para>Desktop management methods</para></entry> + </row> + <row> + <entry><para>Take least amount of time to migrate</para></entry> + <entry><para>Minimize user impact</para></entry> + <entry><para>Better control of Desktops/Users</para></entry> + </row> + <row> + <entry><para>Live versus isolated conversion</para></entry> + <entry><para>Maximize functionality</para></entry> + <entry><para>Identify Needs for: <emphasis>Manageability, Scalability, Security, Availability</emphasis></para></entry> + </row> + <row> + <entry><para>Integrate Samba-3 then migrate while users are active, then change of control (swap out)</para></entry> + <entry><para>Take advantage of lower maintenance opportunity</para></entry> + <entry><para></para></entry> + </row> + </tbody> +</tgroup> +</table> +</sect2> + +<sect2> +<title>Samba-3 Implementation Choices</title> + +<variablelist> + <varlistentry><term>Authentication Database/Backend</term><listitem> + <para> + Samba-3 can use an external authentication backend: + </para> + + <para> + <itemizedlist> + <listitem><para>Winbind (external Samba or NT4/200x server).</para></listitem> + <listitem><para>External server could use Active Directory or NT4 Domain.</para></listitem> + <listitem><para>Can use pam_mkhomedir.so to auto-create home dirs.</para></listitem> + <listitem><para> + Samba-3 can use a local authentication backend: <parameter>smbpasswd, tdbsam, ldapsam, mysqlsam</parameter></para></listitem> + </itemizedlist> + </para> + </listitem></varlistentry> + + <varlistentry><term>Access Control Points</term><listitem> + <para> + Samba permits Access Control Points to be set: + </para> + <itemizedlist> + <listitem><para>On the share itself &smbmdash; using Share ACLs.</para></listitem> + <listitem><para>On the file system &smbmdash; using UNIX permissions on files and directories.</para> + <para>Note: Can enable Posix ACLs in file system also.</para></listitem> + <listitem><para>Through Samba share parameters &smbmdash; not recommended except as last resort.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry><term>Policies (migrate or create new ones)</term><listitem> + <para> + Exercise great caution when affecting registry changes, use the right tool and be aware + that changes made through NT4-style <filename>NTConfig.POL</filename> files can leave + permanent changes. + </para> + <itemizedlist> + <listitem><para>Using Group Policy Editor (NT4).</para></listitem> + <listitem><para>Watch out for Tattoo effect.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry><term>User and Group Profiles</term><listitem> + <para> + Platform-specific so use platform tool to change from a Local to a Roaming profile. + Can use new profiles tool to change SIDs (<filename>NTUser.DAT</filename>). + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Logon Scripts</term><listitem> + <para> + Know how they work. + </para> + </listitem> + </varlistentry> + + + <varlistentry><term>User and Group Mapping to UNIX/Linux</term><listitem> + <para> +<indexterm><primary>pdbedit</primary></indexterm> + User and Group mapping code is new. Many problems have been experienced as network administrators + who are familiar with Samba-2.2.x migrate to Samba-3. Carefully study the chapters that document + the new password backend behavior and the new group mapping functionality. + </para> + <itemizedlist> + <listitem><para>The <parameter>username map</parameter> facility may be needed.</para></listitem> + <listitem><para>Use <command>net groupmap</command> to connect NT4 groups to UNIX groups.</para></listitem> + <listitem><para>Use <command>pdbedit</command> to set/change user configuration.</para> + + <para> + When migrating to LDAP backend, it may be easier to dump the initial + LDAP database to LDIF, edit, then reload into LDAP. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry><term>OS Specific Scripts/Programs may be Needed</term><listitem> + <para> + Every operating system has its peculiarities. These are the result of engineering decisions + that were based on the experience of the designer, and may have side-effects that were not + anticipated. Limitations that may bite the Windows network administrator include: + </para> + <itemizedlist> + <listitem><para>Add/Delete Users: Note OS limits on size of name + (Linux 8 chars) NT4 up to 254 chars.</para></listitem> + <listitem><para>Add/Delete Machines: Applied only to Domain Members + (Note: machine names may be limited to 16 characters).</para></listitem> + <listitem><para>Use <command>net groupmap</command> to connect NT4 groups to UNIX groups.</para></listitem> + <listitem><para>Add/Delete Groups: Note OS limits on size and nature. + Linux limit is 16 char, no spaces and no upper case chars (<command>groupadd</command>).</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry><term>Migration Tools</term><listitem> + <para> +<indexterm><primary>pdbedit</primary></indexterm> + Domain Control (NT4 Style) Profiles, Policies, Access Controls, Security + <itemizedlist> + <listitem><para>Samba: <command>net, rpcclient, smbpasswd, pdbedit, profiles.</command></para></listitem> + <listitem><para>Windows: <command>NT4 Domain User Manager, Server Manager (NEXUS)</command></para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml b/docs/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml new file mode 100644 index 0000000000..9592982429 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml @@ -0,0 +1,1797 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="NetworkBrowsing"> +<chapterinfo> + &author.jht; + &author.jelmer; + <pubdate>July 5, 1998</pubdate> + <pubdate>Updated: April 21, 2003</pubdate> +</chapterinfo> + +<title>Network Browsing</title> + +<para> +This document contains detailed information as well as a fast track guide to +implementing browsing across subnets and/or across workgroups (or domains). +WINS is the best tool for resolution of NetBIOS names to IP addresses. WINS is +not involved in browse list handling except by way of name to address resolution. +</para> + +<note><para> +MS Windows 2000 and later versions can be configured to operate with no NetBIOS +over TCP/IP. Samba-3 and later versions also support this mode of operation. +When the use of NetBIOS over TCP/IP has been disabled, the primary +means for resolution of MS Windows machine names is via DNS and Active Directory. +The following information assumes that your site is running NetBIOS over TCP/IP. +</para></note> + +<sect1> +<title>Features and Benefits</title> + +<para> +Someone once referred to the past in these words <quote><emphasis>It was the best of times, +it was the worst of times.</emphasis></quote> The more we look back, the more we long for what was and +hope it never returns. +</para> + + +<para> +<indexterm><primary>NetBIOS</primary></indexterm> +For many MS Windows network administrators, that statement sums up their feelings about +NetBIOS networking precisely. For those who mastered NetBIOS networking, its fickle +nature was just par for the course. For those who never quite managed to tame its +lusty features, NetBIOS is like Paterson's Curse. +</para> + +<para> +For those not familiar with botanical problems in Australia, Paterson's Curse, +<emphasis>Echium plantagineum</emphasis>, was introduced to Australia from Europe during the mid-nineteenth +century. Since then it has spread rapidly. The high seed production, with densities of +thousands of seeds per square meter, a seed longevity of more than seven years, and an +ability to germinate at any time of year, given the right conditions, are some of the +features which make it such a persistent weed. +</para> + +<para> +In this chapter we explore vital aspects of Server Message Block (SMB) networking with +a particular focus on SMB as implemented through running NetBIOS (Network Basic +Input/Output System) over TCP/IP. Since Samba does not implement SMB or NetBIOS over +any other protocols, we need to know how to configure our network environment and simply +remember to use nothing but TCP/IP on all our MS Windows network clients. +</para> + +<para> +Samba provides the ability to implement a WINS (Windows Inter-networking Name Server) +and implements extensions to Microsoft's implementation of WINS. These extensions +help Samba to effect stable WINS operations beyond the normal scope of MS WINS. +</para> + +<para> +WINS is exclusively a service that applies only to those systems +that run NetBIOS over TCP/IP. MS Windows 200x/XP have the capacity to operate with +support for NetBIOS disabled, in which case WINS is of no relevance. Samba supports this also. +</para> + +<para> +For those networks on which NetBIOS has been disabled (i.e., WINS is not required) +the use of DNS is necessary for host name resolution. +</para> + +</sect1> + +<sect1> +<title>What Is Browsing?</title> + +<para> +To most people browsing means they can see the MS Windows and Samba servers +in the Network Neighborhood, and when the computer icon for a particular server is +clicked, it opens up and shows the shares and printers available on the target server. +</para> + +<para> +What seems so simple is in fact a complex interaction of different technologies. +The technologies (or methods) employed in making all of this work include: +</para> + +<itemizedlist> + <listitem><para>MS Windows machines register their presence to the network.</para></listitem> + <listitem><para>Machines announce themselves to other machines on the network.</para></listitem> + <listitem><para>One or more machine on the network collates the local announcements.</para></listitem> + <listitem><para>The client machine finds the machine that has the collated list of machines.</para></listitem> + <listitem><para>The client machine is able to resolve the machine names to IP addresses.</para></listitem> + <listitem><para>The client machine is able to connect to a target machine.</para></listitem> +</itemizedlist> + +<para> +The Samba application that controls browse list management and name resolution is +called <filename>nmbd</filename>. The configuration parameters involved in nmbd's operation are: +</para> + +<para>Browsing options: <smbconfoption name="os level"/>(*), + <smbconfoption name="lm announce"/>, + <smbconfoption name="lm interval"/>, + <smbconfoption name="preferred master"/>(*), + <smbconfoption name="local master"/>(*), + <smbconfoption name="domain master"/>(*), + <smbconfoption name="browse list"/>, + <smbconfoption name="enhanced browsing"/>. +</para> + +<para>Name Resolution Method: + <smbconfoption name="name resolve order"/>(*). +</para> + +<para>WINS options: + <smbconfoption name="dns proxy"/>, + <smbconfoption name="wins proxy"/>, + <smbconfoption name="wins server"/>(*), + <smbconfoption name="wins support"/>(*), + <smbconfoption name="wins hook"/>. +</para> + +<para> +<indexterm><primary>WINS</primary></indexterm> +For Samba, the WINS Server and WINS Support are mutually exclusive options. Those marked with +an (*) are the only options that commonly may need to be modified. Even if none of these +parameters is set, <filename>nmbd</filename> will still do its job. +</para> + +</sect1> + +<sect1 id="netdiscuss"> +<title>Discussion</title> + +<para> +<indexterm><primary>SMB-based messaging</primary></indexterm> +<indexterm><primary>NetBIOS</primary></indexterm> +All MS Windows networking uses SMB-based messaging. SMB messaging may be implemented with or without NetBIOS. +MS Windows 200x supports NetBIOS over TCP/IP for backwards compatibility. Microsoft appears intent on phasing +out NetBIOS support. +</para> + +<sect2> +<title>NetBIOS over TCP/IP</title> + +<para> +<indexterm><primary>encapsulating</primary></indexterm> +<indexterm><primary>broadcast</primary></indexterm> +<indexterm><primary>unicast</primary></indexterm> +<indexterm><primary>UDP</primary></indexterm> +Samba implements NetBIOS, as does MS Windows NT/200x/XP, by encapsulating it over TCP/IP. +MS Windows products can do likewise. NetBIOS-based networking uses broadcast messaging to +effect browse list management. When running NetBIOS over TCP/IP, this uses UDP-based messaging. +UDP messages can be broadcast or unicast. +</para> + +<para> +<indexterm><primary>UDP</primary></indexterm> +Normally, only uni-cast UDP messaging can be forwarded by routers. The +<smbconfoption name="remote announce"/> parameter to smb.conf helps to project browse announcements +to remote network segments via uni-cast UDP. Similarly, the +<smbconfoption name="remote browse sync"/> parameter of &smb.conf; +implements browse list collation using uni-cast UDP. +</para> + +<para> +The methods used by MS Windows to perform name lookup requests (name resolution) is determined by a +configuration parameter called the netbios node-type. There are four (4) basic NetBIOS node types: +</para> + +<indexterm><primary>b-node</primary></indexterm> +<indexterm><primary>p-node</primary></indexterm> +<indexterm><primary>m-node</primary></indexterm> +<indexterm><primary>h-node</primary></indexterm> +<indexterm><primary>node-type</primary></indexterm> +<indexterm><primary>WINS</primary></indexterm> +<indexterm><primary>broadcast</primary></indexterm> +<indexterm><primary>unicast</primary></indexterm> +<itemizedlist> + <listitem><para><emphasis>b-node (type 0x01):</emphasis> The Windows client will use only + NetBIOS broadcast requests using UDP broadcast.</para></listitem> + <listitem><para><emphasis>p-node (type 0x02):</emphasis> The Windows client will use point-to-point + (NetBIOS unicast) requests using UDP unicast directed to a WINS server.</para></listitem> + <listitem><para><emphasis>m-node (type 0x04):</emphasis> The Windows client will first use + NetBIOS broadcast requests using UDP broadcast, then it will use (NetBIOS unicast) + requests using UDP unicast directed to a WINS server.</para></listitem> + <listitem><para><emphasis>h-node (type 0x08):</emphasis> The Windows client will use + (NetBIOS unicast) requests using UDP unicast directed to a WINS server, then it will use + NetBIOS broadcast requests using UDP broadcast.</para></listitem> +</itemizedlist> + +<para> +<indexterm><primary>Hybrid</primary></indexterm> +The default Windows network client (or server) network configuration enables NetBIOS over TCP/IP +and b-node configuration. The use of WINS makes most sense with h-node (Hybid mode) operation so that +in the event of a WINS breakdown or non-availability the client can use broadcast based name resolution. +</para> + +<para> +<indexterm><primary>LMB</primary><see>Local Master Browser</see></indexterm> +<indexterm><primary>Local Master Browser</primary></indexterm> +In those networks where Samba is the only SMB server technology, wherever possible +<filename>nmbd</filename> should be configured on one machine as the WINS +server. This makes it easy to manage the browsing environment. If each network +segment is configured with its own Samba WINS server, then the only way to +get cross-segment browsing to work is by using the +<smbconfoption name="remote announce"/> and the +<smbconfoption name="remote browse sync"/> +parameters to your &smb.conf; file. +</para> + +<para> +<indexterm><primary>WINS</primary></indexterm> +If only one WINS server is used for an entire multi-segment network, then +the use of the <smbconfoption name="remote announce"/> and the +<smbconfoption name="remote browse sync"/> parameters should not be necessary. +</para> + +<para> +<indexterm><primary>replication</primary><secondary>WINS</secondary></indexterm> +As of Samba-3 WINS replication is being worked on. The bulk of the code has +been committed, but it still needs maturation. This is not a supported feature +of the Samba-3.0.20 release. Hopefully, this will become a supported feature +of one of the Samba-3 release series. +</para> + +<para> +Right now Samba WINS does not support MS-WINS replication. This means that +when setting up Samba as a WINS server, there must only be one <filename>nmbd</filename> +configured as a WINS server on the network. Some sites have used multiple Samba WINS +servers for redundancy (one server per subnet) and then used +<smbconfoption name="remote browse sync"/> and <smbconfoption name="remote announce"/> +to effect browse list collation across all segments. Note that this means clients +will only resolve local names, and must be configured to use DNS to resolve names +on other subnets in order to resolve the IP addresses of the servers they can see +on other subnets. This setup is not recommended, but is mentioned as a practical +consideration (i.e., an <quote>if all else fails</quote> scenario). +</para> + +<para> +Lastly, take note that browse lists are a collection of unreliable broadcast +messages that are repeated at intervals of not more than 15 minutes. This means +that it will take time to establish a browse list and it can take up to 45 +minutes to stabilize, particularly across network segments. +</para> + +<para> +When an MS Windows 200x/XP system attempts to resolve a host name to an IP address +it follows a defined path: +</para> + +<orderedlist> + <listitem><para> + Checks the <filename>hosts</filename> file. It is located in + <filename>%SystemRoot%\System32\Drivers\etc</filename>. + </para></listitem> + + <listitem><para> + Does a DNS lookup. + </para></listitem> + + <listitem><para> + Checks the NetBIOS name cache. + </para></listitem> + + <listitem><para> + Queries the WINS server. + </para></listitem> + + <listitem><para> + Does a broadcast name lookup over UDP. + </para></listitem> + + <listitem><para> + Looks up entries in LMHOSTS, located in + <filename>%SystemRoot%\System32\Drivers\etc</filename>. + </para></listitem> +</orderedlist> + +</sect2> + +<sect2> +<title>TCP/IP without NetBIOS</title> + +<para> +<indexterm><primary>NetBIOS</primary></indexterm> +<indexterm><primary>NetBIOS-less</primary></indexterm> +<indexterm><primary>DNS</primary></indexterm> +All TCP/IP-enabled systems use various forms of host name resolution. The primary +methods for TCP/IP hostname resolution involve either a static file (<filename>/etc/hosts</filename>) +or the Domain Name System (DNS). DNS is the technology that makes +the Internet usable. DNS-based host name resolution is supported by nearly all +TCP/IP-enabled systems. Only a few embedded TCP/IP systems do not support DNS. +</para> + +<para> +<indexterm><primary>DNS</primary></indexterm> +Windows 200x/XP can register its host name with a Dynamic DNS server. You can +force register with a Dynamic DNS server in Windows 200x/XP using: +<command>ipconfig /registerdns</command>. +</para> + +<para> +With Active Directory (ADS), a correctly functioning DNS server is absolutely +essential. In the absence of a working DNS server that has been correctly configured, +MS Windows clients and servers will be unable to locate each other, so +consequently network services will be severely impaired. +</para> + +<para> +The use of Dynamic DNS is highly recommended with Active Directory, in which case +the use of BIND9 is preferred for its ability to adequately support the SRV (service) +records that are needed for Active Directory. +</para> + +<para> +Use of raw SMB over TCP/IP (No NetBIOS layer) can be done only with Active +Directory domains. Samba is not an Active Directory Domain Controller: ergo, +it is not possible run Samba as a domain controller and at the same time NOT use +NetBIOS. Where Samba is used as an Active Directory Domain Member Server (DMS) +it is possible to configure Samba to not use NetBIOS over TCP/IP. A Samba DMS +can integrate fully into an Active Directory domain. +</para> + +</sect2> + +<sect2 id="adsdnstech"> +<title>DNS and Active Directory</title> + + +<para> +<indexterm><primary>DNS</primary><secondary>Active Directory</secondary></indexterm> +Occasionally we hear from UNIX network administrators who want to use a UNIX-based Dynamic +DNS server in place of the Microsoft DNS server. While this might be desirable to some, the +MS Windows 200x DNS server is auto-configured to work with Active Directory. It is possible +to use BIND version 8 or 9, but it will almost certainly be necessary to create service records +(SRV records) so MS Active Directory clients can resolve host names to locate essential network services. +The following are some of the default service records that Active Directory requires: +</para> + +<variablelist> +<varlistentry> + <term>_ldap._tcp.pdc._msdcs.<emphasis>Domain</emphasis></term> + <listitem> + <para> + This provides the address of the Windows NT PDC for the Domain. + </para> + </listitem> +</varlistentry> +<varlistentry> + <term>_ldap._tcp.pdc._msdcs.<emphasis>DomainTree</emphasis></term> + <listitem> + <para> + Resolves the addresses of Global Catalog servers in the domain. + </para> + </listitem> +</varlistentry> +<varlistentry> + <term>_ldap._tcp.<emphasis>site</emphasis>.sites.writable._msdcs.<emphasis>Domain</emphasis></term> + <listitem> + <para> + Provides list of Domain Controllers based on sites. + </para> + </listitem> +</varlistentry> +<varlistentry> + <term>_ldap._tcp.writable._msdcs.<emphasis>Domain</emphasis></term> + <listitem> + <para> + Enumerates list of Domain Controllers that have the writable copies of the Active Directory data-store. + </para> + </listitem> +</varlistentry> +<varlistentry> + <term>_ldap._tcp.<emphasis>GUID</emphasis>.domains._msdcs.<emphasis>DomainTree</emphasis></term> + <listitem> + <para> + Entry used by MS Windows clients to locate machines using the Global Unique Identifier. + </para> + </listitem> +</varlistentry> +<varlistentry> + <term>_ldap._tcp.<emphasis>Site</emphasis>.gc._msdcs.<emphasis>DomainTree</emphasis></term> + <listitem> + <para> + Used by MS Windows clients to locate site configuration dependent Global Catalog server. + </para> + </listitem> +</varlistentry> +</variablelist> + + <para> + Specific entries used by Microsoft clients to locate essential services for an example domain + called <constant>quenya.org</constant> includes: + </para> + + <itemizedlist> + <listitem><para> + _kerberos._udp.quenya.org &smbmdash; Used to contact the KDC server via UDP. + This entry must list port 88 for each KDC. + </para></listitem> + + <listitem><para> + _kpasswd._udp.quenya.org &smbmdash; Used to locate the <constant>kpasswd</constant> server + when a user password change must be processed. This record must list port 464 on the + master KDC. + </para></listitem> + + <listitem><para> + _kerberos._tcp.quenya.org &smbmdash; Used to locate the KDC server via TCP. + This entry must list port 88 for each KDC. + </para></listitem> + + <listitem><para> + _ldap._tcp.quenya.org &smbmdash; Used to locate the LDAP service on the PDC. + This record must list port 389 for the PDC. + </para></listitem> + + <listitem><para> + _kpasswd._tcp.quenya.org &smbmdash; Used to locate the <constant>kpasswd</constant> server + to permit user password changes to be processed. This must list port 464. + </para></listitem> + + <listitem><para> + _gc._tcp.quenya.org &smbmdash; Used to locate the Global Catalog server for the + top of the domain. This must list port 3268. + </para></listitem> + </itemizedlist> + + <para> + The following records are also used by the Windows Domain Member client to locate vital + services on the Windows ADS domain controllers. + </para> + + <itemizedlist> + <listitem><para> + _ldap._tcp.pdc._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _ldap.gc._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _ldap.default-first-site-name._sites.gc._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _ldap.{SecID}.domains._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _ldap._tcp.dc._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _kerberos._tcp.dc._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _ldap.default-first-site-name._sites.dc._msdcs.quenya.org + </para></listitem> + + <listitem><para> + _kerberos.default-first-site-name._sites.dc._msdcs.queyna.org + </para></listitem> + + <listitem><para> + SecID._msdcs.quenya.org + </para></listitem> + </itemizedlist> + + <para> + Presence of the correct DNS entries can be validated by executing: +<screen> +&rootprompt; dig @frodo -t any _ldap._tcp.dc._msdcs.quenya.org + +; <lt;>> DiG 9.2.2 <lt;>> @frodo -t any _ldap._tcp.dc._msdcs.quenya.org +;; global options: printcmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 3072 +;; flags: qr aa rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 2 + + +;; QUESTION SECTION: +;_ldap._tcp.dc._msdcs.quenya.org. IN ANY + + +;; ANSWER SECTION: +_ldap._tcp.dc._msdcs.quenya.org. 600 IN SRV 0 100 389 frodo.quenya.org. +_ldap._tcp.dc._msdcs.quenya.org. 600 IN SRV 0 100 389 noldor.quenya.org. + + +;; ADDITIONAL SECTION: +frodo.quenya.org. 3600 IN A 10.1.1.16 +noldor.quenya.org. 1200 IN A 10.1.1.17 + + +;; Query time: 0 msec +;; SERVER: frodo#53(10.1.1.16) +;; WHEN: Wed Oct 7 14:39:31 2004 +;; MSG SIZE rcvd: 171 +</screen> + </para> + +</sect2> + +</sect1> + +<sect1> +<title>How Browsing Functions</title> + +<para> +MS Windows machines register their NetBIOS names +(i.e., the machine name for each service type in operation) on start-up. +The exact method by which this name registration +takes place is determined by whether or not the MS Windows client/server +has been given a WINS server address, whether or not LMHOSTS lookup +is enabled, or if DNS for NetBIOS name resolution is enabled, etc. +</para> + +<para> +In the case where there is no WINS server, all name registrations as +well as name lookups are done by UDP broadcast. This isolates name +resolution to the local subnet, unless LMHOSTS is used to list all +names and IP addresses. In such situations, Samba provides a means by +which the Samba server name may be forcibly injected into the browse +list of a remote MS Windows network (using the +<smbconfoption name="remote announce"/> parameter). +</para> + +<para> +Where a WINS server is used, the MS Windows client will use UDP +uni-cast to register with the WINS server. Such packets can be routed +and thus WINS allows name resolution to function across routed networks. +</para> + +<para> +During the startup process an election will take place to create a +Local Master Browser if one does not already exist. On each NetBIOS network +one machine will be elected to function as the Domain Master Browser. This +domain browsing has nothing to do with MS security Domain Control. +Instead, the Domain Master Browser serves the role of contacting each local +master browser (found by asking WINS or from LMHOSTS) and exchanging browse +list contents. This way every master browser will eventually obtain a complete +list of all machines that are on the network. Every 11 to 15 minutes an election +is held to determine which machine will be the master browser. By the nature of +the election criteria used, the machine with the highest uptime, or the +most senior protocol version or other criteria, will win the election +as Domain Master Browser. +</para> + +<para> +Clients wishing to browse the network make use of this list, but also depend +on the availability of correct name resolution to the respective IP +address/addresses. +</para> + +<para> +Any configuration that breaks name resolution and/or browsing intrinsics +will annoy users because they will have to put up with protracted +inability to use the network services. +</para> + +<para> +Samba supports a feature that allows forced synchronization of browse lists across +routed networks using the <smbconfoption name="remote browse sync"/> +parameter in the &smb.conf; file. This causes Samba to contact the local master +browser on a remote network and to request browse list synchronization. This +effectively bridges two networks that are separated by routers. The two remote +networks may use either broadcast-based name resolution or WINS-based name +resolution, but it should be noted that the +<smbconfoption name="remote browse sync"/> parameter provides +browse list synchronization &smbmdash; and that is distinct from name to address +resolution. In other words, for cross-subnet browsing to function correctly it is +essential that a name-to-address resolution mechanism be provided. This mechanism +could be via DNS, <filename>/etc/hosts</filename>, and so on. +</para> + +<sect2 id="DMB"> +<title>Configuring WORKGROUP Browsing</title> + +<para> +To configure cross-subnet browsing on a network containing machines +in a WORKGROUP, not an NT Domain, you need to set up one +Samba server to be the Domain Master Browser (note that this is not +the same as a Primary Domain Controller, although in an NT Domain the +same machine plays both roles). The role of a Domain Master Browser is +to collate the browse lists from Local Master Browsers on all the +subnets that have a machine participating in the workgroup. Without +one machine configured as a Domain Master Browser, each subnet would +be an isolated workgroup unable to see any machines on another +subnet. It is the presence of a Domain Master Browser that makes +cross-subnet browsing possible for a workgroup. +</para> + +<para> +In a 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 <smbconfsection name="[global]"/> section +of the &smb.conf; file: +</para> + +<para> +<smbconfblock> +<smbconfoption name="domain master">yes</smbconfoption> +</smbconfblock> +</para> + +<para> +The Domain Master Browser should preferably be the local master +browser for its own subnet. In order to achieve this, set the following +options in the <smbconfsection name="[global]"/> section of the &smb.conf; +file as shown in <link linkend="dmbexample">the following example</link>: +</para> + +<para> +<smbconfexample id="dmbexample"> +<title>Domain Master Browser smb.conf</title> +<smbconfsection name="[global]"/> +<smbconfoption name="domain master">yes</smbconfoption> +<smbconfoption name="local master">yes</smbconfoption> +<smbconfoption name="preferred master">yes</smbconfoption> +<smbconfoption name="os level">65</smbconfoption> +</smbconfexample> +</para> + +<para> +The Domain Master Browser may be the same machine as the WINS server, if necessary. +</para> + +<para> +Next, you should ensure that each of the subnets contains a machine that can act as +a Local Master Browser for the workgroup. Any MS Windows NT/200x/XP machine should +be able to do this, as will Windows 9x/Me machines (although these tend to get +rebooted more often, so it is not such a good idea to use these). To make a Samba +server a Local Master Browser set the following options in the +<smbconfsection name="[global]"/> section of the &smb.conf; file as +shown in <link linkend="lmbexample">following example</link>: +</para> + +<para> +<smbconfexample id="lmbexample"> +<title>Local master browser smb.conf</title> +<smbconfsection name="[global]"/> +<smbconfoption name="domain master">no</smbconfoption> +<smbconfoption name="local master">yes</smbconfoption> +<smbconfoption name="preferred master">yes</smbconfoption> +<smbconfoption name="os level">65</smbconfoption> +</smbconfexample> +</para> + +<para> +Do not do this for more than one Samba server on each subnet, or they will war with +each other over which is to be the Local Master Browser. +</para> + +<para> +The <smbconfoption name="local master"/> parameter allows Samba to act as a +Local Master Browser. The <smbconfoption name="preferred master"/> causes <command>nmbd</command> +to force a browser election on startup and the <smbconfoption name="os level"/> +parameter sets Samba high enough so it should win any browser elections. +</para> + +<para> +If you have an NT machine on the subnet that you wish to be the Local Master Browser, you can disable Samba from +becoming a Local Master Browser by setting the following options in the <smbconfsection name="[global]"/> section of the +&smb.conf; file as shown in <link linkend="nombexample">following example</link>: +</para> + +<para> +<smbconfexample id="nombexample"> +<title>smb.conf for not being a Master Browser</title> +<smbconfsection name="[global]"/> +<smbconfoption name="domain master">no</smbconfoption> +<smbconfoption name="local master">no</smbconfoption> +<smbconfoption name="preferred master">no</smbconfoption> +<smbconfoption name="os level">0</smbconfoption> +</smbconfexample> +</para> + +</sect2> + +<sect2> +<title>DOMAIN Browsing Configuration</title> + +<para> +If you are adding Samba servers to a Windows NT Domain, then you must not set up a Samba server as a Domain Master Browser. +By default, a Windows NT Primary Domain Controller for a domain is also the Domain Master Browser for that domain. Network +browsing may break if a Samba server registers the domain master browser NetBIOS name (<replaceable>DOMAIN</replaceable><1B>) +with WINS instead of the PDC. +</para> + +<para> +For subnets other than the one containing the Windows NT PDC, you may set up Samba servers as Local Master Browsers as +described. To make a Samba server a Local Master Browser, set the following options in the <smbconfsection name="[global]"/> section +of the &smb.conf; file as shown in <link linkend="remsmb">following example</link>: +</para> + +<para> +<smbconfexample id="remsmb"> +<title>Local Master Browser smb.conf</title> +<smbconfsection name="[global]"/> +<smbconfoption name="domain master">no</smbconfoption> +<smbconfoption name="local master">yes</smbconfoption> +<smbconfoption name="preferred master">yes</smbconfoption> +<smbconfoption name="os level">65</smbconfoption> +</smbconfexample> +</para> + +<para> +If you wish to have a Samba server fight the election with machines on the same subnet you +may set the <smbconfoption name="os level"/> 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 refer to <link linkend="browse-force-master">Forcing Samba to Be the Master</link> section. +</para> + +<para> +If you have Windows NT machines that are members of the domain on all subnets and you are +sure they will always be running, you can disable Samba from taking part in browser elections +and ever becoming a Local Master Browser by setting the following options in the +<smbconfsection name="[global]"/> section of the &smb.conf; file as shown in <link linkend="xremmb">next example</link>: +</para> + +<para> +<smbconfexample id="xremmb"> +<title>&smb.conf; for not being a master browser</title> +<smbconfsection name="[global]"/> +<smbconfoption name="domain master">no</smbconfoption> +<smbconfoption name="local master">no</smbconfoption> +<smbconfoption name="preferred master">no</smbconfoption> +<smbconfoption name="os level">0</smbconfoption> +</smbconfexample> +</para> + +</sect2> + +<sect2 id="browse-force-master"> +<title>Forcing Samba to Be the Master</title> + +<para> +Who becomes the master browser is determined by an election process using broadcasts. Each election packet contains a number of parameters +that determine what precedence (bias) a host should have in the election. By default Samba uses a low precedence and thus loses +elections to just about every Windows network server or client. +</para> + +<para> +If you want Samba to win elections, set the <smbconfoption name="os level"/> +global option in &smb.conf; to a higher number. It defaults to 20. Using 34 would make it win +all elections every other system (except other samba systems). +</para> + +<para> +An <smbconfoption name="os level"/> of two would make it beat Windows for Workgroups and Windows 9x/Me, but not MS Windows +NT/200x Server. An MS Windows NT/200x Server Domain Controller uses level 32. The maximum os level is 255. +</para> + +<para> +If you want Samba to force an election on startup, set the +<smbconfoption name="preferred master"/> 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 9x/Me or +NT/200x/XP or Samba) on the same local subnet both set with <smbconfoption name="preferred master"/> +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 <emphasis>Domain Master Browser</emphasis>, then it is recommended that +you also set <smbconfoption name="preferred master"/> 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. +</para> + +<para> +It is possible to configure two Samba servers to attempt to become the Domain Master Browser for a domain. The first server that comes +up will be the Domain Master Browser. All other Samba servers will attempt to become the Domain Master Browser every five minutes. They +will find that another Samba server is already the domain master browser and will fail. This provides automatic redundancy, should +the current Domain Master Browser fail. +</para> + +</sect2> + +<sect2> +<title>Making Samba the Domain Master</title> + +<para> +The domain master is responsible for collating the browse lists of multiple subnets so browsing can occur between subnets. You can +make Samba act as the Domain Master by setting <smbconfoption name="domain master">yes</smbconfoption> +in &smb.conf;. By default it will not be a Domain Master. +</para> + +<para> +Do not set Samba to be the Domain Master for a workgroup that has the same name as an NT/200x Domain. +If Samba is configured to be the Domain Master for a workgroup that is present on the same +network as a Windows NT/200x domain that has the same name, network browsing problems will +certainly be experienced. +</para> + +<para> +When Samba is the Domain Master and the Master Browser, it will listen for master +announcements (made roughly every twelve minutes) from Local Master Browsers on +other subnets and then contact them to synchronize browse lists. +</para> + +<para> +If you want Samba to be the domain master, you should also set the +<smbconfoption name="os level"/> high enough to make sure it wins elections, and +set <smbconfoption name="preferred master"/> to <constant>yes</constant>, to +get Samba to force an election on startup. +</para> + +<para> +All servers (including Samba) and clients should be using a WINS server to resolve NetBIOS names. If your +clients are only using broadcasting to resolve NetBIOS names, then two things will occur: +</para> + +<orderedlist> +<listitem> + <para> + Local Master Browsers will be unable to find a Domain Master Browser, as they will be looking only on the local subnet. + </para> +</listitem> + +<listitem> + <para> + If a client happens to get hold of a domain-wide browse list and a user attempts to access a + host in that list, it will be unable to resolve the NetBIOS name of that host. + </para> +</listitem> +</orderedlist> + +<para> +If, however, both Samba and your clients are using a WINS server, then: +</para> + +<orderedlist> +<listitem> + <para> + Local master browsers will contact the WINS server and, as long as Samba has registered that it is a Domain Master Browser with the WINS + server, the Local Master Browser will receive Samba's IP address as its Domain Master Browser. + </para> +</listitem> + +<listitem> + <para> + When a client receives a domain-wide browse list and a user attempts to access a host in that list, it will contact the WINS server to + resolve the NetBIOS name of that host. As long as that host has registered its NetBIOS name with the same WINS server, the user will + be able to see that host. + </para> +</listitem> +</orderedlist> + +</sect2> + +<sect2> +<title>Note about Broadcast Addresses</title> + +<para> +If your network uses a 0 based broadcast address (for example, if it ends in a 0) then you will strike problems. Windows for Workgroups +does not seem to support a zeros broadcast and you will probably find that browsing and name lookups will not work. +</para> +</sect2> + +<sect2> +<title>Multiple Interfaces</title> + +<para> +Samba supports machines with multiple network interfaces. If you have multiple interfaces, you will +need to use the <smbconfoption name="interfaces"/> option in &smb.conf; to configure them. +</para> +</sect2> +<sect2> +<title>Use of the Remote Announce Parameter</title> +<para> +The <smbconfoption name="remote announce"/> parameter of +&smb.conf; can be used to forcibly ensure +that all the NetBIOS names on a network get announced to a remote network. +The syntax of the <smbconfoption name="remote announce"/> parameter is: +<smbconfblock> +<smbconfoption name="remote announce">a.b.c.d [e.f.g.h] ...</smbconfoption> +</smbconfblock> +<emphasis>or</emphasis> +<smbconfblock> +<smbconfoption name="remote announce">a.b.c.d/WORKGROUP [e.f.g.h/WORKGROUP] ...</smbconfoption> +</smbconfblock> + +where: +<variablelist> + <varlistentry><term><replaceable>a.b.c.d</replaceable> and <replaceable>e.f.g.h</replaceable></term> + <listitem><para> +<indexterm><primary>LMB</primary><see>Local Master Browser</see></indexterm> +<indexterm><primary>Local Master Browser</primary></indexterm> + is either the LMB (Local Master Browser) IP address or the broadcast address of the remote network. + i.e., the LMB is at 192.168.1.10, or the address could be given as 192.168.1.255 where the netmask + is assumed to be 24 bits (255.255.255.0). When the remote announcement is made to the broadcast + address of the remote network, every host will receive our announcements. This is noisy and therefore + undesirable but may be necessary if we do not know the IP address of the remote LMB. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>WORKGROUP</replaceable></term> + <listitem><para>is optional and can be either our own workgroup or that of the remote network. If you use the + workgroup name of the remote network, our NetBIOS machine names will end up looking like + they belong to that workgroup. This may cause name resolution problems and should be avoided. + </para></listitem> + </varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>Use of the Remote Browse Sync Parameter</title> + +<para> +The <smbconfoption name="remote browse sync"/> parameter of +&smb.conf; is used to announce to another LMB that it must synchronize its NetBIOS name list with our +Samba LMB. This works only if the Samba server that has this option is +simultaneously the LMB on its network segment. +</para> + +<para> +The syntax of the <smbconfoption name="remote browse sync"/> parameter is: + +<smbconfblock> +<smbconfoption name="remote browse sync"><replaceable>a.b.c.d</replaceable></smbconfoption> +</smbconfblock> + +where <replaceable>a.b.c.d</replaceable> is either the IP address of the +remote LMB or else is the network broadcast address of the remote segment. +</para> + +</sect2> + +</sect1> + +<sect1> +<title>WINS &smbmdash; The Windows Inter-networking Name Server</title> + +<para> +Use of WINS (either Samba WINS or MS Windows NT Server WINS) is highly +recommended. Every NetBIOS machine registers its name together with a +name_type value for each of several types of service it has available. +It registers its name directly as a unique (the type 0x03) name. +It also registers its name if it is running the LanManager compatible +server service (used to make shares and printers available to other users) +by registering the server (the type 0x20) name. +</para> + +<para> +All NetBIOS names are up to 15 characters in length. The name_type variable +is added to the end of the name, thus creating a 16 character name. Any +name that is shorter than 15 characters is padded with spaces to the 15th +character. Thus, all NetBIOS names are 16 characters long (including the +name_type information). +</para> + +<para> +WINS can store these 16-character names as they get registered. A client +that wants to log onto the network can ask the WINS server for a list +of all names that have registered the NetLogon service name_type. This saves +broadcast traffic and greatly expedites logon processing. Since broadcast +name resolution cannot be used across network segments this type of +information can only be provided via WINS or via a statically configured +<filename>lmhosts</filename> file that must reside on all clients in the +absence of WINS. +</para> + +<para> +WINS also serves the purpose of forcing browse list synchronization by all +LMBs. LMBs must synchronize their browse list with the DMB (Domain Master +Browser) and WINS helps the LMB to identify its DMB. By definition this +will work only within a single workgroup. Note that the Domain Master Browser +has nothing to do with what is referred to as an MS Windows NT Domain. The +later is a reference to a security environment while the DMB refers to the +master controller for browse list information only. +</para> + +<para> +WINS will work correctly only if every client TCP/IP protocol stack +has been configured to use the WINS servers. Any client that has not been +configured to use the WINS server will continue to use only broadcast-based +name registration so WINS may never get to know about it. In any case, +machines that have not registered with a WINS server will fail name to address +lookup attempts by other clients and will therefore cause workstation access +errors. +</para> + +<para> +To configure Samba as a WINS server just add +<smbconfoption name="wins support">yes</smbconfoption> to the &smb.conf; +file [global] section. +</para> + +<para> +To configure Samba to register with a WINS server just add +<smbconfoption name="wins server">a.b.c.d</smbconfoption> +to your &smb.conf; file <smbconfsection name="[global]"/> section. +</para> + +<important><para> +Never use both <smbconfoption name="wins support">yes</smbconfoption> together +with <smbconfoption name="wins server">a.b.c.d</smbconfoption> +particularly not using its own IP address. Specifying both will cause &nmbd; to refuse to start! +</para></important> + +<sect2> +<title>WINS Server Configuration</title> + +<para> +Either a Samba Server or a Windows NT Server machine may be set up +as a WINS server. To configure a Samba Server to be a WINS server you must +add to the &smb.conf; file on the selected Server the following line to +the <smbconfsection name="[global]"/> section: +</para> + +<para> +<smbconfblock> +<smbconfoption name="wins support">yes</smbconfoption> +</smbconfblock> +</para> + +<para> +Versions of Samba prior to 1.9.17 had this parameter default to +yes. If you have any older versions of Samba on your network it is +strongly suggested you upgrade to a recent version, or at the very +least set the parameter to <quote>no</quote> on all these machines. +</para> + +<para> +Machines configured with <smbconfoption name="wins support">yes</smbconfoption> will keep a list of +all NetBIOS names registered with them, acting as a DNS for NetBIOS names. +</para> + +<para> +It is strongly recommended to set up only one WINS server. Do not set the +<smbconfoption name="wins support">yes</smbconfoption> option on more than one Samba +server. +</para> + +<para> +<indexterm><primary>replication</primary><secondary>WINS</secondary></indexterm> +To configure Windows NT/200x Server as a WINS server, install and configure +the WINS service. See the Windows NT/200x documentation for details. +Windows NT/200x WINS servers can replicate to each other, allowing more +than one to be set up in a complex subnet environment. As Microsoft +refuses to document the replication protocols, Samba cannot currently +participate in these replications. It is possible in the future that +a Samba-to-Samba WINS replication protocol may be defined, in which +case more than one Samba machine could be set up as a WINS server. +Currently only one Samba server should have the +<smbconfoption name="wins support">yes</smbconfoption> 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 <guilabel>Primary WINS Server</guilabel> field of +the <guilabel>Control Panel->Network->Protocols->TCP->WINS Server</guilabel> dialogs +in Windows 9x/Me or Windows NT/200x. To tell a Samba server the IP address +of the WINS server, add the following line to the <smbconfsection name="[global]"/> section of +all &smb.conf; files: +</para> + +<para> +<smbconfblock> +<smbconfoption name="wins server"><name or IP address></smbconfoption> +</smbconfblock> +</para> + +<para> +where <name or IP address> is either the DNS name of the WINS server +machine or its IP address. +</para> + +<para> +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 +<smbconfoption name="wins support">yes</smbconfoption> option and the +<smbconfoption name="wins server"><name></smbconfoption> option then +<command>nmbd</command> will fail to start. +</para> + +<para> +There are two possible scenarios for setting up cross-subnet browsing. +The first details setting up cross-subnet browsing on a network containing +Windows 9x/Me, Samba and Windows NT/200x machines that are not configured as +part of a Windows NT Domain. The second details setting up cross-subnet +browsing on networks that contain NT Domains. +</para> + +</sect2> + +<sect2> +<title>WINS Replication</title> + +<para> +<indexterm><primary>replication</primary><secondary>WINS</secondary></indexterm> +Samba-3 permits WINS replication through the use of the <filename>wrepld</filename> utility. +This tool is not currently capable of being used as it is still in active development. +As soon as this tool becomes moderately functional, we will prepare man pages and enhance this +section of the documentation to provide usage and technical details. +</para> + +</sect2> +<sect2> +<title>Static WINS Entries</title> + +<para> +Adding static entries to your Samba WINS server is actually fairly easy. +All you have to do is add a line to <filename>wins.dat</filename>, typically +located in <filename class="directory">/usr/local/samba/var/locks</filename> or +<filename>/var/run/samba</filename>. +</para> + +<para> +Entries in <filename>wins.dat</filename> take the form of: + +<programlisting> +"NAME#TYPE" TTL ADDRESS+ FLAGS +</programlisting> + +where NAME is the NetBIOS name, TYPE is the NetBIOS type, TTL is the +time-to-live as an absolute time in seconds, ADDRESS+ is one or more +addresses corresponding to the registration and FLAGS are the NetBIOS +flags for the registration. +</para> + +<para> +A typical dynamic entry looks like this: +<programlisting> +"MADMAN#03" 1055298378 192.168.1.2 66R +</programlisting> + +To make it static, all that has to be done is set the TTL to 0, like this: + +<programlisting> +"MADMAN#03" 0 192.168.1.2 66R +</programlisting> +</para> + +<para> +Though this method works with early Samba-3 versions, there is a +possibility that it may change in future versions if WINS replication +is added. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Helpful Hints</title> + +<para> +The following hints should be carefully considered as they are stumbling points +for many new network administrators. +</para> + +<sect2> +<title>Windows Networking Protocols</title> + +<para> +A common cause of browsing problems results from installing more than +one protocol on an MS Windows machine. +</para> + +<warning><para> +Do not use more than one protocol on MS Windows clients. +</para></warning> + +<para> +Every NetBIOS machine takes part in a process of electing the LMB (and DMB) +every 15 minutes. A set of election criteria is used to determine the order +of precedence for winning this election process. A machine running Samba or +Windows NT will be biased so the most suitable machine will predictably +win and thus retain its role. +</para> + +<para> +The election process is <quote>fought out</quote> so to speak over every NetBIOS network +interface. In the case of a Windows 9x/Me machine that has both TCP/IP and IPX +installed and has NetBIOS enabled over both protocols, the election will be +decided over both protocols. As often happens, if the Windows 9x/Me machine is +the only one with both protocols then the LMB may be won on the NetBIOS +interface over the IPX protocol. Samba will then lose the LMB role as Windows +9x/Me will insist it knows who the LMB is. Samba will then cease to function +as an LMB and thus browse list operation on all TCP/IP-only machines will +fail. +</para> + +<para> +Windows 95, 98, 98se, and Me are referred to generically as Windows 9x/Me. +The Windows NT4, 200x, and XP use common protocols. These are roughly +referred to as the Windows NT family, but it should be recognized that 2000 and +XP/2003 introduce new protocol extensions that cause them to behave +differently from MS Windows NT4. Generally, where a server does not support +the newer or extended protocol, these will fall back to the NT4 protocols. +</para> + +<para> +The safest rule of all to follow is: use only one protocol! +</para> + +</sect2> + +<sect2> +<title>Name Resolution Order</title> + +<para> +Resolution of NetBIOS names to IP addresses can take place using a number +of methods. The only ones that can provide NetBIOS name_type information +are: +</para> + +<itemizedlist> + <listitem><para>WINS &smbmdash; the best tool.</para></listitem> + <listitem><para>LMHOSTS &smbmdash; static and hard to maintain.</para></listitem> + <listitem><para>Broadcast &smbmdash; uses UDP and cannot resolve names across remote segments.</para></listitem> +</itemizedlist> + +<para> +Alternative means of name resolution include: +</para> +<itemizedlist> +<listitem><para>Static <filename>/etc/hosts</filename> &smbmdash; hard to maintain, and lacks name_type info.</para></listitem> +<listitem><para>DNS &smbmdash; is a good choice but lacks essential name_type info.</para></listitem> +</itemizedlist> + +<para> +Many sites want to restrict DNS lookups and avoid broadcast name +resolution traffic. The <parameter>name resolve order</parameter> parameter is of great help here. +The syntax of the <parameter>name resolve order</parameter> parameter is: +<smbconfblock> +<smbconfoption name="name resolve order">wins lmhosts bcast host</smbconfoption> +</smbconfblock> +<emphasis>or</emphasis> +<smbconfblock> +<smbconfoption name="name resolve order">wins lmhosts (eliminates bcast and host)</smbconfoption> +</smbconfblock> +The default is: +<smbconfblock> +<smbconfoption name="name resolve order">host lmhost wins bcast</smbconfoption> +</smbconfblock> +where <quote>host</quote> refers to the native methods used by the UNIX system +to implement the gethostbyname() function call. This is normally +controlled by <filename>/etc/host.conf</filename>, <filename>/etc/nsswitch.conf</filename> and <filename>/etc/resolv.conf</filename>. +</para> +</sect2> +</sect1> + +<sect1> +<title>Technical Overview of Browsing</title> + +<para> +SMB networking provides a mechanism by which clients can access a list +of machines in a network, a so-called <smbconfoption name="browse list"/>. 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 that aren't currently able to do server tasks. The browse +list is heavily used by all SMB clients. Configuration of SMB +browsing has been problematic for some Samba users, hence this +document. +</para> + +<para> +MS Windows 2000 and later versions, as with Samba-3 and later versions, can be +configured to not use NetBIOS over TCP/IP. When configured this way, +it is imperative that name resolution (using DNS/LDAP/ADS) be correctly +configured and operative. Browsing will not work if name resolution +from SMB machine names to IP addresses does not function correctly. +</para> + +<para> +Where NetBIOS over TCP/IP is enabled, use of a WINS server is highly +recommended to aid the resolution of NetBIOS (SMB) names to IP addresses. +WINS allows remote segment clients to obtain NetBIOS name_type information +that cannot be provided by any other means of name resolution. +</para> + +<sect2> +<title>Browsing Support in Samba</title> + +<para> +Samba facilitates browsing. The browsing is supported by &nmbd; +and is also controlled by options in the &smb.conf; file. +Samba can act as a local browse master for a workgroup and the ability +to support domain logons and scripts is now available. +</para> + +<para> +Samba can also act as a Domain Master Browser for a workgroup. This +means that it will collate lists from Local Master Browsers into a +wide area network server list. In order for browse clients to +resolve the names they may find in this list, it is recommended that +both Samba and your clients use a WINS server. +</para> + +<para> +Do not set Samba to be the Domain Master for a workgroup that has the same +name as an NT Domain. On each wide area network, you must only ever have one +Domain Master Browser per workgroup, regardless of whether it is NT, Samba +or any other type of domain master that is providing this service. +</para> + +<note><para> +<command>nmbd</command> can be configured as a WINS server, but it is not +necessary to specifically use Samba as your WINS server. MS Windows +NT4, Server or Advanced Server 200x can be configured as +your WINS server. In a mixed NT/200x server and Samba environment on +a Wide Area Network, it is recommended that you use the Microsoft +WINS server capabilities. In a Samba-only environment, it is +recommended that you use one and only one Samba server as the WINS server. +</para></note> + +<para> +To get browsing to work you need to run nmbd as usual, but will need +to use the <smbconfoption name="workgroup"/> option in &smb.conf; +to control what workgroup Samba becomes a part of. +</para> + +<para> +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 <quote>unusual</quote> purposes: announcements over the Internet, for +example. See <smbconfoption name="remote announce"/> in the +&smb.conf; man page. +</para> +</sect2> + +<sect2> +<title>Problem Resolution</title> + +<para> +If something does not work, the <filename>log.nmbd</filename> file will help +to track down the problem. Try a <smbconfoption name="log level"></smbconfoption> of 2 or 3 for finding +problems. Also note that the current browse list usually gets stored +in text form in a file called <filename>browse.dat</filename>. +</para> + +<para> +If it does not work, you should still be able to +type the server name as <filename>\\SERVER</filename> in <command>filemanager</command>, then +press enter and <command>filemanager</command> should display the list of available shares. +</para> + +<para> +Some people find browsing fails because they do not have the global +<smbconfoption name="guest account"/> 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> + +<para> +MS Windows 2000 and later (as with Samba) can be configured to disallow +anonymous (i.e., guest account) access to the IPC$ share. In that case, the +MS Windows 2000/XP/2003 machine acting as an SMB/CIFS client will use the +name of the currently logged-in user to query the IPC$ share. MS Windows +9x/Me clients are not able to do this and thus will not be able to browse +server resources. +</para> + +<para> +The other big problem people have is that their broadcast address, +netmask or IP address is wrong (specified with the <smbconfoption name="interfaces"></smbconfoption> option +in &smb.conf;) +</para> +</sect2> + +<sect2> +<title>Cross-Subnet Browsing</title> + +<para> +<indexterm><primary>replication</primary><secondary>browse lists</secondary></indexterm> +Since the release of Samba 1.9.17 (alpha1), Samba has supported the +replication of browse lists across subnet boundaries. This section +describes how to set this feature up in different settings. +</para> + +<para> +To see browse lists that span TCP/IP subnets (i.e., networks separated +by routers that do not pass broadcast traffic), you must set up at least +one WINS server. The WINS server acts as a DNS for NetBIOS names. This will +allow NetBIOS name-to-IP address translation to be completed by a direct +query of the WINS server. This is done via a directed UDP packet on +port 137 to the WINS server machine. The WINS server avoids the necessity +of default NetBIOS name-to-IP address translation, which is done +using UDP broadcasts from the querying machine. This means that machines +on one subnet will not be able to resolve the names of machines on +another subnet without using a WINS server. +</para> + +<para> +Remember, for browsing across subnets to work correctly, all machines, +be they Windows 95, Windows NT or Samba servers, must have the IP address +of a WINS server given to them by a DHCP server, or by manual configuration +(for Windows 9x/Me and Windows NT/200x/XP, this is in the TCP/IP Properties, under Network +settings); for Samba, this is in the &smb.conf; file. +</para> + +<sect3> +<title>Behavior of Cross-Subnet Browsing</title> + +<para> +Cross-subnet Browsing is a complicated dance, containing multiple +moving parts. It has taken Microsoft several years to get the code +that achieves this correct, and Samba lags behind in some areas. +Samba is capable of cross-subnet browsing when configured correctly. +</para> + +<para> +Consider a network set up as in <link linkend="browsing1">Cross-Subnet Browsing Example</link>. +</para> + +<image id="browsing1"> + <imagedescription>Cross-Subnet Browsing Example.</imagedescription> + <imagefile scale="40">browsing1</imagefile> +</image> + +<para> +This consists of 3 subnets (1, 2, 3) connected by two routers +(R1, R2) which do not pass broadcasts. Subnet 1 has five machines +on it, subnet 2 has four machines, subnet 3 has four machines. Assume +for the moment that all machines are configured to be in the +same workgroup (for simplicity's sake). Machine N1_C on subnet 1 +is configured as Domain Master Browser (i.e., it will collate the +browse lists for the workgroup). Machine N2_D is configured as +WINS server and all the other machines are configured to register +their NetBIOS names with it. +</para> + +<para> +As these machines are booted up, elections for master browsers +will take place on each of the three subnets. Assume that machine +N1_C wins on subnet 1, N2_B wins on subnet 2, and N3_D wins on +subnet 3. These machines are known as Local Master Browsers for +their particular subnet. N1_C has an advantage in winning as the +Local Master Browser on subnet 1 as it is set up as Domain Master +Browser. +</para> + +<para> +On each of the three networks, machines that are configured to +offer sharing services will broadcast that they are offering +these services. The Local Master Browser on each subnet will +receive these broadcasts and keep a record of the fact that +the machine is offering a service. This list of records is +the basis of the browse list. For this case, assume that +all the machines are configured to offer services, so all machines +will be on the browse list. +</para> + +<para> +For each network, the Local Master Browser on that network is +considered <quote>authoritative</quote> for all the names it receives via +local broadcast. This is because a machine seen by the Local Master +Browser via a local broadcast must be on the same network as the +Local Master Browser and thus is a <quote>trusted</quote> +and <quote>verifiable</quote> resource. Machines on other networks that +the Local Master Browsers learn about when collating their +browse lists have not been directly seen. These records are +called <quote>non-authoritative.</quote> +</para> + +<para> +At this point the browse lists appear as shown in <link linkend="browsubnet">the next example</link> (these are +the machines you would see in your network neighborhood if you looked in it on a particular network right now). +</para> + +<para> +<table frame="all" id="browsubnet"> + <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> + + <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> +At this point all the subnets are separate, and no machine is seen across any of the subnets. +</para> + +<para> +Now examine subnet 2. As soon as N2_B has become the Local +Master Browser it looks for a Domain Master Browser with which to synchronize +its browse list. It does this by querying the WINS server +(N2_D) for the IP address associated with the NetBIOS name +WORKGROUP<1B>. This name was registered by the Domain Master +Browser (N1_C) with the WINS server as soon as it was started. +</para> + +<para> +Once N2_B knows the address of the Domain Master Browser, it +tells it that is the Local Master Browser for subnet 2 by +sending a <emphasis>MasterAnnouncement</emphasis> packet as a UDP port 138 packet. +It then synchronizes with it by doing a <emphasis>NetServerEnum2</emphasis> call. This +tells the Domain Master Browser to send it all the server +names it knows about. Once the Domain Master Browser receives +the <emphasis>MasterAnnouncement</emphasis> packet, it schedules a synchronization +request to the sender of that packet. After both synchronizations +are complete the browse lists look as shown in <link linkend="brsbex">following example</link>: +</para> + +<table frame="all" id="brsbex"> + <title>Browse Subnet Example 2</title> + <tgroup cols="3"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <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(*)</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> + +<para> +Servers with an (*) after them are non-authoritative names. +</para> + +<para> +At this point users looking in their network neighborhood on +subnets 1 or 2 will see all the servers on both, users on +subnet 3 will still only see the servers on their own subnet. +</para> + +<para> +The same sequence of events that occurred for N2_B now occurs +for the Local Master Browser on subnet 3 (N3_D). When it +synchronizes browse lists with the Domain Master Browser (N1_A) +it gets both the server entries on subnet 1, and those on +subnet 2. After N3_D has synchronized with N1_C and vica versa, +the browse lists will appear as shown in <link linkend="brsex2">following example</link>. +</para> + +<table frame="all" id="brsex2"> + <title>Browse Subnet Example 3</title> + <tgroup cols="3" align="left"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + + <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(*)</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> + +<para> +Servers with an (*) after them are non-authoritative names. +</para> + +<para> +At this point, users looking in their network neighborhood on +subnets 1 or 3 will see all the servers on all subnets, while users on +subnet 2 will still only see the servers on subnets 1 and 2, but not 3. +</para> + +<para> +Finally, the Local Master Browser for subnet 2 (N2_B) will sync again +with the Domain Master Browser (N1_C) and will receive the missing +server entries. Finally, as when a steady state (if no machines +are removed or shut off) has been achieved, the browse lists will appear +as shown in <link linkend="brsex3">example below</link>. +</para> + +<table frame="all" id="brsex3"> + <title>Browse Subnet Example 4</title> + <tgroup cols="3" align="left"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + + <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> + +<para> +Servers with an (*) after them are non-authoritative names. +</para> + +<para> +Synchronizations between the Domain Master Browser and Local +Master Browsers will continue to occur, but this should remain a +steady state operation. +</para> + +<para> +If either router R1 or R2 fails, the following will occur: +</para> + +<orderedlist> +<listitem> + <para> + Names of computers on each side of the inaccessible network fragments + will be maintained for as long as 36 minutes in the network neighborhood + lists. + </para> +</listitem> + +<listitem> + <para> + Attempts to connect to these inaccessible computers will fail, but the + names will not be removed from the network neighborhood lists. + </para> +</listitem> + +<listitem> + <para> + If one of the fragments is cut off from the WINS server, it will only + be able to access servers on its local subnet using subnet-isolated + broadcast NetBIOS name resolution. The effects are similar to that of + losing access to a DNS server. + </para> +</listitem> +</orderedlist> +</sect3> +</sect2> +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +Many questions are asked on the mailing lists regarding browsing. The majority of browsing +problems originate from incorrect configuration of NetBIOS name resolution. Some are of +particular note. +</para> + +<sect2> +<title>How Can One Flush the Samba NetBIOS Name Cache without Restarting Samba?</title> + +<para> +<indexterm><primary>flush name cache</primary></indexterm> +Samba's <command>nmbd</command> process controls all browse list handling. Under normal circumstances it is +safe to restart <command>nmbd</command>. This will effectively flush the Samba NetBIOS name cache and cause it +to be rebuilt. This does not make certain that a rogue machine name will not re-appear +in the browse list. When <command>nmbd</command> is taken out of service, another machine on the network will +become the Browse Master. This new list may still have the rogue entry in it. If you really +want to clear a rogue machine from the list, every machine on the network will need to be +shut down and restarted after all machines are down. Failing a complete restart, the only +other thing you can do is wait until the entry times out and is then flushed from the list. +This may take a long time on some networks (perhaps months). +</para> + +</sect2> + +<sect2> + <title>Server Resources Can Not Be Listed</title> + +<para><quote>My Client Reports <quote>This server is not configured to list shared resources</quote></quote></para> + + +<para> +Your guest account is probably invalid for some reason. Samba uses the +guest account for browsing in <command>smbd</command>. Check that your guest account is +valid. +</para> + +<para>Also see <smbconfoption name="guest account"/> in the &smb.conf; man page.</para> + +</sect2> + +<sect2> + <title>I get an <errorname>`Unable to browse the network'</errorname> error</title> + + <para>This error can have multiple causes: +<indexterm><primary>browsing problems</primary></indexterm> + </para> + + <itemizedlist> + <listitem><para>There is no Local Master Browser. Configure &nmbd; + or any other machine to serve as Local Master Browser.</para></listitem> + <listitem><para>You cannot log onto the machine that is the local master + browser. Can you logon to it as a guest user? </para></listitem> + <listitem><para>There is no IP connectivity to the Local Master Browser. + Can you reach it by broadcast?</para></listitem> +</itemizedlist> +</sect2> + +<sect2> +<title>Browsing of Shares and Directories is Very Slow</title> + +<para><quote> +<indexterm><primary>slow browsing</primary></indexterm> +There are only two machines on a test network. One a Samba server, the other a Windows XP machine. +Authentication and logons work perfectly, but when I try to explore shares on the Samba server, the +Windows XP client becomes unresponsive. Sometimes it does not respond for some minutes. Eventually, +Windows Explorer will respond and displays files and directories without problem. +display file and directory.</quote> +</para> + +<para><quote> +But, the share is immediately available from a command shell (<command>cmd</command>, followed by +exploration with dos command. Is this a Samba problem or is it a Windows problem? How can I solve this? +</quote></para> + +<para> +Here are a few possibilities: +</para> + +<variablelist> + <varlistentry> + <term>Bad Networking Hardware</term> + <listitem><para> +<indexterm><primary>bad hardware</primary></indexterm> +<indexterm><primary>WebClient</primary></indexterm> + Most common defective hardware problems center around low cost or defective HUBs, routers, + Network Interface Controllers (NICs) and bad wiring. If one piece of hardware is defective + the whole network may suffer. Bad networking hardware can cause data corruption. Most bad + networking hardware problems are accompanied by an increase in apparent network traffic, + but not all. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>The Windows XP WebClient</term> + <listitem><para> + A number of sites have reported similar slow network browsing problems and found that when + the WebClient service is turned off, the problem disappears. This is certainly something + that should be explored as it is a simple solution &smbmdash; if it works. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Inconsistent WINS Configuration</term> + <listitem><para> + This type of problem is common when one client is configured to use a WINS server (that is + a TCP/IP configuration setting) and there is no WINS server on the network. Alternately, + this will happen is there is a WINS server and Samba is not configured to use it. The use of + WINS is highly recommended if the network is using NetBIOS over TCP/IP protocols. If use + of NetBIOS over TCP/IP is disabled on all clients, Samba should not be configured as a WINS + server neither should it be configured to use one. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Incorrect DNS Configuration</term> + <listitem><para> + If use of NetBIOS over TCP/IP is disabled, Active Directory is in use and the DNS server + has been incorrectly configured. Refer <link linkend="adsdnstech">DNS and Active Directory</link> for more information. + </para></listitem> + </varlistentry> +</variablelist> + +</sect2> +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Other-Clients.xml b/docs/Samba3-HOWTO/TOSHARG-Other-Clients.xml new file mode 100644 index 0000000000..0a0d78fd91 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Other-Clients.xml @@ -0,0 +1,353 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="Other-Clients"> +<chapterinfo> + &author.jelmer; + &author.jht; + &author.danshearer; + <author>&person.jmcd;<contrib>OS/2</contrib></author> + <pubdate>5 Mar 2001</pubdate> +</chapterinfo> + +<title>Samba and Other CIFS Clients</title> + +<para>This chapter contains client-specific information.</para> + +<sect1> +<title>Macintosh Clients</title> + +<para> +Yes. <ulink url="http://www.thursby.com/">Thursby</ulink> has a CIFS Client/Server called <ulink url="http://www.thursby.com/products/dave.html">DAVE.</ulink> +They test it against Windows 95, Windows NT /200x/XP and Samba for +compatibility issues. At the time of this writing, DAVE was at version +4.1. Please refer to Thursby's Web site for more information regarding this +product. +</para> + +<para> +Alternatives &smbmdash; There are two free implementations of AppleTalk for +several kinds of UNIX machines and several more commercial ones. +These products allow you to run file services and print services +natively to Macintosh users, with no additional support required on +the Macintosh. The two free implementations are +<ulink url="http://www.umich.edu/~rsug/netatalk/">Netatalk,</ulink> and +<ulink url="http://www.cs.mu.oz.au/appletalk/atalk.html">CAP.</ulink> +What Samba offers MS Windows users, these packages offer to Macs. +For more info on these packages, Samba, and Linux (and other UNIX-based systems), see +<ulink noescape="1" url="http://www.eats.com/linux_mac_win.html">http://www.eats.com/linux_mac_win.html.</ulink> +</para> + +<para>Newer versions of the Macintosh (Mac OS X) include Samba.</para> + +</sect1> + +<sect1> +<title>OS2 Client</title> + + <sect2> + <title>Configuring OS/2 Warp Connect or OS/2 Warp 4</title> + + <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 <quote>NetBIOS over TCP/IP</quote> driver (TCPBEUI)</para></listitem> + </itemizedlist> + + <para>Installing the first two together with the base operating + system on a blank system is explained in the Warp manual. If Warp + has already been installed, but you now want to install the + networking support, use the <quote>Selective Install for Networking</quote> + object in the <quote>System Setup</quote> folder.</para> + + <para>Adding the <quote>NetBIOS over TCP/IP</quote> driver is not described + in the manual and just barely in the online documentation. Start + <command>MPTS.EXE</command>, click on <guiicon>OK</guiicon>, click on <guimenu>Configure LAPS</guimenu> and click + on <guimenu>IBM OS/2 NETBIOS OVER TCP/IP</guimenu> in <guilabel>Protocols</guilabel>. This line + is then moved to <guilabel>Current Configuration</guilabel>. Select that line, + click on <guimenuitem>Change number</guimenuitem> and increase it from 0 to 1. Save this + configuration.</para> + + <para>If the Samba server is not on your local subnet, you + can optionally add IP names and addresses of these servers + to the <guimenu>Names List</guimenu>, or specify a WINS server (NetBIOS + Nameserver in IBM and RFC terminology). For Warp Connect, you + may need to download an update for <constant>IBM Peer</constant> to bring it on + the same level as Warp 4. See the Web page mentioned above.</para> + </sect2> + + <sect2> + <title>Configuring Other Versions of OS/2</title> + + <para>This sections deals with configuring OS/2 Warp 3 (not Connect), OS/2 1.2, 1.3 or 2.x.</para> + + <para>You can use the free Microsoft LAN Manager 2.2c Client for OS/2 that is + available from + <ulink noescape="1" url="ftp://ftp.microsoft.com/BusSys/Clients/LANMAN.OS2/"> + ftp://ftp.microsoft.com/BusSys/Clients/LANMAN.OS2/</ulink>. In a nutshell, edit + the file <filename>\OS2VER</filename> in the root directory of the OS/2 boot partition and add the lines:</para> + + <para><programlisting> + 20=setup.exe + 20=netwksta.sys + 20=netvdd.sys + </programlisting></para> + + <para>before you install the client. Also, do not use the included NE2000 driver because it is buggy. + Try the NE2000 or NS2000 driver from <ulink noescape="1" url="ftp://ftp.cdrom.com/pub/os2/network/ndis/"> + ftp://ftp.cdrom.com/pub/os2/network/ndis/</ulink> instead. + </para> + </sect2> + + <sect2> + <title>Printer Driver Download for OS/2 Clients</title> + + <para>Create a share called <smbconfsection name="[PRINTDRV]"/> that is + world-readable. Copy your OS/2 driver files there. The <filename>.EA_</filename> + 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, + <smbconfoption name="os2 driver map"><replaceable>filename</replaceable></smbconfoption>. + Next, 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><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> + + <para>If you only specify the OS/2 driver name, and not the + device name, the first attempt to download the driver will + actually download the files, but the OS/2 client will tell + you the driver is not available. On the second attempt, it + will work. This is fixed simply by adding the device name + to the mapping, after which it will work on the first attempt. + </para> + </sect2> +</sect1> + +<sect1> +<title>Windows for Workgroups</title> + +<sect2> +<title>Latest TCP/IP Stack from Microsoft</title> + +<para>Use the latest TCP/IP stack from Microsoft if you use Windows +for Workgroups. The early TCP/IP stacks had lots of bugs.</para> + +<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 <filename>/Softlib/MSLFILES/TCP32B.EXE</filename>. +There is an update.txt file there that describes the problems that were +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> + +<para>More information about this patch is available in <ulink url="http://support.microsoft.com/kb/q99891/">Knowledge base article 99891</ulink>.</para> + +</sect2> + +<sect2> +<title>Delete .pwl Files After Password Change</title> + +<para> +Windows for Workgroups does a lousy job with passwords. When you change passwords on either +the UNIX box or the PC, the safest thing to do is to delete the .pwl files in the Windows +directory. The PC will complain about not finding the files, but will soon get over it, +allowing you to enter the new password. +</para> + +<para> +If you do not do this, you may find that Windows for Workgroups remembers and uses the old +password, even if you told it a new one. +</para> + +<para> +Often Windows for Workgroups will totally ignore a password you give it in a dialog box. +</para> + +</sect2> + +<sect2> +<title>Configuring Windows for Workgroups Password Handling</title> + +<para> +There is a program call <filename>admincfg.exe</filename> +on the last disk (disk 8) of the WFW 3.11 disk set. To install it, +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, i.e., +Disable Password Caching and so on. +for use with <smbconfoption name="security">user</smbconfoption>. +</para> + +</sect2> + +<sect2> +<title>Password Case Sensitivity</title> + +<para>Windows for Workgroups uppercases the password before sending it to the server. +UNIX passwords can be case-sensitive though. Check the &smb.conf; information on +<smbconfoption name="password level"/> to specify what characters +Samba should try to uppercase when checking.</para> + +</sect2> + +<sect2> +<title>Use TCP/IP as Default Protocol</title> + +<para>To support print queue reporting, you may find +that you have to use TCP/IP as the default protocol under +Windows for Workgroups. For some reason, if you leave NetBEUI as the default, +it may break the print queue reporting on some systems. +It is presumably a Windows for Workgroups bug.</para> + +</sect2> + +<sect2> +<title>Speed Improvement</title> + +<para> + Note that some people have found that setting <parameter>DefaultRcvWindow</parameter> in +the <smbconfsection name="[MSTCP]"/> section of the +<filename>SYSTEM.INI</filename> file under Windows for Workgroups to 3072 gives a +big improvement. +</para> + +<para> +My own experience with DefaultRcvWindow is that I get a much better +performance with a large value (16384 or larger). Other people have +reported that anything over 3072 slows things down enormously. One +person even reported a speed drop of a factor of 30 when he went from +3072 to 8192. +</para> +</sect2> +</sect1> + +<sect1> +<title>Windows 95/98</title> + +<para> +When using Windows 95 OEM SR2, the following updates are recommended where Samba +is being used. Please note that the above change will effect you once these +updates have been installed. +</para> + +<para> +There are more updates than the ones mentioned here. You are referred to the +Microsoft Web site for all currently available updates to your specific version +of Windows 95. +</para> + +<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 <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 notice a significant speedup when accessing network +neighborhood services. +</para> + +<sect2> +<title>Speed Improvement</title> + +<para> +Configure the Windows 95 TCP/IP registry settings to give better +performance. I use a program called <command>MTUSPEED.exe</command> that I got off the +Internet. There are various other utilities of this type freely available. +</para> + +</sect2> + +</sect1> + +<sect1> +<title>Windows 2000 Service Pack 2</title> + +<para> +There are several annoyances with Windows 2000 SP2. One of which +only appears when using a Samba server to host user profiles +to Windows 2000 SP2 clients in a Windows domain. This assumes +that Samba is a member of the domain, but the problem will +most likely occur if it is not. +</para> + +<para> +In order to serve profiles successfully to Windows 2000 SP2 +clients (when not operating as a PDC), Samba must have +<smbconfoption name="nt acl support">no</smbconfoption> +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 +Denied) and create multiple copies of it on disk (DOMAIN.user.001, +DOMAIN.user.002, and so on). See the &smb.conf; man page +for more details on this option. Also note that the +<smbconfoption name="nt acl support"/> parameter was formally a global parameter in +releases prior to Samba 2.2.2. +</para> + +<para> +<link linkend="minimalprofile">Following example</link> provides a minimal profile share. +</para> + +<para><smbconfexample id="minimalprofile"> +<title>Minimal profile share</title> +<smbconfsection name="[profile]"/> +<smbconfoption name="path">/export/profile</smbconfoption> +<smbconfoption name="create mask">0600</smbconfoption> +<smbconfoption name="directory mask">0700</smbconfoption> +<smbconfoption name="nt acl support">no</smbconfoption> +<smbconfoption name="read only">no</smbconfoption> +</smbconfexample></para> + +<para> +The reason for this bug is that the Windows 200x SP2 client copies +the security descriptor for the profile that contains +the Samba server's SID, and not the domain SID. The client +compares the SID for SAMBA\user and realizes it is +different from the one assigned to DOMAIN\user. Hence, the reason +for the <errorname>access denied</errorname> message. +</para> + +<para> +By disabling the <smbconfoption name="nt acl support"/> parameter, Samba will send +the Windows 200x 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><emphasis>DOMAIN\user <quote>Full Control</quote></emphasis>></para> + +<note><para>This bug does not occur when using Winbind to +create accounts on the Samba host for Domain users.</para></note> + +</sect1> + +<sect1> +<title>Windows NT 3.1</title> + +<para>If you have problems communicating across routers with Windows +NT 3.1 workstations, read <ulink url="http://support.microsoft.com/default.aspx?scid=kb;Q103765">this Microsoft Knowledge Base article.</ulink> + +</para> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-PAM.xml b/docs/Samba3-HOWTO/TOSHARG-PAM.xml new file mode 100644 index 0000000000..4a09e808b4 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-PAM.xml @@ -0,0 +1,941 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="pam"> +<chapterinfo> + &author.jht; + <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-Based Distributed Authentication</title> + +<para> +This chapter 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 management +possibilities and in particular how to deploy tools like <filename>pam_smbpass.so</filename> to your advantage. +</para> + +<note><para> +The use of Winbind requires more than PAM configuration alone. +Please refer to <link linkend="winbind">Winbind: Use of Domain Accounts</link>, for further information regarding Winbind. +</para></note> + +<sect1> +<title>Features and Benefits</title> + +<para> +A number of UNIX systems (e.g., 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 programs such as: <command>login</command>, +<command>passwd</command>, <command>chown</command>, and so on. +</para> + +<para> +PAM provides a mechanism that disconnects these security programs from the underlying +authentication/authorization infrastructure. PAM is configured by making appropriate modifications to one file +<filename>/etc/pam.conf</filename> (Solaris), or by editing individual control files that are +located in <filename>/etc/pam.d</filename>. +</para> + +<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 centralized on a +remote server. +</para> + +<para> +PAM support modules are available for: +</para> + +<variablelist> + <varlistentry><term><filename>/etc/passwd</filename></term><listitem> + <para> + There are several PAM modules that interact with this standard UNIX user + database. The most common are called: <filename>pam_unix.so</filename>, <filename>pam_unix2.so</filename>, <filename>pam_pwdb.so</filename> + and <filename>pam_userdb.so</filename>. + </para> + </listitem></varlistentry> + + <varlistentry><term>Kerberos</term><listitem> + <para> + The <filename>pam_krb5.so</filename> 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> + The <filename>pam_ldap.so</filename> 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> + The <filename>pam_ncp_auth.so</filename> module allows authentication off any bindery-enabled + NetWare Core Protocol-based server. + </para> + </listitem></varlistentry> + + <varlistentry><term>SMB Password</term><listitem> + <para> + This module, called <filename>pam_smbpass.so</filename>, 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> + The <filename>pam_smb_auth.so</filename> 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> + The <filename>pam_winbind.so</filename> 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> + There is a PAM RADIUS (Remote Access Dial-In User Service) authentication + module. In most cases, administrators 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 <filename>pam_smbpasswd.so</filename> and the <filename>pam_winbind.so</filename> 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 area 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, <filename>/etc/pam.conf</filename>, or the +<filename>/etc/pam.d/</filename> 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 <quote>#</quote> and extend to the next end-of-line; also, +module specification lines may be extended with a <quote>\</quote> 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> +<programlisting> +auth required /other_path/pam_strange_module.so +</programlisting> +</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/">The Official Linux-PAM home page.</ulink> +</para> + +<para> +A general configuration line of the <filename>/etc/pam.conf</filename> file has the following form: +</para> + +<para> +<programlisting> +service-name module-type control-flag module-path args +</programlisting> +</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> + The name of the service associated with this entry. Frequently, the service name is the conventional + name of the given application. For example, <command>ftpd</command>, <command>rlogind</command> and + <command>su</command>, and so on. + </para> + + <para> + There is a special service-name reserved for defining a default authentication mechanism. It has + the name <parameter>OTHER</parameter> and may be specified in either lower- or upper-case characters. + Note, when there is a module specified for a named service, the <parameter>OTHER</parameter> + entries are ignored. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>module-type</term><listitem> + <para> + One of (currently) four types of module. The four types are as follows: + </para> + + <itemizedlist> + <listitem><para> + <parameter>auth:</parameter> This module type provides two aspects of authenticating the user. + It establishes that the user is who he claims 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> + <parameter>account:</parameter> 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 <quote>root</quote> login only on the console. + </para></listitem> + + <listitem><para> + <parameter>session:</parameter> Primarily, this module is associated with doing things that need + to be done for the user before and after they can be given service. Such things include the logging + of information concerning the opening and closing of some data exchange with a user, mounting + directories, and so on. + </para></listitem> + + <listitem><para> + <parameter>password:</parameter> This last module type is required for updating the authentication + token associated with the user. Typically, there is one module for each <quote>challenge/response</quote> + -based authentication <parameter>(auth)</parameter> module type. + </para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry><term>control-flag</term><listitem> + <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 + keywords: <parameter>required, requisite, sufficient and optional</parameter>. + </para> + + <para> + The Linux-PAM library interprets these keywords in the following manner: + </para> + + <itemizedlist> + <listitem><para> + <parameter>required:</parameter> 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> + <parameter>requisite:</parameter> 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. 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> + <parameter>sufficient:</parameter> The success of this module is deemed <parameter>sufficient</parameter> 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 <quote>stacked</quote> modules of this type are invoked. + (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> + <parameter>optional:</parameter> 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 delimited with square brackets and + consists of a series of <parameter>value=action</parameter> tokens: + </para> + +<para><programlisting> +[value1=action1 value2=action2 ...] +</programlisting></para> + + <para> + Here, <parameter>value1</parameter> is one of the following return values: +<screen> +<parameter>success; open_err; symbol_err; service_err; system_err; buf_err;</parameter> +<parameter>perm_denied; auth_err; cred_insufficient; authinfo_unavail;</parameter> +<parameter>user_unknown; maxtries; new_authtok_reqd; acct_expired; session_err;</parameter> +<parameter>cred_unavail; cred_expired; cred_err; no_module_data; conv_err;</parameter> +<parameter>authtok_err; authtok_recover_err; authtok_lock_busy;</parameter> +<parameter>authtok_disable_aging; try_again; ignore; abort; authtok_expired;</parameter> +<parameter>module_unknown; bad_item;</parameter> and <parameter>default</parameter>. +</screen> +</para> + + <para> + The last of these <parameter>(default)</parameter> can be used to set the action for those return values that are not explicitly defined. + </para> + + <para> + The <parameter>action1</parameter> can be a positive integer or one of the following tokens: + <parameter>ignore; ok; done; bad; die;</parameter> and <parameter>reset</parameter>. + 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> + <parameter>ignore:</parameter> 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> + <parameter>bad:</parameter> 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> + <parameter>die:</parameter> Equivalent to bad with the side effect of terminating the module stack and + PAM immediately returning to the application. + </para></listitem> + + <listitem><para> + <parameter>ok:</parameter> 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 <parameter>ok</parameter> value will not be used to override that value. + </para></listitem> + + <listitem><para> + <parameter>done:</parameter> Equivalent to <parameter>ok</parameter> with the side effect of terminating the module stack and + PAM immediately returning to the application. + </para></listitem> + + <listitem><para> + <parameter>reset:</parameter> Clears all memory of the state of the module stack and starts again with + the next stacked module. + </para></listitem> + </itemizedlist> + + <para> + Each of the four keywords: <parameter>required; requisite; sufficient;</parameter> and <parameter>optional</parameter>, + have an equivalent expression in terms of the [...] syntax. They are as follows: + </para> + + <para> + <itemizedlist> + <listitem><para> + <parameter>required</parameter> is equivalent to <parameter>[success=ok new_authtok_reqd=ok ignore=ignore default=bad]</parameter>. + </para></listitem> + + <listitem><para> + <parameter>requisite</parameter> is equivalent to <parameter>[success=ok new_authtok_reqd=ok ignore=ignore default=die]</parameter>. + </para></listitem> + + <listitem><para> + <parameter>sufficient</parameter> is equivalent to <parameter>[success=done new_authtok_reqd=done<?latex \linebreak ?> default=ignore]</parameter>. + </para></listitem> + + <listitem><para> + <parameter>optional</parameter> is equivalent to <parameter>[success=ok new_authtok_reqd=ok default=ignore]</parameter>. + </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 + <parameter>[ ... value=action ... ]</parameter> 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> + The path-name of the dynamically loadable object file; the pluggable module itself. If the first character of the + module path is <quote>/</quote>, 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 arguments 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> + If you wish to include spaces in an argument, you should surround that argument with square brackets. For example: + </para> + +<para><programlisting> +squid auth required pam_mysql.so user=passwd_query passwd=mada \ +db=eminence [query=select user_name from internet_service where \ +user_name=<quote>%u</quote> and password=PASSWORD(<quote>%p</quote>) and service=<quote>web_proxy</quote>] +</programlisting></para> + + <para> + When using this convention, you can include <quote>[</quote> characters inside the string, and if you wish to have a <quote>]</quote> + character inside the string that will survive the argument parsing, you should use <quote>\[</quote>. In other words: + </para> + +<para><programlisting> +[..[..\]..] --> ..[..].. +</programlisting></para> + + <para> + Any line in one of the configuration files 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. +This example had all options uncommented and is probably not usable +because it stacks many conditions before allowing successful completion +of the login process. Essentially all conditions can be disabled +by commenting them out, except the calls to <filename>pam_pwdb.so</filename>. +</para> + +<sect3> +<title>PAM: Original Login Config</title> + +<para> + <smbfile name="pam-login-default"> + <programlisting> +#%PAM-1.0 +# The PAM configuration file for the <quote>login</quote> 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> +</smbfile></para> + +</sect3> + +<sect3> +<title>PAM: Login Using <filename>pam_smbpass</filename></title> + +<para> +PAM allows use of replaceable 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> + +<para> +The following example for the login program replaces the use of +the <filename>pam_pwdb.so</filename> module that uses the system +password database (<filename>/etc/passwd</filename>, +<filename>/etc/shadow</filename>, <filename>/etc/group</filename>) with +the module <filename>pam_smbpass.so</filename>, which uses the Samba +database which contains the Microsoft MD4 encrypted password +hashes. This database is stored in either +<filename>/usr/local/samba/private/smbpasswd</filename>, +<filename>/etc/samba/smbpasswd</filename>, or in +<filename>/etc/samba.d/smbpasswd</filename>, depending on the +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 +<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> + <smbfile name="pam-login-smbpass"> + <programlisting> +#%PAM-1.0 +# The PAM configuration file for the <quote>login</quote> 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></smbfile></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> + <smbfile name="pam-samba-default"> + <programlisting> +#%PAM-1.0 +# The PAM configuration file for the <quote>samba</quote> 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></smbfile></para> + +<para> +In the following example, the decision has been made to use the +<command>smbpasswd</command> database even for basic Samba authentication. Such a +decision could also be made for the <command>passwd</command> program and would +thus allow the <command>smbpasswd</command> passwords to be changed using the +<command>passwd</command> program: +</para> + +<para><smbfile name="pam-samba-smbpass"> + <programlisting> +#%PAM-1.0 +# The PAM configuration file for the <quote>samba</quote> 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> +</smbfile></para> + +<note><para>PAM allows stacking of authentication mechanisms. It is +also possible to pass information obtained within one PAM module through +to the next module in the PAM stack. Please refer to the documentation for +your particular system implementation for details regarding the specific +capabilities of PAM in this environment. Some Linux implementations also +provide the <filename>pam_stack.so</filename> module that allows all +authentication to be configured in a single central file. The +<filename>pam_stack.so</filename> method has some devoted followers +on the basis that it allows for easier administration. As with all issues in +life though, every decision makes trade-offs, so you may want to examine the +PAM documentation for further helpful information. +</para></note> + +</sect3> + +</sect2> + +<sect2> +<title>&smb.conf; PAM Configuration</title> + +<para> + There is an option in &smb.conf; called <smbconfoption name="obey pam restrictions"/>. +The following is from the online help for this option in SWAT; +</para> + +<para> +When Samba 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 ignore any account or session management. Samba always +ignores PAM for authentication in the case of <smbconfoption name="encrypt passwords">yes</smbconfoption>. +The reason is that PAM modules cannot support the challenge/response authentication mechanism needed in the presence of SMB +password encryption. +</para> + +<para>Default: <smbconfoption name="obey pam restrictions">no</smbconfoption></para> + +</sect2> + +<sect2> +<title>Remote CIFS Authentication Using <filename>winbindd.so</filename></title> + +<para> +All operating systems depend on the provision of users credentials acceptable 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 <smbconfoption name="passdb backend"></smbconfoption>, +such as <parameter>ldap</parameter>, will allow the establishment of a centrally managed, distributed user/password +database that can also be used by all PAM-aware (e.g., Linux) programs and applications. This arrangement can have +particularly potent advantages compared with the use of Microsoft Active Directory Service (ADS) in so far as +the 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 <command>winbindd</command>. If this file is deleted or corrupted, there is no way for <command>winbindd</command> +to determine which user and group IDs correspond to Windows NT user and group RIDs. +</para></warning> + +</sect2> + +<sect2> +<title>Password Synchronization Using <filename>pam_smbpass.so</filename></title> + +<para> +<filename>pam_smbpass</filename> is a PAM module that can be used on conforming systems to +keep the <filename>smbpasswd</filename> (Samba password) database in sync with the UNIX +password file. PAM (Pluggable Authentication Modules) is an API supported +under some UNIX operating systems, such as Solaris, HPUX and Linux, that provides a +generic interface to authentication mechanisms. +</para> + +<para> +This module authenticates a local <filename>smbpasswd</filename> user database. If you require +support for authenticating against a remote SMB server, or if you are +concerned about the presence of SUID root binaries on your system, it is +recommended that you use <filename>pam_winbind</filename> instead. +</para> + +<para> +Options recognized by this module are shown in <link linkend="smbpassoptions">next table</link>. +<table frame="all" id="smbpassoptions"> + <title>Options recognized by <parameter>pam_smbpass</parameter></title> + <tgroup cols="2" align="left"> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <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>do not 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>do not make passwords used by this module available to other modules.</entry></row> + <row><entry>nodelay</entry><entry>do not 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 <quote>auth</quote> 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> + +<para> +The following are examples of the use of <filename>pam_smbpass.so</filename> in the format of Linux +<filename>/etc/pam.d/</filename> files structure. Those wishing to implement this +tool on other platforms will need to adapt this appropriately. +</para> + +<sect3> +<title>Password Synchronization Configuration</title> + +<para> +A sample PAM configuration that shows the use of pam_smbpass to make +sure <filename>private/smbpasswd</filename> is kept in sync when <filename>/etc/passwd (/etc/shadow)</filename> +is changed. Useful when an expired password might be changed by an +application (such as <command>ssh</command>). +</para> + +<para> + <smbfile name="pam-synchronised-password"> + <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></smbfile></para> +</sect3> + +<sect3> +<title>Password Migration Configuration</title> + +<para> +A sample PAM configuration that shows the use of <filename>pam_smbpass</filename> to migrate +from plaintext to encrypted passwords for Samba. Unlike other methods, +this can be used for users who have never connected to Samba shares: +password migration takes place when users <command>ftp</command> in, login using <command>ssh</command>, pop +their mail, and so on. +</para> + +<para><smbfile name="pam-password-migration"> + <programlisting> +#%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 +</programlisting></smbfile></para> +</sect3> + +<sect3> +<title>Mature Password Configuration</title> + +<para> +A sample PAM configuration for a mature <filename>smbpasswd</filename> installation. +<filename>private/smbpasswd</filename> is fully populated, and we consider it an error if +the SMB password does not exist or does not match the UNIX password. +</para> + +<para><smbfile name="pam-fallback"> +<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></smbfile></para> +</sect3> + +<sect3> +<title>Kerberos Password Integration Configuration</title> + +<para> +A sample PAM configuration that shows <parameter>pam_smbpass</parameter> used together with +<parameter>pam_krb5</parameter>. This could be useful on a Samba PDC that is also a member of +a Kerberos realm. +</para> + +<para><smbfile name="pam-krb"> + <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></smbfile></para> + +</sect3> + +</sect2> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +PAM can be fickle and sensitive to configuration glitches. Here we look at a few cases from +the Samba mailing list. +</para> + +<!-- shouldn't this be in the Winbind chapter - Jelmer --> + <sect2> + <title>pam_winbind Problem</title> + + <para> + A user reported: I have the following PAM configuration: + </para> + +<para> + <smbfile name="pam-winbind-erratic"> +<programlisting> +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 +</programlisting></smbfile> +</para> + + <para> + When I open a new console with [ctrl][alt][F1], I can't log in with my user <quote>pitie</quote>. + I have tried with user <quote>scienceu\pitie</quote> also. + </para> + + <para> + <emphasis>Answer:</emphasis> 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 are already doing. Try commenting out the <parameter>pam_stack</parameter> lines + for <parameter>auth</parameter> and <parameter>account</parameter> 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. Alternately, 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> + + <sect2> + <title>Winbind Is Not Resolving Users and Groups</title> + + <para> + <quote> + My &smb.conf; file is correctly configured. I have specified + <smbconfoption name="idmap uid">12000</smbconfoption>, + and <smbconfoption name="idmap gid">3000-3500</smbconfoption> + and <command>winbind</command> is running. When I do the following it all works fine. + </quote> + </para> + +<para><screen> +&rootprompt;<userinput>wbinfo -u</userinput> +MIDEARTH\maryo +MIDEARTH\jackb +MIDEARTH\ameds +... +MIDEARTH\root + +&rootprompt;<userinput>wbinfo -g</userinput> +MIDEARTH\Domain Users +MIDEARTH\Domain Admins +MIDEARTH\Domain Guests +... +MIDEARTH\Accounts + +&rootprompt;<userinput>getent passwd</userinput> +root:x:0:0:root:/root:/bin/bash +bin:x:1:1:bin:/bin:/bin/bash +... +maryo:x:15000:15003:Mary Orville:/home/MIDEARTH/maryo:/bin/false +</screen></para> + + <para> + <quote> + But this command fails: + </quote> +<screen> +&rootprompt;<userinput>chown maryo a_file</userinput> +chown: 'maryo': invalid user +</screen> + <quote>This is driving me nuts! What can be wrong?</quote> + </para> + + <para> + <emphasis>Answer:</emphasis> Your system is likely running <command>nscd</command>, the name service + caching daemon. Shut it down, do not restart it! You will find your problem resolved. + </para> + + </sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-PDC.xml b/docs/Samba3-HOWTO/TOSHARG-PDC.xml new file mode 100644 index 0000000000..ee9d5155c0 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-PDC.xml @@ -0,0 +1,989 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="samba-pdc"> + +<chapterinfo> + &author.jht; + &author.jerry; + &author.dbannon; + <author>&person.gd; <contrib>LDAP updates</contrib></author> +</chapterinfo> + +<title>Domain Control</title> + +<para> +There are many who approach MS Windows networking with incredible misconceptions. +That's okay, because it gives the rest of us plenty of opportunity to be of assistance. +Those who really want help would be well advised to become familiar with information +that is already available. +</para> + +<para> +The reader is advised not to tackle this section without having first understood +and mastered some basics. MS Windows networking is not particularly forgiving of +mis-configuration. Users of MS Windows networking are likely to complain +of persistent niggles that may be caused by a broken network configuration. +To a great many people, however, MS Windows networking starts with a Domain Controller +that in some magical way is expected to solve all network operational ills. +</para> + +<para> +<link linkend="domain-example">The diagram</link> shows a typical MS Windows Domain Security +network environment. Workstations A, B and C are representative of many physical MS Windows +network clients. +</para> + +<image id="domain-example"> + <imagedescription>An Example Domain.</imagedescription> + <imagefile scale="50">domain</imagefile> +</image> + +<?latex \newpage ?> + +<para> +From the Samba mailing list one can readily identify many common networking issues. +If you are not clear on the following subjects, then it will do much good to read the +sections of this HOWTO that deal with it. These are the most common causes of MS Windows +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 how MS Windows clients interoperate in a network + environment.</para></listitem> +</itemizedlist> + +<para> +Do not be put off; on the surface of it MS Windows networking seems so simple that anyone +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 okay to make mistakes!</emphasis> In the right place and at +the right time, mistakes are the essence of learning. It is very much not okay to make +mistakes that cause loss of productivity and impose an avoidable financial burden on an +organization. +</para> + +<para> +Where is the right place to make mistakes? Only out of harms way. If you are going to +make mistakes, then please do it on a test network, away from users and in such a way as +to not inflict pain on others. Do your learning on a test network. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +<indexterm><primary>domain security</primary></indexterm> +<emphasis>What is the key benefit of Microsoft Domain Security?</emphasis> +</para> + +<para> +In a word, <emphasis>Single Sign On</emphasis>, or SSO for short. To many, this is the Holy +Grail of MS Windows NT and beyond networking. SSO allows users in a well-designed network +to log onto any workstation that is a member of the domain that their user account is in +(or in a domain that has an appropriate trust relationship with the domain they are visiting) +and they will be able to log onto the network and access resources (shares, files and printers) +as if they are sitting at their home (personal) workstation. This is a feature of the Domain +Security protocols. +</para> + +<para> +<indexterm><primary>SID</primary></indexterm> +The benefits of Domain Security are available to those sites that deploy a Samba PDC. +A Domain provides a unique network security identifier (SID). Domain user and group security +identifiers are comprised of the network SID plus a relative identifier (RID) that is unique to +the account. User and Group SIDs (the network SID plus the RID) can be used to create Access Control +Lists (ACLs) attached to network resources to provide organizational access control. UNIX systems +recognize only local security identifiers. +</para> + +<note><para> +Network clients of an MS Windows Domain Security Environment must be Domain Members to be +able to gain access to the advanced features provided. Domain Membership involves more than just +setting the workgroup name to the Domain name. It requires the creation of a Domain trust account +for the workstation (called a machine account). Refer to <link linkend="domain-member">Domain Membership</link> +for more information. +</para></note> + +<para> +The following functionalities are new to the Samba-3 release: +</para> + +<itemizedlist> + <listitem><para> + Windows NT4 domain trusts. + </para></listitem> + + <listitem><para> + <indexterm><primary>Nexus.exe</primary></indexterm> + Adding users via the User Manager for Domains. This can be done on any MS Windows + client using the <filename>Nexus.exe</filename> toolkit for Windows 9x/Me, or using + the SRVTOOLS.EXE package for MS Windows NT4/200x/XP platforms. These packages are + available from Microsoft's Web site. + </para></listitem> + + <listitem><para> + Introduces replaceable and multiple user account (authentication) + backends. In the case where the backend is placed in an LDAP database, + Samba-3 confers the benefits of a backend that can be distributed, replicated + and is highly scalable. + </para></listitem> + + <listitem><para> + Implements full Unicode support. This simplifies cross locale internationalization + support. It also opens up the use of protocols that Samba-2.2.x had but could not use due + to the need to fully support Unicode. + </para></listitem> +</itemizedlist> + +<para> +The following functionalities are not provided by Samba-3: +</para> +<itemizedlist> + <listitem><para> +<indexterm><primary>SAM</primary></indexterm> +<indexterm><primary>replication</primary></indexterm> + SAM replication with Windows NT4 Domain Controllers + (i.e., a Samba PDC and a Windows NT BDC or vice versa). This means Samba + cannot operate as a BDC when the PDC is Microsoft-based or + replicate account data to Windows BDCs. + </para></listitem> + + <listitem><para> + Acting as a Windows 2000 Domain Controller (i.e., Kerberos and + Active Directory). In point of fact, Samba-3 does have some + Active Directory Domain Control ability that is at this time + purely experimental that is certain to change as it becomes a + fully supported feature some time during the Samba-3 (or later) + life cycle. However, Active Directory is more then just SMB &smbmdash; + it's also LDAP, Kerberos, DHCP, and other protocols (with proprietary + extensions, of course). + </para></listitem> + + <listitem><para> + The Windows 200x/XP MMC (Computer Management) Console can not be used + to manage a Samba-3 server. For this you can use only the MS Windows NT4 + Domain Server manager and the MS Windows NT4 Domain User Manager. Both are + part of the SVRTOOLS.EXE package mentioned later. + </para></listitem> +</itemizedlist> + +<para> +Windows 9x/Me/XP Home clients are not true members of a domain for reasons outlined +in this chapter. The protocol for support of Windows 9x/Me style network (domain) logons +is completely different from NT4/Windows 200x type domain logons and has been officially supported +for some time. These clients use the old LanMan Network Logon facilities that are supported +in Samba since approximately the Samba-1.9.15 series. +</para> + +<para> +Samba-3 implements group mapping between Windows NT groups +and UNIX groups (this is really quite complicated to explain in a short space). This is +discussed more fully in <link linkend="groupmapping">Group Mapping &smbmdash; MS Windows and UNIX</link>. +</para> + +<para> +<indexterm><primary>Machine Trust Accounts</primary></indexterm> +Samba-3, like an MS Windows NT4 PDC or a Windows 200x Active Directory, needs to store +user and Machine Trust Account information in a suitable backend data-store. +Refer to <link linkend="machine-trust-accounts">MS Windows Workstation/Server Machine Trust Accounts</link>. With Samba-3 there can be multiple +backends for this. A complete discussion of account database backends can be found in +<link linkend="passdb">Account Information Databases</link>. +</para> + +</sect1> + +<sect1> +<title>Basics of Domain Control</title> + +<para> +Over the years, public perceptions of what Domain Control really is has taken on an +almost mystical nature. Before we branch into a brief overview of Domain Control, +there are three basic types of Domain Controllers. +</para> + +<sect2> +<title>Domain Controller Types</title> + +<itemizedlist> + <listitem><para>Primary Domain Controller</para></listitem> + <listitem><para>Backup Domain Controller</para></listitem> + <listitem><para>ADS Domain Controller</para></listitem> +</itemizedlist> + +<para> +The <emphasis>Primary Domain Controller</emphasis> or PDC plays an important role in MS +Windows NT4. In Windows 200x Domain Control architecture, this role is held by Domain Controllers. +Folklore dictates that because of its role in the MS Windows +network, the Domain Controller should be the most powerful and most capable machine in the network. +As strange as it may seem to say this here, good overall network performance dictates that +the entire infrastructure needs to be balanced. It is advisable to invest more in Stand-alone +(Domain Member) servers than in the Domain Controllers. +</para> + +<para> +<indexterm><primary>SAM</primary></indexterm> +In the case of MS Windows NT4-style domains, it is the PDC that initiates a new Domain Control database. +This forms a part of the Windows registry called the Security Account Manager (SAM). It plays a key +part in NT4-type domain user authentication and in synchronization of the domain authentication +database with Backup Domain Controllers. +</para> + +<para> +With MS Windows 200x Server-based Active Directory domains, one Domain Controller initiates a potential +hierarchy of Domain Controllers, each with their own area of delegated control. The master domain +controller has the ability to override any downstream controller, but a down-line controller has +control only over its down-line. With Samba-3, this functionality can be implemented using an +LDAP-based user and machine account backend. +</para> + +<para> +New to Samba-3 is the ability to use a backend database that holds the same type of data as +the NT4-style SAM database (one of the registry files)<footnote><para>See also <link linkend="passdb">Account Information Databases</link>.</para></footnote>. +</para> + +<para> +The <emphasis>Backup Domain Controller</emphasis> or BDC plays a key role in servicing network +authentication requests. The BDC is biased to answer logon requests in preference to the PDC. +On a network segment that has a BDC and a PDC, the BDC will most likely service network +logon requests. The PDC will answer network logon requests when the BDC is too busy (high load). +A BDC can be promoted to a PDC. If the PDC is online at the time that a BDC is promoted to +PDC, the previous PDC is automatically demoted to a BDC. With Samba-3, this is not an automatic +operation; the PDC and BDC must be manually configured and changes also need to be made. +</para> + +<para> +With MS Windows NT4, a decision is made at installation to determine what type of machine the server will be. +It is possible to promote a BDC to a PDC and vice versa. The only way +to convert a Domain Controller to a Domain Member server or a Stand-alone Server is to +reinstall it. The install time choices offered are: +</para> + +<itemizedlist> + <listitem><para><emphasis>Primary Domain Controller</emphasis> &smbmdash; the one that seeds the domain SAM.</para></listitem> + <listitem><para><emphasis>Backup Domain Controller</emphasis> &smbmdash; one that obtains a copy of the domain SAM.</para></listitem> + <listitem><para><emphasis>Domain Member Server</emphasis> &smbmdash; 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> &smbmdash; one that plays no part is SAM synchronization, has its own authentication database and plays no role in Domain Security.</para></listitem> +</itemizedlist> + +<para> +With MS Windows 2000, the configuration of Domain Control is done after the server has been +installed. Samba-3 is capable of acting fully as a native member of a Windows 200x server +Active Directory domain. +</para> + +<para> +<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm> +New to Samba-3 is the ability to function fully as an MS Windows NT4-style Domain Controller, +excluding the SAM replication components. However, please be aware that Samba-3 also supports the +MS Windows 200x Domain Control protocols. +</para> + +<para> +At this time any appearance that Samba-3 is capable of acting as an +<emphasis>Domain Controller</emphasis> in native ADS mode is limited and experimental in nature. +This functionality should not be used until the Samba Team offers formal support for it. +At such a time, the documentation will be revised to duly reflect all configuration and +management requirements. Samba can act as a NT4-style DC in a Windows 2000/XP +environment. However, there are certain compromises: + +<itemizedlist> + <listitem><para>No machine policy files.</para></listitem> + <listitem><para>No Group Policy Objects.</para></listitem> + <listitem><para>No synchronously executed AD logon scripts.</para></listitem> + <listitem><para>Can't use Active Directory management tools to manage users and machines.</para></listitem> + <listitem><para>Registry changes tattoo the main registry, while with AD they do not leave permanent changes in effect.</para></listitem> + <listitem><para>Without AD you cannot perform the function of exporting specific applications to specific users or groups.</para></listitem> +</itemizedlist> +</para> + +</sect2> + +<sect2> +<title>Preparing for Domain Control</title> + +<para> +There are two ways that MS Windows machines may interact with each other, with other servers +and with Domain Controllers: either as <emphasis>Stand-alone</emphasis> systems, more commonly +called <emphasis>Workgroup</emphasis> members, or as full participants in a security system, +more commonly called <emphasis>Domain</emphasis> members. +</para> + +<para> +It should be noted that <emphasis>Workgroup</emphasis> membership involves no special configuration +other than the machine being configured so the network configuration has a commonly used name +for its 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 neighborhood to be logically +grouped together. Again, just to be clear: <emphasis>workgroup mode does not involve security machine +accounts</emphasis>. +</para> + +<para> +Domain Member machines have a machine account in the Domain accounts database. A special procedure +must be followed on each machine to effect Domain Membership. This procedure, which can be done +only by the local machine Administrator account, will create the Domain machine account (if it does +not exist), and then initializes that account. When the client first logs onto the +Domain it triggers a machine password change. +</para> + +<note><para> +When Samba is configured as a Domain Controller, secure network operation demands that +all MS Windows NT4/200x/XP Professional clients should be configured as Domain Members. +If a machine is not made a member of the Domain, then it will operate like a workgroup +(Stand-alone) machine. Please refer to <link linkend="domain-member">Domain Membership</link> chapter for +information regarding Domain Membership. +</para></note> + +<para> +The following are necessary for configuring Samba-3 as an MS Windows NT4-style PDC for MS Windows +NT4/200x/XP clients: +</para> + +<itemizedlist> + <listitem><para>Configuration of basic TCP/IP and MS Windows networking.</para></listitem> + <listitem><para>Correct designation of the Server Role (<smbconfoption name="security">user</smbconfoption>).</para></listitem> + <listitem><para>Consistent configuration of Name Resolution<footnote><para>See <link linkend="NetworkBrowsing">Network Browsing</link>, and + <link linkend="integrate-ms-networks">Integrating MS Windows Networks with Samba</link>.</para></footnote>.</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> +</itemizedlist> + +<para> +The following provisions are required to serve MS Windows 9x/Me clients: +</para> + +<itemizedlist> + <listitem><para>Configuration of basic TCP/IP and MS Windows networking.</para></listitem> + <listitem><para>Correct designation of the server role (<smbconfoption name="security">user</smbconfoption>).</para></listitem> + <listitem><para>Network Logon Configuration (since Windows 9x/Me/XP Home are not technically domain + members, they do not really participate 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 <quote>Client for MS Windows Networks</quote> and configuration + to log onto the domain.</para></listitem> + <listitem><para>Placing Windows 9x/Me clients in User Level Security &smbmdash; 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> +</itemizedlist> + +<note><para> +Roaming Profiles and System/Network policies are advanced network administration topics +that are covered in the <link linkend="ProfileMgmt">Desktop Profile Management</link> and +<link linkend="PolicyMgmt">System and Account Policies</link> chapters of this document. However, these are not +necessarily specific to a Samba PDC as much as they are related to Windows NT networking concepts. +</para></note> + +<para> +A Domain Controller is an SMB/CIFS server that: +</para> + +<itemizedlist> + <listitem><para> + Registers and advertises itself as a Domain Controller (through NetBIOS broadcasts + as well as by way of name registrations either by Mailslot Broadcasts over UDP broadcast, + to a WINS server over UDP uni-cast, or via DNS and Active Directory). + </para></listitem> + + <listitem><para> + Provides the NETLOGON service. (This is actually a collection of services that runs over + multiple protocols. These include the LanMan Logon service, the Netlogon service, + the Local Security Account service, and variations of them.) + </para></listitem> + + <listitem><para> + Provides a share called NETLOGON. + </para></listitem> +</itemizedlist> + +<para> +It is rather easy to configure Samba to provide these. Each Samba Domain Controller must provide +the NETLOGON service that Samba calls the <smbconfoption name="domain logons"/> functionality +(after the name of the parameter in the &smb.conf; file). Additionally, one server in a Samba-3 +Domain must advertise itself as the Domain Master Browser<footnote><para>See <link linkend="NetworkBrowsing">Network Browsing</link>.</para></footnote>. +This causes the Primary Domain Controller to claim a domain-specific NetBIOS name that identifies it as a +Domain Master Browser for its given domain or workgroup. Local master browsers in the same domain or workgroup on +broadcast-isolated subnets then ask for a complete copy of the browse list for the whole wide area network. +Browser clients will then contact their Local Master Browser, and will receive the domain-wide browse list, +instead of just the list for their broadcast-isolated subnet. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Domain Control &smbmdash; Example Configuration</title> + +<para> +The first step in creating a working Samba PDC is to understand the parameters necessary +in &smb.conf;. An example &smb.conf; for acting as a PDC can be found in <link linkend="pdc-example">the next example</link>. +</para> + +<para> +<smbconfexample id="pdc-example"> +<title>smb.conf for being a PDC</title> +<smbconfsection name="[global]"/> +<smbconfoption name="netbios name"><replaceable>BELERIAND</replaceable></smbconfoption> +<smbconfoption name="workgroup"><replaceable>&example.workgroup;</replaceable></smbconfoption> +<smbconfoption name="passdb backend">tdbsam</smbconfoption> +<smbconfoption name="os level">33</smbconfoption> +<smbconfoption name="preferred master">yes</smbconfoption> +<smbconfoption name="domain master">yes</smbconfoption> +<smbconfoption name="local master">yes</smbconfoption> +<smbconfoption name="security">user</smbconfoption> +<smbconfoption name="domain logons">yes</smbconfoption> +<smbconfoption name="logon path">\\%N\profiles\%U</smbconfoption> +<smbconfoption name="logon drive">H:</smbconfoption> +<smbconfoption name="logon home">\\homeserver\%U\winprofile</smbconfoption> +<smbconfoption name="logon script">logon.cmd</smbconfoption> + +<smbconfsection name="[netlogon]"/> +<smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption> +<smbconfoption name="read only">yes</smbconfoption> +<smbconfoption name="write list"><replaceable>ntadmin</replaceable></smbconfoption> + +<smbconfsection name="[profiles]"/> +<smbconfoption name="path">/var/lib/samba/profiles</smbconfoption> +<smbconfoption name="read only">no</smbconfoption> +<smbconfoption name="create mask">0600</smbconfoption> +<smbconfoption name="directory mask">0700</smbconfoption> +</smbconfexample> +</para> + +<para> +The basic options shown in <link linkend="pdc-example">this example</link> are explained as follows: +</para> + +<variablelist> + <varlistentry><term>passdb backend </term> + <listitem><para> + This contains all the user and group account information. Acceptable values for a PDC + are: <emphasis>smbpasswd, tdbsam, and ldapsam</emphasis>. The <quote>guest</quote> entry provides + default accounts and is included by default, there is no need to add it explicitly.</para> + + <para> + Where use of backup Domain Controllers (BDCs) is intended, the only logical choice is + to use LDAP so the passdb backend can be distributed. The tdbsam and smbpasswd files + cannot effectively be distributed and therefore should not be used. + </para></listitem> + </varlistentry> + <varlistentry><term>Domain Control Parameters </term> + <listitem><para> + The parameters <emphasis>os level, preferred master, domain master, security, + encrypt passwords, and domain logons</emphasis> play a central role in assuring domain + control and network logon support.</para> + + <para> + The <emphasis>os level</emphasis> must be set at or above a value of 32. A Domain Controller + must be the Domain Master Browser, must be set in <emphasis>user</emphasis> mode security, + must support Microsoft-compatible encrypted passwords, and must provide the network logon + service (domain logons). Encrypted passwords must be enabled. For more details on how + to do this, refer to <link linkend="passdb">Account Information Databases</link>. + </para></listitem> + </varlistentry> + <varlistentry><term>Environment Parameters </term> + <listitem><para> + The parameters <emphasis>logon path, logon home, logon drive, and logon script</emphasis> are + environment support settings that help to facilitate client logon operations and that help + to provide automated control facilities to ease network management overheads. Please refer + to the man page information for these parameters. + </para></listitem> + </varlistentry> + <varlistentry><term>NETLOGON Share </term> + <listitem><para> + The NETLOGON share plays a central role in domain logon and Domain Membership support. + This share is provided on all Microsoft Domain Controllers. It is used to provide logon + scripts, to store Group Policy files (NTConfig.POL), as well as to locate other common + tools that may be needed for logon processing. This is an essential share on a Domain Controller. + </para></listitem> + </varlistentry> + <varlistentry><term>PROFILE Share </term> + <listitem><para> + This share is used to store user desktop profiles. Each user must have a directory at the root + of this share. This directory must be write-enabled for the user and must be globally read-enabled. + Samba-3 has a VFS module called <quote>fake_permissions</quote> that may be installed on this share. This will + allow a Samba administrator to make the directory read-only to everyone. Of course this is useful + only after the profile has been properly created. + </para></listitem> + </varlistentry> +</variablelist> + +<note><para> +The above parameters make for a full set of parameters that may define the server's mode +of operation. The following &smb.conf; parameters are the essentials alone: +</para> + +<para> +<smbconfblock> +<smbconfoption name="netbios name">BELERIAND</smbconfoption> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +<smbconfoption name="domain logons">Yes</smbconfoption> +<smbconfoption name="domain master">Yes</smbconfoption> +<smbconfoption name="security">User</smbconfoption> +</smbconfblock> +</para> + +<para> +The additional parameters shown in the longer listing above just makes for +a more complete explanation. +</para></note> + +</sect1> + +<sect1> +<title>Samba ADS Domain Control</title> + +<para> +Samba-3 is not, and cannot act as, an Active Directory Server. It cannot truly function as +an Active Directory Primary Domain Controller. The protocols for some of the functionality +of Active Directory Domain Controllers has been partially implemented on an experimental +only basis. Please do not expect Samba-3 to support these protocols. Do not depend +on any such functionality either now or in the future. The Samba Team may remove these +experimental features or may change their behavior. This is mentioned for the benefit of those +who have discovered secret capabilities in Samba-3 and who have asked when this functionality will be +completed. The answer is maybe or maybe never! +</para> + +<para> +To be sure, Samba-3 is designed to provide most of the functionality that Microsoft Windows NT4-style +Domain Controllers have. Samba-3 does not have all the capabilities of Windows NT4, but it does have +a number of features that Windows NT4 domain controllers do not have. In short, Samba-3 is not NT4 and it +is not Windows Server 200x, it is not an Active Directory server. We hope this is plain and simple +enough for all to understand. +</para> + +</sect1> + +<sect1> +<title>Domain and Network Logon Configuration</title> + +<para> +The subject of Network or Domain Logons is discussed here because it forms +an integral part of the essential functionality that is provided by a Domain Controller. +</para> + +<sect2> +<title>Domain Network Logon Service</title> + +<para> +All Domain Controllers must run the netlogon service (<emphasis>domain logons</emphasis> +in Samba). One Domain Controller must be configured with <smbconfoption name="domain master">Yes</smbconfoption> +(the Primary Domain Controller); on all Backup Domain Controllers <smbconfoption name="domain master">No</smbconfoption> +must be set. +</para> + +<sect3> +<title>Example Configuration</title> + +<smbconfexample id="PDC-config"> +<title>smb.conf for being a PDC</title> +<smbconfsection name="[global]"/> +<smbconfoption name="domain logons">Yes</smbconfoption> +<smbconfoption name="domain master">(Yes on PDC, No on BDCs)</smbconfoption> + +<smbconfsection name="[netlogon]"/> +<smbconfoption name="comment">Network Logon Service</smbconfoption> +<smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> +</smbconfexample> + +</sect3> +<sect3> +<title>The Special Case of MS Windows XP Home Edition</title> + +<para> +To be completely clear: If you want MS Windows XP Home Edition to integrate with your +MS Windows NT4 or Active Directory Domain Security, understand it cannot be done. +The only option is to purchase the upgrade from MS Windows XP Home Edition to +MS Windows XP Professional. +</para> + +<note><para> +MS Windows XP Home Edition does not have the ability to join any type of Domain +Security facility. Unlike MS Windows 9x/Me, MS Windows XP Home Edition also completely +lacks the ability to log onto a network. +</para></note> + +<para> +Now that this has been said, please do not ask the mailing list or email any of the +Samba Team members with your questions asking how to make this work. It can't be done. +If it can be done, then to do so would violate your software license agreement with +Microsoft, and we recommend that you do not do that. +</para> + +</sect3> + +<sect3> +<title>The Special Case of Windows 9x/Me</title> + +<para> +A domain and a workgroup are exactly the same in terms of network +browsing. The difference is that a distributable authentication +database is associated with a domain, for secure login access to a +network. Also, different access rights can be granted to users if they +successfully authenticate against a domain logon server. Samba-3 does this +now in the same way as MS Windows NT/200x. +</para> + +<para> +The SMB client logging on to a domain has an expectation that every other +server in the domain should accept the same authentication information. +Network browsing functionality of domains and workgroups is identical and +is explained in this documentation under the browsing discussions. +It should be noted that browsing is totally orthogonal to logon support. +</para> + +<para> +Issues related to the single-logon network model are discussed in this +section. Samba supports domain logons, network logon scripts and user +profiles for MS Windows for workgroups and MS Windows 9X/ME clients, +which are the focus of this section. +</para> + +<para> +When an SMB client in a domain wishes to logon, it broadcasts requests for a +logon server. The first one to reply gets the job, and validates its +password using whatever mechanism the Samba administrator has installed. +It is possible (but ill advised ) to create a domain where the user +database is not shared between servers, i.e., they are effectively workgroup +servers advertising themselves as participating in a domain. This +demonstrates how authentication is quite different from but closely +involved with domains. +</para> + +<para> +Using these features you can make your clients verify their logon via +the Samba server; make clients run a batch file when they logon to +the network and download their preferences, desktop and start menu. +</para> + +<para><emphasis> +MS Windows XP Home edition is not able to join a domain and does not permit +the use of domain logons. +</emphasis></para> + +<para> +Before launching into the configuration instructions, it is +worthwhile to look at how a Windows 9x/Me client performs a logon: +</para> + +<orderedlist> +<listitem> + <para> + The client broadcasts (to the IP broadcast address of the subnet it is in) + 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 + <filename>\\SERVER</filename>. + </para> +</listitem> + +<listitem> + <para> + The client connects to that server, logs on (does an SMBsessetupX) and + then connects to the IPC$ share (using an SMBtconX). + </para> +</listitem> + +<listitem> + <para> + The client does a NetWkstaUserLogon request, which retrieves the name + of the user's logon script. + </para> +</listitem> + +<listitem> + <para> + The client then connects to the NetLogon share and searches for said script. + If it is found and can be read, it is retrieved and executed by the client. + After this, the client disconnects from the NetLogon share. + </para> +</listitem> + +<listitem> + <para> + The client sends a NetUserGetInfo request to the server to retrieve + the user's home share, which is used to search for profiles. Since the + response to the NetUserGetInfo request does not contain much more than + the user's home share, profiles for Windows 9x clients must reside in the user + home directory. + </para> +</listitem> + +<listitem> + <para> + The client 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 share name and path. For example, <filename>\\server\fred\.winprofile</filename>. + If the profiles are found, they are implemented. + </para> +</listitem> + +<listitem> + <para> + The client then disconnects from the user's home share and reconnects to + the NetLogon share and looks for <filename>CONFIG.POL</filename>, the policies file. If this is + found, it is read and implemented. + </para> +</listitem> +</orderedlist> + +<para> +The main difference between a PDC and a Windows 9x/Me logon server configuration is: +</para> + +<itemizedlist> +<listitem><para> + Password encryption is not required for a Windows 9x/Me logon server. But note + that beginning with MS Windows 98 the default setting is that plain-text + password support is disabled. It can be re-enabled with the registry + changes that are documented in <link linkend="PolicyMgmt">System and Account Policies</link>. + </para></listitem> + + <listitem><para> + Windows 9x/Me clients do not require and do not use Machine Trust Accounts. + </para></listitem> +</itemizedlist> + +<para> +A Samba PDC will act as a Windows 9x/Me logon server; after all, it does provide the +network logon services that MS Windows 9x/Me expect to find. +</para> + +<note><para> +Use of plain-text passwords is strongly discouraged. Where used they are easily detected +using a sniffer tool to examine network traffic. +</para></note> + +</sect3> +</sect2> + +<sect2> +<title>Security Mode and Master Browsers</title> + +<para> +There are a few comments to make in order to tie up some loose ends. There has been +much debate over the issue of whether it is okay to configure Samba as a Domain +Controller in security modes other than user. The only security mode that will +not work due to technical reasons is share-mode security. Domain and server mode +security are really just a variation on SMB User Level Security. +</para> + +<para> +Actually, this issue is also closely tied to the debate on whether +Samba must be the Domain Master Browser for its workgroup +when operating as a DC. While it may technically be possible +to configure a server as such (after all, browsing and domain logons +are two distinctly different functions), it is not a good idea to do +so. You should remember that the DC must register the DOMAIN<#1b> NetBIOS +name. This is the name used by Windows clients to locate the DC. +Windows clients do not distinguish between the DC and the DMB. +A DMB is a Domain Master Browser &smbmdash; see <link linkend="DMB">Configuring WORKGROUP Browsing</link> section. +For this reason, it is wise to configure the Samba DC as the DMB. +</para> + +<para> +Now back to the issue of configuring a Samba DC to use a mode other than +<smbconfoption name="security">user</smbconfoption>. If a Samba host is +configured to use another SMB server or DC in order to validate user connection requests, +it is a fact that some other machine on the network (the <smbconfoption name="password server"/>) +knows more about the user than the Samba host. About 99% of the time, this other host is +a Domain Controller. Now to operate in domain mode security, the <smbconfoption name="workgroup"/> +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, you do not yet have a Domain. +</para> + +<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 <smbconfoption name="security">user</smbconfoption>. +This is the only officially supported mode of operation. +</para> + +</sect2> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<sect2> + <title><quote>$</quote> Cannot Be Included in Machine Name</title> +<para> +A machine account, typically stored in <filename>/etc/passwd</filename>, takes the form of the machine +name with a <quote>$</quote> appended. Some BSD systems will not create a user with a <quote>$</quote> in the name. +Recent versions of FreeBSD have removed this limitation, but older releases are still in common use. +</para> + +<para> +The problem is only in the program used to make the entry. Once made, it works perfectly. +Create a user without the <quote>$</quote>. Then use <command>vipw</command> to edit the entry, adding +the <quote>$</quote>. Or create the whole entry with vipw if you like; make sure you use a unique user login ID. +</para> + +<note><para>The machine account must have the exact name that the workstation has.</para></note> + +<note><para> +The UNIX tool <command>vipw</command> is a common tool for directly editing the <filename>/etc/passwd</filename> file. +</para></note> + +</sect2> + +<sect2> +<title>Joining Domain Fails Because of Existing Machine Account</title> + +<para> +<quote>I get told, `You already have a connection to the Domain....' or `Cannot join domain, the +credentials supplied conflict with an existing set...' when creating a Machine Trust Account.</quote> +</para> + +<para> +This happens if you try to create a Machine Trust Account from the machine itself and already have a +connection (e.g., mapped drive) to a share (or IPC$) on the Samba PDC. The following command +will remove all network drive connections: +<screen> +&dosprompt;<userinput>net use * /d</userinput> +</screen> +</para> + +<para> +Further, if the machine is already a <quote>member of a workgroup</quote> that +is the same name as the domain you are joining (bad idea) you will +get this message. Change the workgroup name to something else, it +does not matter what, reboot, and try again. +</para> +</sect2> + +<sect2> +<title>The System Cannot Log You On (C000019B)</title> + +<para><quote>I joined the domain successfully but after upgrading +to a newer version of the Samba code I get the message, <errorname>`The system +cannot log you on (C000019B), Please try again or consult your +system administrator</errorname> when attempting to logon.'</quote> +</para> + +<para> +<indexterm><primary>SID</primary></indexterm> +This occurs when the domain SID stored in the secrets.tdb database +is changed. The most common cause of a change in domain SID is when +the domain name and/or the server name (NetBIOS name) is changed. +The only way to correct the problem is to restore the original domain +SID or remove the domain client from the domain and rejoin. The domain +SID may be reset using either the net or rpcclient utilities. +</para> + +<para> +To reset or change the domain SID you can use the net command as follows: + +<screen> +&rootprompt;<userinput>net getlocalsid 'OLDNAME'</userinput> +&rootprompt;<userinput>net setlocalsid 'SID'</userinput> +</screen> +</para> + +<para> +Workstation Machine Trust Accounts work only with the Domain (or network) SID. If this SID changes +Domain Members (workstations) will not be able to log onto the domain. The original Domain SID +can be recovered from the secrets.tdb file. The alternative is to visit each workstation to re-join +it to the domain. +</para> + +</sect2> + +<sect2> +<title>The Machine Trust Account Is Not Accessible</title> + +<para> +<quote>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?</quote> +</para> + +<para> +This problem is caused by the PDC not having a suitable Machine Trust Account. +If you are using the <smbconfoption name="add machine script"/> method to create +accounts then this would indicate that it has not worked. Ensure the domain +admin user system is working. +</para> + +<para> +Alternately, if you are creating account entries manually then they +have not been created correctly. Make sure that you have the entry +correct for the Machine Trust Account in <filename>smbpasswd</filename> file on the Samba PDC. +If you added the account using an editor rather than using the smbpasswd +utility, make sure that the account name is the machine NetBIOS name +with a <quote>$</quote> appended to it (i.e., computer_name$). There must be an entry +in both /etc/passwd and the smbpasswd file. +</para> + +<para> +Some people have also reported that inconsistent subnet masks between the Samba server and the NT +client can cause this problem. Make sure that these are consistent for both client and server. +</para> +</sect2> + +<sect2> +<title>Account Disabled</title> + +<para><quote>When I attempt to login to a Samba Domain from a NT4/W200x workstation, +I get a message about my account being disabled.</quote></para> + +<para> +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>Domain Controller Unavailable</title> + +<para><quote>Until a few minutes after Samba has started, clients get the error `Domain Controller Unavailable'</quote></para> + +<para> +A Domain Controller has to announce its role on the network. This usually takes a while. Be patient for up to fifteen minutes, +then try again. +</para> +</sect2> + +<sect2> +<title>Cannot Log onto Domain Member Workstation After Joining Domain</title> + +<para> +<indexterm><primary>schannel</primary></indexterm> +<indexterm><primary>signing</primary></indexterm> +After successfully joining the domain, user logons fail with one of two messages: one to the +effect that the Domain Controller cannot be found; the other claims that the account does not +exist in the domain or that the password is incorrect. This may be due to incompatible +settings between the Windows client and the Samba-3 server for <emphasis>schannel</emphasis> +(secure channel) settings or <emphasis>smb signing</emphasis> settings. Check your Samba +settings for <emphasis> client schannel, server schannel, client signing, server signing</emphasis> +by executing: +<screen> +<command>testparm -v | more</command> and looking for the value of these parameters. +</screen> +</para> + +<para> +Also use the Microsoft Management Console &smbmdash; Local Security Settings. This tool is available from the +Control Panel. The Policy settings are found in the Local Policies/Security Options area and are prefixed by +<emphasis>Secure Channel: ..., and Digitally sign ....</emphasis>. +</para> + +<para> +It is important that these be set consistently with the Samba-3 server settings. +</para> + +</sect2> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Passdb.xml b/docs/Samba3-HOWTO/TOSHARG-Passdb.xml new file mode 100644 index 0000000000..2ee109db01 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Passdb.xml @@ -0,0 +1,1791 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="passdb"> +<chapterinfo> + &author.jelmer; + &author.jht; + &author.jerry; + &author.jeremy; + <author>&person.gd;<contrib>LDAP updates</contrib></author> + <author> + <firstname>Olivier (lem)</firstname><surname>Lemaire</surname> + <affiliation> + <orgname>IDEALX</orgname> + <address><email>olem@IDEALX.org</email></address> + </affiliation> + </author> + + <pubdate>May 24, 2003</pubdate> +</chapterinfo> +<title>Account Information Databases</title> + +<para> +Samba-3 implements a new capability to work concurrently with multiple account backends. +The possible new combinations of password backends allows Samba-3 a degree of flexibility +and scalability that previously could be achieved only with MS Windows Active Directory. +This chapter describes the new functionality and how to get the most out of it. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +Samba-3 provides for complete backward compatibility with Samba-2.2.x functionality +as follows: +<indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm> +<indexterm><primary>SAM backend</primary><secondary>ldapsam_compat</secondary></indexterm> +<indexterm><primary>encrypted passwords</primary></indexterm> +</para> + +<?latex \newpage ?> + +<sect2> + <title>Backward Compatibility Backends</title> + +<variablelist> + <varlistentry><term>Plain Text</term> + <listitem> + <para> + This isn't really a backend at all, but is listed here for simplicity. Samba can be + configured to pass plaintext authentication requests to the traditional UNIX/Linux + <filename>/etc/passwd</filename> and <filename>/etc/shadow</filename> + style subsystems. On systems that have Pluggable Authentication Modules (PAM) + support, all PAM modules are supported. The behavior is just as it was with + Samba-2.2.x, and the protocol limitations imposed by MS Windows clients + apply likewise. Please refer to <link linkend="passdbtech">Technical Information</link> for more information + regarding the limitations of Plain Text password usage. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>smbpasswd</term> + <listitem> + <para> + This option allows continued use of the <filename>smbpasswd</filename> + file that maintains a plain ASCII (text) layout that includes the MS Windows + LanMan and NT encrypted passwords as well as a field that stores some + account information. This form of password backend does not store any of + the MS Windows NT/200x SAM (Security Account Manager) information required to + provide the extended controls that are needed for more comprehensive + inter-operation with MS Windows NT4/200x servers. + </para> + + <para> + This backend should be used only for backward compatibility with older + versions of Samba. It may be deprecated in future releases. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>ldapsam_compat (Samba-2.2 LDAP Compatibility)</term> + <listitem> + <para> + There is a password backend option that allows continued operation with + an 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. This tool will eventually + be deprecated. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title>New Backends</title> + +<para> +Samba-3 introduces a number of new password backend capabilities. +<indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm> +<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm> +<indexterm><primary>SAM backend</primary><secondary>mysqlsam</secondary></indexterm> +<indexterm><primary>SAM backend</primary><secondary>xmlsam</secondary></indexterm> +</para> + +<variablelist> + <varlistentry><term>tdbsam</term> + <listitem> + <para> + This backend provides a rich database backend for local servers. This + backend is not suitable for multiple Domain Controllers (i.e., 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. + The inclusion of the extended information makes it possible for Samba-3 + to implement the same account and system access controls that are possible + with MS Windows NT4/200x-based systems. + </para> + + <para> + The inclusion of the <emphasis>tdbsam</emphasis> capability is a direct + response to user requests to allow simple site operation without the overhead + of the complexities of running OpenLDAP. It is recommended to use this only + for sites that have fewer than 250 users. For larger sites or implementations, + the use of OpenLDAP or of Active Directory integration is strongly recommended. + </para> + </listitem> + </varlistentry> + + <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 class="directory">examples/LDAP</filename> directory of the Samba distribution. + </para> + + <para> + The new LDAP implementation significantly expands the control abilities that + were possible with prior versions of Samba. It is now possible to specify + <quote>per user</quote> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>mysqlsam (MySQL based backend)</term> + <listitem> + <para> + It is expected that the MySQL-based SAM will be very popular in some corners. + This database backend will be of considerable interest to sites that want to + leverage existing MySQL technology. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>pgsqlsam (PostGreSQL based backend)</term> + <listitem> + <para> + Stores user information in a PostgreSQL database. + This backend is largely undocumented at + the moment, though it's configuration is very similar to + that of the mysqlsam backend. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>xmlsam (XML based datafile)</term> + <listitem> + <para> +<indexterm><primary>pdbedit</primary></indexterm> + Allows the account and password data to be stored in an XML format + data file. This backend cannot 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 <parameter>xmlsam</parameter> option can be useful for account migration between database + backends or backups. Use of this tool will allow the data to be edited before migration + into another backend format. + </para> + </listitem> + </varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="passdbtech"> + <title>Technical Information</title> + + <para> + Old Windows clients send plain text passwords over the wire. Samba can check these + passwords by encrypting them and comparing them to the hash stored in the UNIX user database. + </para> + + <para> +<indexterm><primary>encrypted passwords</primary></indexterm> + Newer Windows clients send encrypted passwords (so-called LanMan and NT hashes) over + the wire, instead of plain text passwords. The newest clients will send only encrypted + passwords and refuse to send plain text passwords, unless their registry is tweaked. + </para> + + <para> + These passwords can't be converted to UNIX-style encrypted passwords. Because of that, + you can't use the standard UNIX user database, and you have to store the LanMan and NT + hashes somewhere else. + </para> + + <para> + In addition to differently encrypted passwords, Windows also stores certain data for each + user that is not stored in a UNIX user database. For example, workstations the user may logon from, + the location where the user's profile is stored, and so on. Samba retrieves and stores this + information using a <smbconfoption name="passdb backend"/>. Commonly available backends are LDAP, plain text + file, and MySQL. For more information, see the man page for &smb.conf; regarding the + <smbconfoption name="passdb backend"/> parameter. + </para> + + + <image id="idmap-sid2uid"> + <imagedescription>IDMAP: Resolution of SIDs to UIDs.</imagedescription> + <imagefile scale="50">idmap-sid2uid</imagefile> + </image> + + <para> +<indexterm><primary>SID</primary></indexterm> + The resolution of SIDs to UIDs is fundamental to correct operation of Samba. In both cases shown, if winbindd is not running, or cannot + be contacted, then only local SID/UID resolution is possible. See <link linkend="idmap-sid2uid">resolution of SIDs to UIDs</link> and + <link linkend="idmap-uid2sid">resolution of UIDs to SIDs</link> diagrams. + </para> + + <image id="idmap-uid2sid"> + <imagedescription>IDMAP: Resolution of UIDs to SIDs.</imagedescription> + <imagefile scale="50">idmap-uid2sid</imagefile> + </image> + + <sect2> + <title>Important Notes About Security</title> + + <para> + The UNIX and SMB password encryption techniques seem similar on the surface. This + similarity is, however, only skin deep. The UNIX scheme typically sends clear-text + passwords over the network when logging in. This is bad. The SMB encryption scheme + never sends the clear-text password over the network but it does store the 16 byte + hashed values on disk. This is also bad. Why? Because the 16 byte hashed values + are a <quote>password equivalent.</quote> You cannot derive the user's password from them, but + they could potentially be used in a modified client to gain access to a server. + This would require considerable technical knowledge on behalf of the attacker but + is perfectly possible. You should thus treat the data stored in whatever passdb + backend you use (smbpasswd file, LDAP, MYSQL) as though it contained the clear-text + passwords of all your users. Its contents must be kept secret and the file should + be protected accordingly. + </para> + + <para> + Ideally, we would like a password scheme that involves neither plain text passwords + on the network nor on disk. Unfortunately, this is not available as Samba is stuck with + having to be compatible with other SMB systems (Windows NT, Windows for Workgroups, Windows 9x/Me). + </para> + + <para> + Windows NT 4.0 Service Pack 3 changed the default setting so plaintext passwords + are disabled from being sent over the wire. This mandates either the use of encrypted + password support or editing the Windows NT registry to re-enable plaintext passwords. + </para> + + <para> + The following versions of Microsoft Windows do not support full domain security protocols, + 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 [Second Edition].</para></listitem> + <listitem><para>Windows Me.</para></listitem> + </itemizedlist> + + <note> + <para> + MS Windows XP Home does not have facilities to become a Domain Member and it cannot participate in domain logons. + </para> + </note> + + <para> + 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> + + <para> + All current releases of Microsoft SMB/CIFS clients support authentication via the + SMB Challenge/Response mechanism described here. Enabling clear-text authentication + does not disable the ability of the client to participate in encrypted authentication. + Instead, it allows the client to negotiate either plain text or encrypted password + handling. + </para> + + <para> + MS Windows clients will cache the encrypted password alone. Where plain text passwords + are re-enabled through the appropriate registry change, the plain text password is never + cached. This means that in the event that a network connections should become disconnected + (broken), only the cached (encrypted) password will be sent to the resource server to + effect an auto-reconnect. If the resource server does not support encrypted passwords the + auto-reconnect will fail. Use of encrypted passwords is strongly advised. + </para> + + <sect3> + <title>Advantages of Encrypted Passwords</title> + + <itemizedlist> + <listitem><para>Plaintext passwords are not passed across + the network. Someone using a network sniffer cannot just + record passwords going to the SMB server.</para></listitem> + + <listitem><para>Plaintext passwords are not stored anywhere in + memory or on disk.</para></listitem> + + <listitem><para>Windows NT does not like talking to a server + that does not support encrypted passwords. It will refuse + to browse the server if the server is also in User Level + security mode. It will insist on prompting the user for the + password on each connection, which is very annoying. The + only things you can do to stop this is to use SMB encryption. + </para></listitem> + + <listitem><para>Encrypted password support allows automatic share + (resource) reconnects.</para></listitem> + + <listitem><para>Encrypted passwords are essential for PDC/BDC + operation.</para></listitem> + </itemizedlist> + </sect3> + + + <sect3> + <title>Advantages of Non-Encrypted Passwords</title> + + <itemizedlist> + <listitem><para>Plaintext passwords are not kept + on disk, and are not cached in memory. </para></listitem> + + <listitem><para>Uses same password file as other UNIX + services such as Login and FTP.</para></listitem> + + <listitem><para>Use of other services (such as Telnet and FTP) that + send plain text passwords over the network, so sending them for SMB + is not such a big deal.</para></listitem> + </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> + First, all Samba SAM (Security Account Manager database) accounts require + a UNIX/Linux UID that the account will map to. As users are added to the account + information database, Samba will call the <smbconfoption name="add user script"/> + 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> + <indexterm><primary>idmap uid</primary></indexterm> + <indexterm><primary>idmap gid</primary></indexterm> + The second way to effect Windows SID to UNIX UID mapping is via the + <emphasis>idmap uid</emphasis> and <emphasis>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> + + <sect2 id="idmapbackend"> + <title>Mapping Common UIDs/GIDs on Distributed Machines</title> + + <para> + Samba-3 has a special facility that makes it possible to maintain identical UIDs and GIDs + on all servers in a distributed network. A distributed network is one where there exists + a PDC, one or more BDCs and/or one or more Domain Member servers. Why is this important? + This is important if files are being shared over more than one protocol (e.g., NFS) and where + users are copying files across UNIX/Linux systems using tools such as <command>rsync</command>. + </para> + + <para> + <indexterm><primary>idmap backend</primary></indexterm> + The special facility is enabled using a parameter called <parameter>idmap backend</parameter>. + The default setting for this parameter is an empty string. Technically it is possible to use + an LDAP based idmap backend for UIDs and GIDs, but it makes most sense when this is done for + network configurations that also use LDAP for the SAM backend. Following + <link linkend="idmapbackendexample">example</link> shows that. + </para> + + <para> +<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm> +<smbconfexample id="idmapbackendexample"> +<title>Example configuration with the LDAP idmap backend</title> +<smbconfsection name="[global]"/> +<smbconfoption name="idmap backend">ldap:ldap://ldap-server.quenya.org:636</smbconfoption> +<smbconfcomment>Alternately, this could be specified as:</smbconfcomment> +<smbconfoption name="idmap backend">ldap:ldaps://ldap-server.quenya.org</smbconfoption> +</smbconfexample> + </para> + + <para> + A network administrator who wants to make significant use of LDAP backends will sooner or later be + exposed to the excellent work done by PADL Software. PADL <ulink url="http://www.padl.com"/> have + produced and released to open source an array of tools that might be of interest. These tools include: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>nss_ldap:</emphasis> An LDAP Name Service Switch module to provide native + name service support for AIX, Linux, Solaris, and other operating systems. This tool + can be used for centralized storage and retrieval of UIDs/GIDs. + </para> + </listitem> + + <listitem> + <para> + <emphasis>pam_ldap:</emphasis> A PAM module that provides LDAP integration for UNIX/Linux + system access authentication. + </para> + </listitem> + <listitem> + <para> + <emphasis>idmap_ad:</emphasis> An IDMAP backend that supports the Microsoft Services for + UNIX RFC 2307 schema available from the PADL web + <ulink url="http://www.padl.com/download/xad_oss_plugins.tar.gz">site</ulink>. + </para> + </listitem> + </itemizedlist> + + </sect2> + + <sect2> + <title>Regarding LDAP Directories and Windows Computer Accounts</title> + + <para> + Samba doesn't provide a turnkey solution to LDAP. It is best to deal with the design and configuration + of an LDAP directory prior to integration with Samba. A working knowledge of LDAP makes Samba integration + easy and the lack of a working knowledge of LDAP can make it one a frustrating experience. + </para> + + <para> + Computer (machine) accounts can be placed where ever you like in an LDAP directory subject to some + constraints that are described in this chapter. + </para> + + <para> + The POSIX and SambaSAMAccount components of computer (machine) accounts are both used by Samba. + i.e.: Machine accounts are treated inside Samba in the same way that Windows NT4/200X treats + them. A user account and a machine account are indistinquishable from each other, except that + the machine account ends in a '$' character, as do trust accounts. + </para> + + <para> + The need for Windows user, group, machine, trust, etc. accounts to be tied to a valid UNIX uid + is a design decision that was made a long way back in the history of Samba development. It is + unlikely that this decision will be reversed of changed during the remaining life of the + Samba-3.x series. + </para> + + <para> + The resolution of a UID from the Windows SID is achieved within Samba through a mechanism that + must refer back to the host operating system on which Samba is running. The Name Service + Switcher (NSS) is the preferred mechanism that shields applications (like Samba) from the + need to know everything about every host OS it runs on. + </para> + + <para> + Samba asks the host OS to provide a UID via the <quote>passwd</quote>, <quote>shadow</quote> + and <quote>group</quote> facilities in the NSS control (configuration) file. The best tool + for achieving this is left up to the UNIX administrator to determine. It is not imposed by + Samba. Samba provides winbindd together with its support libraries as one method. It is + possible to do this via LDAP - and for that Samba provides the appropriate hooks so that + all account entities can be located in an LDAP directory. + </para> + + <para> + For many the weapon of choice is to use the PADL nss_ldap utility. This utility must + be configured so that computer accounts can be resolved to a POSIX/UNIX account UID. That + is fundamentally an LDAP design question. The information provided on the Samba list and + in the documentation is directed at providing working examples only. The design + of an LDAP directory is a complex subject that is beyond the scope of this documentation. + </para> + + </sect2> + +</sect1> + +<sect1 id="acctmgmttools"> +<title>Account Management Tools</title> + +<para> +<indexterm><primary>pdbedit</primary></indexterm> +Samba provides two tools for management of user and machine accounts. These tools are +called <command>smbpasswd</command> and <command>pdbedit</command>. +</para> + <sect2> + <title>The <emphasis>smbpasswd</emphasis> Command</title> + + <para> + The smbpasswd utility is similar to the <command>passwd</command> + or <command>yppasswd</command> programs. It maintains the two 32 byte password + fields in the passdb backend. + </para> + + <para> + <command>smbpasswd</command> works in a client-server mode where it contacts the + local smbd to change the user's password on its behalf. This has enormous benefits. + </para> + + <para> + <command>smbpasswd</command> has the capability to change passwords on Windows NT + servers (this only works when the request is sent to the NT Primary Domain Controller + if changing an NT Domain user's password). + </para> + + <para> + <command>smbpasswd</command> can be used to: +<indexterm><primary>User Management</primary></indexterm> +<indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm> + + </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> + + <para> + To run smbpasswd as a normal user just type: + </para> + + <para> +<screen> +&prompt;<userinput>smbpasswd</userinput> +<prompt>Old SMB password: </prompt><userinput><replaceable>secret</replaceable></userinput> +</screen> + For <replaceable>secret</replaceable>, type old value here or press return if + there is no old password. +<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> + If the old value does not match the current value stored for that user, or the two + new values do not match each other, then the password will not be changed. + </para> + + <para> + When invoked by an ordinary user, the command will only allow the user to change his or her own + SMB password. + </para> + + <para> + When run by root, <command>smbpasswd</command> may take an optional argument specifying + the user name whose SMB password you wish to change. When run as root, <command>smbpasswd</command> + does not prompt for or check the old password value, thus allowing root to set passwords + for users who have forgotten their passwords. + </para> + + <para> + <command>smbpasswd</command> is designed to work in the way familiar to UNIX + users who use the <command>passwd</command> or <command>yppasswd</command> commands. + While designed for administrative use, this tool provides essential User Level + password change capabilities. + </para> + + <para> + For more details on using <command>smbpasswd</command>, refer to the man page (the + definitive reference). + </para> + </sect2> + + <sect2 id="pdbeditthing"> + <title>The <emphasis>pdbedit</emphasis> Command</title> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + <command>pdbedit</command> is a tool that can be used only by root. It is used to + manage the passdb backend. <command>pdbedit</command> can be used to: +<indexterm><primary>User Management</primary></indexterm> +<indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm> + + </para> + + <itemizedlist> + <listitem><para>add, remove or modify user accounts.</para></listitem> + <listitem><para>list user accounts.</para></listitem> + <listitem><para>migrate user accounts.</para></listitem> + </itemizedlist> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + The <command>pdbedit</command> tool is the only one that can manage the account + security and policy settings. It is capable of all operations that smbpasswd can + do as well as a super set of them. + </para> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + One particularly important purpose of the <command>pdbedit</command> is to allow + the migration of account information from one passdb backend to another. See the + <link linkend="XMLpassdb">XML</link> password backend section of this chapter. + </para> + + <para> + The following is an example of the user account information that is stored in + a tdbsam password backend. This listing was produced by running: + </para> + +<screen> +&prompt;<userinput>pdbedit -Lv met</userinput> +UNIX username: met +NT username: +Account Flags: [UX ] +User SID: S-1-5-21-1449123459-1407424037-3116680435-2004 +Primary Group SID: S-1-5-21-1449123459-1407424037-3116680435-1201 +Full Name: Melissa E Terpstra +Home Directory: \\frodo\met\Win9Profile +HomeDir Drive: H: +Logon Script: scripts\logon.bat +Profile Path: \\frodo\Profiles\met +Domain: &example.workgroup; +Account desc: +Workstations: melbelle +Munged dial: +Logon time: 0 +Logoff time: Mon, 18 Jan 2038 20:14:07 GMT +Kickoff time: Mon, 18 Jan 2038 20:14:07 GMT +Password last set: Sat, 14 Dec 2002 14:37:03 GMT +Password can change: Sat, 14 Dec 2002 14:37:03 GMT +Password must change: Mon, 18 Jan 2038 20:14:07 GMT +</screen> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + The <command>pdbedit</command> tool allows migration of authentication (account) + databases from one backend to another. For example: To migrate accounts from an + old <filename>smbpasswd</filename> database to a <parameter>tdbsam</parameter> + backend: + </para> + + <procedure> + <step><para> + Set the <smbconfoption name="passdb backend">tdbsam, smbpasswd</smbconfoption>. + </para></step> + + <step><para> + Execute: +<screen> +&rootprompt;<userinput>pdbedit -i smbpasswd -e tdbsam</userinput> +</screen> + </para></step> + + <step><para> + Now remove the <parameter>smbpasswd</parameter> from the passdb backend + configuration in &smb.conf;. + </para></step> + </procedure> + + </sect2> +</sect1> + +<sect1> +<title>Password Backends</title> + +<para> +Samba offers the greatest flexibility in backend account database design of any SMB/CIFS server +technology available today. The flexibility is immediately obvious as one begins to explore this +capability. +</para> + +<para> +It is possible to specify not only multiple different password backends, but even multiple +backends of the same type. For example, to use two different tdbsam databases: +</para> + +<para> +<smbconfblock> + <smbconfoption name="passdb backend">tdbsam:/etc/samba/passdb.tdb tdbsam:/etc/samba/old-passdb.tdb</smbconfoption> +</smbconfblock> +</para> + + + <sect2> + <title>Plaintext</title> + + <para> + Older versions of Samba retrieved user information from the UNIX user database + and eventually some other fields from the file <filename>/etc/samba/smbpasswd</filename> + or <filename>/etc/smbpasswd</filename>. When password encryption is disabled, no + SMB specific data is stored at all. Instead all operations are conducted via the way + that the Samba host OS will access its <filename>/etc/passwd</filename> database. + Linux systems For example, all operations are done via PAM. + </para> + + </sect2> + + <sect2> + <title>smbpasswd &smbmdash; Encrypted Password Database</title> + + <para> +<indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm> + Traditionally, when configuring <smbconfoption name="encrypt passwords">yes</smbconfoption> in Samba's &smb.conf; file, user account + information such as username, LM/NT password hashes, password change times, and account + flags have been stored in the <filename>smbpasswd(5)</filename> file. There are several + disadvantages to this approach for sites with large numbers of users (counted + in the thousands). + </para> + + <itemizedlist> + <listitem><para> + The first problem is that all lookups must be performed sequentially. Given that + there are approximately two lookups per domain logon (one for a normal + session connection such as when mapping a network drive or printer), this + is a performance bottleneck for large sites. What is needed is an indexed approach + such as used in databases. + </para></listitem> + + <listitem><para> + The second problem is that administrators who desire to replicate a smbpasswd file + to more than one Samba server were left to use external tools such as + <command>rsync(1)</command> and <command>ssh(1)</command> and wrote custom, + in-house scripts. + </para></listitem> + + <listitem><para> + Finally, the amount of information that is stored in an smbpasswd entry leaves + no room for additional attributes such as a home directory, password expiration time, + or even a Relative Identifier (RID). + </para></listitem> + </itemizedlist> + + <para> + As a result of these deficiencies, a more robust means of storing user attributes + used by smbd was developed. The API which defines access to user accounts + is commonly referred to as the samdb interface (previously this was called the passdb + API, and is still so named in the Samba CVS trees). + </para> + + <para> + Samba provides an enhanced set of passdb backends that overcome the deficiencies + of the smbpasswd plain text database. These are tdbsam, ldapsam and xmlsam. + Of these, ldapsam will be of most interest to large corporate or enterprise sites. + </para> + + </sect2> + + <sect2> + <title>tdbsam</title> + + <para> +<indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm> + Samba can store user and machine account data in a <quote>TDB</quote> (Trivial Database). + Using this backend does not require any additional configuration. This backend is + recommended for new installations that do not require LDAP. + </para> + + <para> + As a general guide, the Samba Team does not recommend using the tdbsam backend for sites + that have 250 or more users. Additionally, tdbsam is not capable of scaling for use + in sites that require PDB/BDC implementations that require replication of the account + database. Clearly, for reason of scalability, the use of ldapsam should be encouraged. + </para> + + <para> + The recommendation of a 250 user limit is purely based on the notion that this + would generally involve a site that has routed networks, possibly spread across + more than one physical location. The Samba Team has not at this time established + the performance based scalability limits of the tdbsam architecture. + </para> + + </sect2> + + <sect2> + <title>ldapsam</title> + + <para> +<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm> + There are a few points to stress that the ldapsam does not provide. The LDAP + support referred to in this documentation does not include: + </para> + + <itemizedlist> + <listitem><para>A means of retrieving user account information from + an Windows 200x Active Directory server.</para></listitem> + <listitem><para>A means of replacing /etc/passwd.</para></listitem> + </itemizedlist> + + <para> + The second item can be accomplished by using LDAP NSS and PAM modules. LGPL + versions of these libraries can be obtained from + <ulink url="http://www.padl.com/">PADL Software</ulink>. + More information about the configuration of these packages may be found at + <ulink url="http://safari.oreilly.com/?XmlId=1-56592-491-6"> + <emphasis>LDAP, System Administration</emphasis>; Gerald Carter by O'Reilly; Chapter 6: Replacing NIS."</ulink> + </para> + + <para> + This document describes how to use an LDAP directory for storing Samba user + account information traditionally stored in the smbpasswd(5) file. It is + assumed that the reader already has a basic understanding of LDAP concepts + and has a working directory server already installed. For more information + on LDAP architectures and directories, please refer to the following sites: + </para> + + <itemizedlist> + <listitem><para><ulink url="http://www.openldap.org/">OpenLDAP</ulink></para></listitem> + <listitem><para><ulink url="http://iplanet.netscape.com/directory">Sun iPlanet Directory Server</ulink></para></listitem> + </itemizedlist> + + <para> + Two additional Samba resources which may prove to be helpful are: + </para> + + <itemizedlist> + <listitem><para>The <ulink url="http://www.unav.es/cti/ldap-smb/ldap-smb-3-howto.html">Samba-PDC-LDAP-HOWTO</ulink> + maintained by Ignacio Coupeau.</para></listitem> + + <listitem><para>The NT migration scripts from <ulink url="http://samba.idealx.org/">IDEALX</ulink> that are + geared to manage users and group in such a Samba-LDAP Domain Controller configuration. + </para></listitem> + </itemizedlist> + + <sect3> + <title>Supported LDAP Servers</title> + + <para> + 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 the process outlined in <link linkend="bugreport">Reporting Bugs</link> chapter. + </para> + + </sect3> + + <sect3> + <title>Schema and Relationship to the RFC 2307 posixAccount</title> + + + <para> + Samba-3.0 includes the necessary schema file for OpenLDAP 2.0 in + <filename>examples/LDAP/samba.schema</filename>. The sambaSamAccount ObjectClass is given here: + </para> + +<para> +<programlisting> +ObjectClass (1.3.6.1.4.1.7165.2.2.6 NAME 'sambaSamAccount' SUP top AUXILIARY + DESC 'Samba-3.0 Auxiliary SAM Account' + MUST ( uid $ sambaSID ) + MAY ( cn $ sambaLMPassword $ sambaNTPassword $ sambaPwdLastSet $ + sambaLogonTime $ sambaLogoffTime $ sambaKickoffTime $ + sambaPwdCanChange $ sambaPwdMustChange $ sambaAcctFlags $ + displayName $ sambaHomePath $ sambaHomeDrive $ sambaLogonScript $ + sambaProfilePath $ description $ sambaUserWorkstations $ + sambaPrimaryGroupSID $ sambaDomainName )) +</programlisting> +</para> + + <para> + The <filename>samba.schema</filename> file has been formatted for OpenLDAP 2.0/2.1. + The Samba Team owns the OID space used by the above schema and recommends its use. + If you translate the schema to be used with Netscape DS, please submit the modified + schema file as a patch to <ulink url="mailto:jerry@samba.org">jerry@samba.org</ulink>. + </para> + + <para> + Just as the smbpasswd file is meant to store information that provides information additional to a + user's <filename>/etc/passwd</filename> entry, so is the sambaSamAccount object + meant to supplement the UNIX user account information. A sambaSamAccount is a + <constant>AUXILIARY</constant> ObjectClass so it can be used to augment existing + user account information in the LDAP directory, thus providing information needed + for Samba account handling. However, there are several fields (e.g., uid) that overlap + with the posixAccount ObjectClass outlined in RFC2307. This is by design. + </para> + + <!--olem: we should perhaps have a note about shadowAccounts too as many + systems use them, isn'it ? --> + + <para> + In order to store all user account information (UNIX and Samba) in the directory, + it is necessary to use the sambaSamAccount and posixAccount ObjectClass es in + combination. However, smbd will still obtain the user's UNIX account + information via the standard C library calls (e.g., getpwnam(), et al). + This means that the Samba server must also have the LDAP NSS library installed + and functioning correctly. This division of information makes it possible to + store all Samba account information in LDAP, but still maintain UNIX account + information in NIS while the network is transitioning to a full LDAP infrastructure. + </para> + </sect3> + + <sect3> + <title>OpenLDAP Configuration</title> + + <para> + To include support for the sambaSamAccount object in an OpenLDAP directory + server, first copy the samba.schema file to slapd's configuration directory. + The samba.schema file can be found in the directory <filename>examples/LDAP</filename> + in the Samba source distribution. + </para> + +<para> +<screen> +&rootprompt;<userinput>cp samba.schema /etc/openldap/schema/</userinput> +</screen> +</para> + + <para> + Next, include the <filename>samba.schema</filename> file in <filename>slapd.conf</filename>. + The sambaSamAccount object contains two attributes that depend on other schema + files. The <parameter>uid</parameter> attribute is defined in <filename>cosine.schema</filename> and + the <parameter>displayName</parameter> attribute is defined in the <filename>inetorgperson.schema</filename> + file. Both of these must be included before the <filename>samba.schema</filename> file. + </para> + +<para> +<programlisting> +## /etc/openldap/slapd.conf + +## schema files (core.schema is required by default) +include /etc/openldap/schema/core.schema + +## needed for sambaSamAccount +include /etc/openldap/schema/cosine.schema +include /etc/openldap/schema/inetorgperson.schema +include /etc/openldap/schema/nis.schema +include /etc/openldap/schema/samba.schema +.... +</programlisting> +</para> + + <para> + It is recommended that you maintain some indices on some of the most useful attributes, + as in the following example, to speed up searches made on sambaSamAccount objectclasses + (and possibly posixAccount and posixGroup as well): + </para> + +<para> +<programlisting> +# Indices to maintain +## required by OpenLDAP +index objectclass eq + +index cn pres,sub,eq +index sn pres,sub,eq +## required to support pdb_getsampwnam +index uid pres,sub,eq +## required to support pdb_getsambapwrid() +index displayName pres,sub,eq + +## uncomment these if you are storing posixAccount and +## posixGroup entries in the directory as well +##index uidNumber eq +##index gidNumber eq +##index memberUid eq + +index sambaSID eq +index sambaPrimaryGroupSID eq +index sambaDomainName eq +index default sub +</programlisting> +</para> + + <para> + Create the new index by executing: + </para> + +<para> +<screen> +&rootprompt;./sbin/slapindex -f slapd.conf +</screen> +</para> + + <para> + Remember to restart slapd after making these changes: + </para> + +<para> +<screen> +&rootprompt;<userinput>/etc/init.d/slapd restart</userinput> +</screen> +</para> + + </sect3> + + <sect3> + <title>Initialize 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 (DNS entries, and so on): + </para> + +<para> + <smbfile name="samba.ldif.example"> +<programlisting> +# Organization for Samba Base +dn: dc=quenya,dc=org +objectclass: dcObject +objectclass: organization +dc: quenya +o: Quenya Org Network +description: The Samba-3 Network LDAP Example + +# Organizational Role for Directory Management +dn: cn=Manager,dc=quenya,dc=org +objectclass: organizationalRole +cn: Manager +description: Directory Manager + +# Setting up container for users +dn: ou=People,dc=quenya,dc=org +objectclass: top +objectclass: organizationalUnit +ou: People + +# Setting up admin handle for People OU +dn: cn=admin,ou=People,dc=quenya,dc=org +cn: admin +objectclass: top +objectclass: organizationalRole +objectclass: simpleSecurityObject +userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz + +# Setting up container for groups +dn: ou=Groups,dc=quenya,dc=org +objectclass: top +objectclass: organizationalUnit +ou: Groups + +# Setting up admin handle for Groups OU +dn: cn=admin,ou=Groups,dc=quenya,dc=org +cn: admin +objectclass: top +objectclass: organizationalRole +objectclass: simpleSecurityObject +userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz + +# Setting up container for computers +dn: ou=Computers,dc=quenya,dc=org +objectclass: top +objectclass: organizationalUnit +ou: Computers + +# Setting up admin handle for Computers OU +dn: cn=admin,ou=Computers,dc=quenya,dc=org +cn: admin +objectclass: top +objectclass: organizationalRole +objectclass: simpleSecurityObject +userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz +</programlisting> +</smbfile> +</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;<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 store 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 if your + version of Samba was built with LDAP support. Samba automatically builds with LDAP support if the + LDAP libraries are found. + </para> + + <para>LDAP related smb.conf options: + <smbconfoption name="passdb backend">ldapsam:url</smbconfoption>, + <smbconfoption name="ldap admin dn"/>, + <smbconfoption name="ldap delete dn"/>, + <smbconfoption name="ldap filter"/>, + <smbconfoption name="ldap group suffix"/>, + <smbconfoption name="ldap idmap suffix"/>, + <smbconfoption name="ldap machine suffix"/>, + <smbconfoption name="ldap passwd sync"/>, + <smbconfoption name="ldap ssl"/>, + <smbconfoption name="ldap suffix"/>, + <smbconfoption name="ldap user suffix"/>, + </para> + + <para> + These are described in the &smb.conf; man + page and so will not be repeated here. However, a <link linkend="confldapex">sample &smb.conf; file</link> for + use with an LDAP directory could appear as shown below. + </para> + +<para> +<smbconfexample id="confldapex"> +<title>Configuration with LDAP</title> +<smbconfsection name="[global]"/> +<smbconfoption name="security">user</smbconfoption> +<smbconfoption name="encrypt passwords">yes</smbconfoption> +<smbconfoption name="netbios name">MORIA</smbconfoption> +<smbconfoption name="workgroup">NOLDOR</smbconfoption> + +<smbconfcomment>ldap related parameters</smbconfcomment> + +<smbconfcomment>define the DN to use when binding to the directory servers</smbconfcomment> +<smbconfcomment>The password for this DN is not stored in smb.conf. Rather it</smbconfcomment> +<smbconfcomment>must be set by using 'smbpasswd -w secretpw' to store the</smbconfcomment> +<smbconfcomment>passphrase in the secrets.tdb file. If the "ldap admin dn" values</smbconfcomment> +<smbconfcomment>change, this password will need to be reset.</smbconfcomment> +<smbconfoption name="ldap admin dn">"cn=Manager,dc=quenya,dc=org"</smbconfoption> + +<smbconfcomment>Define the SSL option when connecting to the directory</smbconfcomment> +<smbconfcomment>('off', 'start tls', or 'on' (default))</smbconfcomment> +<smbconfoption name="ldap ssl">start tls</smbconfoption> + +<smbconfcomment>syntax: passdb backend = ldapsam:ldap://server-name[:port]</smbconfcomment> +<smbconfoption name="passdb backend">ldapsam:ldap://frodo.quenya.org</smbconfoption> + +<smbconfcomment>smbpasswd -x delete the entire dn-entry</smbconfcomment> +<smbconfoption name="ldap delete dn">no</smbconfoption> + +<smbconfcomment>the machine and user suffix added to the base suffix</smbconfcomment> +<smbconfcomment>wrote WITHOUT quotes. NULL suffixes by default</smbconfcomment> +<smbconfoption name="ldap user suffix">ou=People</smbconfoption> +<smbconfoption name="ldap group suffix">ou=Groups</smbconfoption> +<smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption> + +<smbconfcomment>Trust UNIX account information in LDAP</smbconfcomment> +<smbconfcomment> (see the smb.conf man page for details)</smbconfcomment> + +<smbconfcomment> specify the base DN to use when searching the directory</smbconfcomment> +<smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption> + +<smbconfcomment> generally the default ldap search filter is ok</smbconfcomment> +<smbconfoption name="ldap filter">(uid=%u)</smbconfoption> +</smbconfexample> +</para> + + </sect3> + + <sect3> + <title>Accounts and Groups Management</title> + + <para> +<indexterm><primary>User Management</primary></indexterm> +<indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm> + + As user accounts are managed through the sambaSamAccount objectclass, you should + modify your existing administration tools to deal with sambaSamAccount attributes. + </para> + + <para> + Machine accounts are managed with the sambaSamAccount objectclass, just + like users accounts. However, it is up to you to store those accounts + in a different tree of your LDAP namespace. You should use + <quote>ou=Groups,dc=quenya,dc=org</quote> to store groups and + <quote>ou=People,dc=quenya,dc=org</quote> to store users. Just configure your + NSS and PAM accordingly (usually, in the <filename>/etc/openldap/sldap.conf</filename> + configuration file). + </para> + + <para> + In Samba-3, the group management system is based on POSIX + groups. This means that Samba makes use of the posixGroup objectclass. + For now, there is no NT-like group system management (global and local + groups). Samba-3 knows only about <constant>Domain Groups</constant> + and, unlike MS Windows 2000 and Active Directory, Samba-3 does not + support nested groups. + </para> + + </sect3> + + <sect3> + <title>Security and sambaSamAccount</title> + + + <para> + There are two important points to remember when discussing the security + of sambaSamAccount entries in the directory. + </para> + + <itemizedlist> + <listitem><para><emphasis>Never</emphasis> retrieve the SambaLMPassword or + SambaNTPassword attribute values over an unencrypted LDAP session.</para></listitem> + <listitem><para><emphasis>Never</emphasis> allow non-admin users to + view the SambaLMPassword or SambaNTPassword attribute values.</para></listitem> + </itemizedlist> + + <para> + These password hashes are clear-text equivalents and can be used to impersonate + the user without deriving the original clear-text strings. For more information + on the details of LM/NT password hashes, refer to the + <link linkend="passdb">Account Information Database</link> section of this chapter. + </para> + + <para> + To remedy the first security issue, the <smbconfoption name="ldap ssl"/> &smb.conf; parameter defaults + to require an encrypted session (<smbconfoption name="ldap ssl">on</smbconfoption>) using + the default port of <constant>636</constant> + when contacting the directory server. When using an OpenLDAP server, it + is possible to use the StartTLS LDAP extended operation in the place of + LDAPS. In either case, you are strongly discouraged to disable this security + (<smbconfoption name="ldap ssl">off</smbconfoption>). + </para> + + <para> + Note that the LDAPS protocol is deprecated in favor of the LDAPv3 StartTLS + extended operation. However, the OpenLDAP library still provides support for + the older method of securing communication between clients and servers. + </para> + + <para> + The second security precaution is to prevent non-administrative users from + harvesting password hashes from the directory. This can be done using the + following ACL in <filename>slapd.conf</filename>: + </para> + +<para> +<programlisting> +## allow the "ldap admin dn" access, but deny everyone else +access to attrs=SambaLMPassword,SambaNTPassword + by dn="cn=Samba Admin,ou=People,dc=quenya,dc=org" write + by * none +</programlisting> +</para> + + </sect3> + + <sect3> + <title>LDAP Special Attributes for sambaSamAccounts</title> + + <para> The sambaSamAccount objectclass is composed of the attributes shown in next tables: <link + linkend="attribobjclPartA">Part A</link>, and <link linkend="attribobjclPartB">Part B</link>. + </para> + + <para> + <table frame="all" id="attribobjclPartA"> + <title>Attributes in the sambaSamAccount objectclass (LDAP) &smbmdash; Part A</title> + <tgroup cols="2" align="justify"> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <tbody> + <row><entry><constant>sambaLMPassword</constant></entry><entry>The LANMAN password 16-byte hash stored as a character + representation of a hexadecimal string.</entry></row> + <row><entry><constant>sambaNTPassword</constant></entry><entry>The NT password hash 16-byte stored as a character + representation of a hexadecimal string.</entry></row> + <row><entry><constant>sambaPwdLastSet</constant></entry><entry>The integer time in seconds since 1970 when the + <constant>sambaLMPassword</constant> and <constant>sambaNTPassword</constant> attributes were last set. + </entry></row> + + <row><entry><constant>sambaAcctFlags</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).</entry></row> + + <row><entry><constant>sambaLogonTime</constant></entry><entry>Integer value currently unused</entry></row> + + <row><entry><constant>sambaLogoffTime</constant></entry><entry>Integer value currently unused</entry></row> + + <row><entry><constant>sambaKickoffTime</constant></entry><entry>Specifies the time (UNIX time format) when the user + will be locked down and cannot login any longer. If this attribute is omitted, then the account will never expire. + If you use this attribute together with `shadowExpire' of the `shadowAccount' objectClass, will enable accounts to + expire completely on an exact date.</entry></row> + + <row><entry><constant>sambaPwdCanChange</constant></entry><entry>Specifies the time (UNIX time format) from which on the user is allowed to + change his password. If attribute is not set, the user will be free to change his password whenever he wants.</entry></row> + + <row><entry><constant>sambaPwdMustChange</constant></entry><entry>Specifies the time (UNIX time format) since when the user is + forced to change his password. If this value is set to `0', the user will have to change his password at first login. + If this attribute is not set, then the password will never expire.</entry></row> + + <row><entry><constant>sambaHomeDrive</constant></entry><entry>Specifies the drive letter to which to map the + UNC path specified by sambaHomePath. The drive letter must be specified in the form <quote>X:</quote> + where X is the letter of the drive to map. Refer to the <quote>logon drive</quote> parameter in the + smb.conf(5) man page for more information.</entry></row> + + <row><entry><constant>sambaLogonScript</constant></entry><entry>The sambaLogonScript 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 <smbconfoption name="logon script"/> parameter in the + &smb.conf; man page for more information.</entry></row> + + <row><entry><constant>sambaProfilePath</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 + <smbconfoption name="logon path"/> parameter in the &smb.conf; man page for more information.</entry></row> + + <row><entry><constant>sambaHomePath</constant></entry><entry>The sambaHomePath property specifies the path of + the home directory for the user. The string can be null. If sambaHomeDrive is set and specifies + a drive letter, sambaHomePath 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. + </entry></row> + </tbody> + </tgroup></table> + </para> + <para> + <table frame="all" id="attribobjclPartB"> + <title>Attributes in the sambaSamAccount objectclass (LDAP) &smbmdash; Part B</title> + <tgroup cols="2" align="justify"> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <tbody> + <row><entry><constant>sambaUserWorkstations</constant></entry><entry>Here you can give a comma-separated list of machines + on which the user is allowed to login. You may observe problems when you try to connect to an Samba Domain Member. + Because Domain Members are not in this list, the Domain Controllers will reject them. Where this attribute is omitted, + the default implies no restrictions. + </entry></row> + + <row><entry><constant>sambaSID</constant></entry><entry>The security identifier(SID) of the user. + The Windows equivalent of UNIX UIDs.</entry></row> + + <row><entry><constant>sambaPrimaryGroupSID</constant></entry><entry>The Security IDentifier (SID) of the primary group + of the user.</entry></row> + + <row><entry><constant>sambaDomainName</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 <link linkend="samba-pdc">Domain Control</link>, for details on + how to configure Samba as a Primary Domain Controller). The following four attributes + are only stored with the sambaSamAccount entry if the values are non-default values: + </para> + + <itemizedlist> + <listitem><para>sambaHomePath</para></listitem> + <listitem><para>sambaLogonScript</para></listitem> + <listitem><para>sambaProfilePath</para></listitem> + <listitem><para>sambaHomeDrive</para></listitem> + </itemizedlist> + + <para> + These attributes are only stored with the sambaSamAccount entry if + the values are non-default values. For example, assume MORIA has now been + configured as a PDC and that <smbconfoption name="logon home">\\%L\%u</smbconfoption> was defined in + its &smb.conf; file. When a user named <quote>becky</quote> logons to the domain, + the <smbconfoption name="logon home"/> string is expanded to \\MORIA\becky. + If the smbHome attribute exists in the entry <quote>uid=becky,ou=People,dc=samba,dc=org</quote>, + this value is used. However, if this attribute does not exist, then the value + of the <smbconfoption name="logon home"/> parameter is used in its place. Samba + will only write the attribute value to the directory entry if the value is + something other than the default (e.g., <filename>\\MOBY\becky</filename>). + </para> + + </sect3> + + <sect3> + <title>Example LDIF Entries for a sambaSamAccount</title> + + <para> + The following is a working LDIF that demonstrates the use of the SambaSamAccount objectclass: + </para> + + <para> + <smbfile name="samba.ldif.example2"> + <programlisting> + dn: uid=guest2, ou=People,dc=quenya,dc=org + sambaLMPassword: 878D8014606CDA29677A44EFA1353FC7 + sambaPwdMustChange: 2147483647 + sambaPrimaryGroupSID: S-1-5-21-2447931902-1787058256-3961074038-513 + sambaNTPassword: 552902031BEDE9EFAAD3B435B51404EE + sambaPwdLastSet: 1010179124 + sambaLogonTime: 0 + objectClass: sambaSamAccount + uid: guest2 + sambaKickoffTime: 2147483647 + sambaAcctFlags: [UX ] + sambaLogoffTime: 2147483647 + sambaSID: S-1-5-21-2447931902-1787058256-3961074038-5006 + sambaPwdCanChange: 0 +</programlisting> +</smbfile> + </para> + + <para> + The following is an LDIF entry for using both the sambaSamAccount and + posixAccount objectclasses: + </para> + + <para> + <smbfile name="samba.ldif.example3"> + <programlisting> + dn: uid=gcarter, ou=People,dc=quenya,dc=org + sambaLogonTime: 0 + displayName: Gerald Carter + sambaLMPassword: 552902031BEDE9EFAAD3B435B51404EE + sambaPrimaryGroupSID: S-1-5-21-2447931902-1787058256-3961074038-1201 + objectClass: posixAccount + objectClass: sambaSamAccount + sambaAcctFlags: [UX ] + userPassword: {crypt}BpM2ej8Rkzogo + uid: gcarter + uidNumber: 9000 + cn: Gerald Carter + loginShell: /bin/bash + logoffTime: 2147483647 + gidNumber: 100 + sambaKickoffTime: 2147483647 + sambaPwdLastSet: 1010179230 + sambaSID: S-1-5-21-2447931902-1787058256-3961074038-5004 + homeDirectory: /home/moria/gcarter + sambaPwdCanChange: 0 + sambaPwdMustChange: 2147483647 + sambaNTPassword: 878D8014606CDA29677A44EFA1353FC7 +</programlisting> +</smbfile> + </para> + + </sect3> + + <sect3> + <title>Password Synchronization</title> + + <para> + Samba-3 and later can update the non-samba (LDAP) password stored with an account. When + using pam_ldap, this allows changing both UNIX and Windows passwords at once. + </para> + + <para>The <smbconfoption name="ldap passwd sync"/> options can have the values shown in + <link linkend="ldappwsync">the next table</link>.</para> + + <table frame="all" id="ldappwsync"> + <title>Possible <emphasis>ldap passwd sync</emphasis> values</title> + <tgroup cols="2"> + <colspec align="left" colwidth="1*"/> + <colspec align="justify" colwidth="4*"/> + <thead> + <row><entry align="left">Value</entry><entry align="center">Description</entry></row> + </thead> + <tbody> + <row><entry>yes</entry><entry><para>When the user changes his password, update + <constant>SambaNTPassword</constant>, <constant>SambaLMPassword</constant> + and the <constant>password</constant> fields.</para></entry></row> + + <row><entry>no</entry><entry><para>Only update <constant>SambaNTPassword</constant> and <constant>SambaLMPassword</constant>.</para></entry></row> + + <row><entry>only</entry><entry><para>Only update the LDAP password and let the LDAP server worry about the other fields. + This option is only available on some LDAP servers. Only when the LDAP server + supports LDAP_EXOP_X_MODIFY_PASSWD.</para></entry></row> + </tbody> + </tgroup> + </table> + + + <para>More information can be found in the &smb.conf; man page.</para> + + </sect3> + + </sect2> + + <sect2> + <title>MySQL</title> + + <para> +<indexterm><primary>SAM backend</primary><secondary>mysqlsam</secondary></indexterm> + Every so often someone will come along with a great new idea. Storing user accounts in a + 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 cannot attempt + to document every 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> + <title>Creating the Database</title> + + <para> + You can set up your own table and specify the field names to pdb_mysql (see below + for the column names) or use the default table. The file <filename>examples/pdb/mysql/mysql.dump</filename> + contains the correct queries to create the required tables. Use the command: + +<screen> +&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> + + <sect3> + <title>Configuring</title> + + <para>This plug-in lacks some good documentation, but here is some brief information. Add the following to the + <smbconfoption name="passdb backend"/> variable in your &smb.conf;: +<smbconfblock> +<smbconfoption name="passdb backend">[other-plugins] mysql:identifier [other-plugins]</smbconfoption> +</smbconfblock> + </para> + + <para>The identifier can be any string you like, as long as it does not collide with + the identifiers of other plugins or other instances of pdb_mysql. If you + specify multiple pdb_mysql.so entries in <smbconfoption name="passdb backend"/>, you also need to + use different identifiers. + </para> + + <para> + Additional options can be given through the &smb.conf; file in the <smbconfsection name="[global]"/> section. + Refer to <link linkend="mysqlpbe">the following table</link>. + </para> + + <table frame="all" id="mysqlpbe"> + <title>Basic smb.conf options for MySQL passdb backend</title> + <tgroup cols="2"> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row><entry>Field</entry><entry>Contents</entry></row> + </thead> + <tbody> + <row><entry>mysql host</entry><entry>Host name, defaults to `localhost'</entry></row> + <row><entry>mysql password</entry><entry></entry></row> + <row><entry>mysql user</entry><entry>Defaults to `samba'</entry></row> + <row><entry>mysql database</entry><entry>Defaults to `samba'</entry></row> + <row><entry>mysql port</entry><entry>Defaults to 3306</entry></row> + <row><entry>table</entry><entry>Name of the table containing the users</entry></row> + </tbody> + </tgroup> + </table> + + <warning> + <para> + Since the password for the MySQL user is stored in the &smb.conf; file, you should make the &smb.conf; file + readable only to the user who runs Samba. This is considered a security bug and will soon be fixed. + </para> + </warning> + + <para>Names of the columns are given in <link linkend="moremysqlpdbe">the next table</link>. + The default column names can be found in the example table dump. + </para> + + <para> + <table frame="all" id="moremysqlpdbe"> + <title>MySQL field names for MySQL passdb backend</title> + <tgroup cols="3" align="justify"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <thead> + <row><entry>Field</entry><entry>Type</entry><entry>Contents</entry></row> + </thead> + <tbody> + <row><entry>logon time column</entry><entry>int(9)</entry><entry>UNIX time stamp of last logon of user</entry></row> + <row><entry>logoff time column</entry><entry>int(9)</entry><entry>UNIX time stamp of last logoff of user</entry></row> + <row><entry>kickoff time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment user should be kicked off workstation (not enforced)</entry></row> + <row><entry>pass last set time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment password was last set</entry></row> + <row><entry>pass can change time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment from which password can be changed</entry></row> + <row><entry>pass must change time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment on which password must be changed</entry></row> + <row><entry>username column</entry><entry>varchar(255)</entry><entry>UNIX username</entry></row> + <row><entry>domain column</entry><entry>varchar(255)</entry><entry>NT domain user belongs to</entry></row> + <row><entry>nt username column</entry><entry>varchar(255)</entry><entry>NT username</entry></row> + <row><entry>fullname column</entry><entry>varchar(255)</entry><entry>Full name of user</entry></row> + <row><entry>home dir column</entry><entry>varchar(255)</entry><entry>UNIX homedir path (equivalent of the <smbconfoption name="logon home"/> parameter.</entry></row> + <row><entry>dir drive column</entry><entry>varchar(2)</entry><entry>Directory drive path (e.g., <quote>H:</quote>)</entry></row> + <row><entry>logon script column</entry><entry>varchar(255)</entry><entry>Batch file to run on client side when logging on</entry></row> + <row><entry>profile path column</entry><entry>varchar(255)</entry><entry>Path of profile</entry></row> + <row><entry>acct desc column</entry><entry>varchar(255)</entry><entry>Some ASCII NT user data</entry></row> + <row><entry>workstations column</entry><entry>varchar(255)</entry><entry>Workstations user can logon to (or NULL for all)</entry></row> + <row><entry>unknown string column</entry><entry>varchar(255)</entry><entry>Unknown string</entry></row> + <row><entry>munged dial column</entry><entry>varchar(255)</entry><entry>Unknown</entry></row> + <row><entry>user sid column</entry><entry>varchar(255)</entry><entry>NT user SID</entry></row> + <row><entry>group sid column</entry><entry>varchar(255)</entry><entry>NT group SID</entry></row> + <row><entry>lanman pass column</entry><entry>varchar(255)</entry><entry>Encrypted lanman password</entry></row> + <row><entry>nt pass column</entry><entry>varchar(255)</entry><entry>Encrypted nt passwd</entry></row> + <row><entry>plain pass column</entry><entry>varchar(255)</entry><entry>Plaintext password</entry></row> + <row><entry>acct ctrl column</entry><entry>int(9)</entry><entry>NT user data</entry></row> + <row><entry>unknown 3 column</entry><entry>int(9)</entry><entry>Unknown</entry></row> + <row><entry>logon divs column</entry><entry>int(9)</entry><entry>Unknown</entry></row> + <row><entry>hours len column</entry><entry>int(9)</entry><entry>Unknown</entry></row> + <row><entry>bad password count column</entry><entry>int(5)</entry><entry>Number of failed password tries before disabling an account</entry></row> + <row><entry>logon count column</entry><entry>int(5)</entry><entry>Number of logon attempts</entry></row> + <row><entry>unknown 6 column</entry><entry>int(9)</entry><entry>Unknown</entry></row> + </tbody></tgroup> + </table> + </para> + + <para> + You can put a colon (:) after the name of each column, which + should specify the column to update when updating the table. One can also specify nothing behind the colon, in which case the field data will not be updated. Setting a column name to <parameter>NULL</parameter> means the field should not be used. + </para> + + <para><link linkend="mysqlsam">An example configuration</link> looks like: + </para> + + <smbconfexample id="mysqlsam"> + <title>Example configuration for the MySQL passdb backend</title> + <smbconfsection name="[global]"/> + <smbconfoption name="passdb backend">mysql:foo</smbconfoption> + <smbconfoption name="foo:mysql user">samba</smbconfoption> + <smbconfoption name="foo:mysql password">abmas</smbconfoption> + <smbconfoption name="foo:mysql database">samba</smbconfoption> + <smbconfcomment>domain name is static and can't be changed</smbconfcomment> + <smbconfoption name="foo:domain column">'MYWORKGROUP':</smbconfoption> + <smbconfcomment>The fullname column comes from several other columns</smbconfcomment> + <smbconfoption name="foo:fullname column">CONCAT(firstname,' ',surname):</smbconfoption> + <smbconfcomment>Samba should never write to the password columns</smbconfcomment> + <smbconfoption name="foo:lanman pass column">lm_pass:</smbconfoption> + <smbconfoption name="foo:nt pass column">nt_pass:</smbconfoption> + <smbconfcomment>The unknown 3 column is not stored</smbconfcomment> + <smbconfoption name="foo:unknown 3 column">NULL</smbconfoption> + </smbconfexample> + </sect3> + + <sect3> + <title>Using Plaintext Passwords or Encrypted Password</title> + + <para> +<indexterm><primary>encrypted passwords</primary></indexterm> + I strongly discourage the use of plaintext passwords, however, you can use them. + </para> + + <para> + If you would like to use plaintext passwords, set + `identifier:lanman pass column' and `identifier:nt pass column' to + `NULL' (without the quotes) and `identifier:plain pass column' to the + name of the column containing the plaintext passwords. + </para> + + <para> + If you use encrypted passwords, set the 'identifier:plain pass + column' to 'NULL' (without the quotes). This is the default. + </para> + + </sect3> + + <sect3> + <title>Getting Non-Column Data from the Table</title> + + <para> + It is possible to have not all data in the database by making some `constant'. + </para> + + <para> + For example, you can set `identifier:fullname column' to + something like <?latex \linebreak ?><command>CONCAT(Firstname,' ',Surname)</command> + </para> + + <para> + Or, set `identifier:workstations column' to: + <command>NULL</command></para> + + <para>See the MySQL documentation for more language constructs.</para> + + </sect3> + </sect2> + + <sect2 id="XMLpassdb"> + <title>XML</title> + + <para> +<indexterm><primary>SAM backend</primary><secondary>xmlsam</secondary></indexterm> + This module requires libxml2 to be installed.</para> + + <para>The usage of pdb_xml is fairly straightforward. To export data, use: + </para> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + <prompt>$ </prompt> <userinput>pdbedit -e xml:filename</userinput> + </para> + + <para> + (where filename is the name of the file to put the data in) + </para> + + <para> + To import data, use: + <prompt>$ </prompt> <userinput>pdbedit -i xml:filename</userinput> + </para> + </sect2> +</sect1> + +<sect1> +<title>Common Errors</title> + + <sect2> + <title>Users Cannot Logon</title> + + <para><quote>I've installed Samba, but now I can't log on with my UNIX account! </quote></para> + + <para>Make sure your user has been added to the current Samba <smbconfoption name="passdb backend"/>. + Read the section <link linkend="acctmgmttools">Account Management Tools</link> for details.</para> + + </sect2> + + <sect2> + <title>Users Being Added to the Wrong Backend Database</title> + + <para> + A few complaints have been received 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> + <smbconfblock> + <smbconfsection name="[global]"/> + <member>...</member> + <smbconfoption name="passdb backend">smbpasswd, tdbsam</smbconfoption> + <member>...</member> + </smbconfblock> + </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> +<smbconfblock> +[globals] +... +<smbconfoption name="passdb backend">tdbsam, smbpasswd</smbconfoption> +... +</smbconfblock> + </para> + + </sect2> + + <sect2> + <title>Configuration of <parameter>auth methods</parameter></title> + + <para> + When explicitly setting an <smbconfoption name="auth methods"/> parameter, + <parameter>guest</parameter> must be specified as the first entry on the line, + for example, <smbconfoption name="auth methods">guest sam</smbconfoption>. + </para> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml b/docs/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml new file mode 100644 index 0000000000..c529963155 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml @@ -0,0 +1,506 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="PolicyMgmt"> +<chapterinfo> + &author.jht; + <pubdate>April 3 2003</pubdate> +</chapterinfo> + +<title>System and Account Policies</title> + +<para> +This chapter summarizes the current state of knowledge derived from personal +practice and knowledge from Samba mailing list subscribers. Before reproduction +of posted information, every effort has been made to validate the information given. +Where additional information was uncovered through this validation it is provided +also. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +When MS Windows NT 3.5 was introduced, the hot new topic was the ability to implement +Group Policies for users and groups. Then along came MS Windows NT4 and a few sites +started to adopt this capability. How do we know that? By the number of <quote>boo-boos</quote> +(or mistakes) administrators made and then requested help to resolve. +</para> + +<para> +<indexterm><primary>group policies</primary></indexterm> +<indexterm><primary>GPOs</primary></indexterm> +<indexterm><primary>group policy objects</primary><see>GPOs</see></indexterm> +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 make 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 obvious from the Samba +mailing list as in 2000 and 2001 when there were 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 &smbmdash; the <command>editreg</command> tool +&smbmdash; may become an important part of the future Samba administrators' +arsenal is described in this document. +</para> + +</sect1> + +<sect1> +<title>Creating and Managing System Policies</title> + +<para> +Under MS Windows platforms, particularly those following the release of MS Windows +NT4 and MS Windows 95, it is possible to create a type of file that would be placed +in the NETLOGON share of a Domain Controller. As the client logs onto the network, +this file is read and the contents initiate changes to the registry of the client +machine. This file allows changes to be made to those parts of the registry that +affect users, groups of users, or machines. +</para> + +<para> +<indexterm><primary>Config.POL</primary></indexterm> +For MS Windows 9x/ME, this file must be called <filename>Config.POL</filename> and may +be generated using a tool called <filename>poledit.exe</filename>, better known as the +Policy Editor. The policy editor was provided on the Windows 98 installation CD, but +disappeared again with the introduction of MS Windows Me (Millennium Edition). From +comments of MS Windows network administrators, it would appear that this tool became +a part of the MS Windows Me Resource Kit. +</para> + +<para> +<indexterm><primary>System Policy Editor</primary></indexterm> +MS Windows NT4 Server products include the <emphasis>System Policy Editor</emphasis> +under <guimenu>Start -> Programs -> Administrative Tools</guimenu>. +For MS Windows NT4 and later clients, this file must be called <filename>NTConfig.POL</filename>. +</para> + +<para> +New with the introduction of MS Windows 2000 was the Microsoft Management Console +or MMC. This tool is the new wave in the ever-changing landscape of Microsoft +methods for management of network access and security. Every new Microsoft product +or technology seems to make the old rules obsolete and introduces newer and more +complex tools and methods. To Microsoft's credit, the MMC does appear to +be a step forward, but improved functionality comes at a great price. +</para> + +<para> +Before embarking on the configuration of network and system policies, it is highly +advisable to read the documentation available from Microsoft's Web site regarding +<ulink url="http://www.microsoft.com/ntserver/techresources/management/prof_policies.asp"> +Implementing Profiles and Policies in Windows NT 4.0</ulink> available from Microsoft. +There are a large number of documents in addition to this old one that should also +be read and understood. Try searching on the Microsoft Web site for <quote>Group Policies</quote>. +</para> + +<para> +What follows is a brief discussion with some helpful notes. The information provided +here is incomplete &smbmdash; you are warned. +</para> + + <sect2> + <title>Windows 9x/ME Policies</title> + + <para> + You need the Windows 98 Group Policy Editor to set up Group Profiles under Windows 9x/ME. + It can be found on the original full product Windows 98 installation CD under + <filename>tools/reskit/netadmin/poledit</filename>. Install this using the + Add/Remove Programs facility and then click on <guiicon>Have Disk</guiicon>. + </para> + + + <para> +<indexterm><primary>NTConfig.POL</primary></indexterm> + Use the Group Policy Editor to create a policy file that specifies the location of + user profiles and/or <filename>My Documents</filename>, and so on. Then save these + settings in a file called <filename>Config.POL</filename> that needs to be placed in the + root of the <smbconfsection name="[NETLOGON]"/> share. If Windows 98 is configured to log onto + the Samba Domain, it will automatically read this file and update the Windows 9x/Me registry + of the machine as it logs on. + </para> + + <para> + Further details are covered in the Windows 98 Resource Kit documentation. + </para> + + <para> + If you do not take the correct steps, then every so often Windows 9x/ME will check the + integrity of the registry and restore its settings from the back-up + copy of the registry it stores on each Windows 9x/ME machine. So, you will + occasionally notice things changing back to the original settings. + </para> + + <para> + Install the group policy handler for Windows 9x/Me to pick up Group Policies. Look on the + Windows 98 CDROM in <filename>\tools\reskit\netadmin\poledit</filename>. + Install group policies on a Windows 9x/Me client by double-clicking on + <filename>grouppol.inf</filename>. Log off and on again a couple of times and see + if Windows 98 picks up Group Policies. Unfortunately, this needs to be done on every + Windows 9x/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 not with NT Workstation. There is a Policy Editor on an NT4 + Workstation but it is not suitable for creating domain policies. + Furthermore, 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</filename>, <filename>common.adm</filename> and <filename>winnt.adm</filename>. + It is convenient to put the two <filename>*.adm</filename> files in the <filename>c:\winnt\inf</filename> + directory, which is where the binary will look for them unless told otherwise. This + directory is normally <quote>hidden.</quote> + </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>, + 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> + + <sect3> + <title>Registry Spoiling</title> + + <para> + With NT4-style registry-based policy changes, a large number of settings are not + automatically reversed as the user logs off. The settings that were in the + <filename>NTConfig.POL</filename> file were applied to the client machine registry and apply to the + hive key HKEY_LOCAL_MACHINE are permanent until explicitly reversed. This is known + as tattooing. It can have serious consequences downstream and the administrator must + be extremely careful not to lock out the ability to manage the machine at a later date. + </para> + + </sect3> + </sect2> + <sect2> + <title>MS Windows 200x/XP Professional Policies</title> + + <para> + Windows NT4 system policies allow the setting of registry parameters specific to + users, groups and computers (client workstations) that are members of the NT4-style + domain. Such policy files will work with MS Windows 200x/XP clients also. + </para> + + <para> + New to MS Windows 2000, Microsoft recently introduced a 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 improved. + </para> + + <para> +<indexterm><primary>GPOs</primary></indexterm> + The older NT4-style registry-based policies are known as <emphasis>Administrative Templates</emphasis> + in MS Windows 2000/XP Group Policy Objects (GPOs). The latter includes the 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> + + <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, password + and selects the domain name to which the logon will attempt to take place. During the logon process, + the client machine reads the <filename>NTConfig.POL</filename> file from the NETLOGON share on + the authenticating server and modifies the local registry values according to the settings in this file. + </para> + + <para> + Windows 200x GPOs are feature-rich. They are not stored in the NETLOGON share, but 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 clients, the policy file is read and executed only as each user logs onto the network. + MS Windows 200x policies are much more complex &smbmdash; 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 concurrently 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 Windows 200x/XP Policies</title> + + <para> +<indexterm><primary>GPOs</primary></indexterm> +<indexterm><primary>System Policy Editor</primary></indexterm> + 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, and select the <guibutton>Properties</guibutton>. + </para></step> + + <step><para> + 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> + 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 an .adm extension, both in NT4 as well as in Windows 200x/XP. + Beware, however, the .adm files are not interchangeable across NT4 and Windows 200x. + The latter 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 administrator 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> +<title>Managing Account/User Policies</title> + +<para> +Policies can define a specific user's settings or the settings for a group of users. The resulting +policy file contains the registry settings for all users, groups, and computers that will be using +the policy file. Separate policy files for each user, group, or computer are not necessary. +</para> + +<para> +<indexterm><primary>NTConfig.POL</primary></indexterm> +If you create a policy that will be automatically downloaded from validating Domain Controllers, +you should name the file <filename>NTConfig.POL</filename>. As system administrator, you have the option of renaming the +policy file and, by modifying the Windows NT-based workstation, directing the computer to update +the policy from a manual path. You can do this by either manually changing the registry or by using +the System Policy Editor. This can even be a local path such that each machine has its own policy file, +but if a change is necessary to all machines, it must be made individually to each workstation. +</para> + +<para> +When a Windows NT4/200x/XP machine logs onto the network, the client looks in the NETLOGON share on +the authenticating domain controller for the presence of the NTConfig.POL file. If one exists it is +downloaded, parsed and then applied to the user's part of the registry. +</para> + +<para> +<indexterm><primary>GPOs</primary></indexterm> +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>spoiling</emphasis> effect. +This has considerable advantage compared with the use of <filename>NTConfig.POL</filename> (NT4) style policy updates. +</para> + +<para> +In addition to user access controls that may be imposed or applied via system and/or group policies +in a manner that works in conjunction with user profiles, the user management environment under +MS Windows NT4/200x/XP allows per domain as well as per user account restrictions to be applied. +Common restrictions that are frequently used include: +</para> + +<para> +<indexterm><primary>Account Controls</primary></indexterm> +<itemizedlist> + <listitem><para>Logon hours</para></listitem> + <listitem><para>Password aging</para></listitem> + <listitem><para>Permitted logon from certain machines only</para></listitem> + <listitem><para>Account type (local or global)</para></listitem> + <listitem><para>User rights</para></listitem> +</itemizedlist> +</para> + +<para> +Samba-3.0.20 does not yet implement all account controls that are common to MS Windows NT4/200x/XP. +While it is possible to set many controls using the Domain User Manager for MS Windows NT4, only password +expiry is functional today. Most of the remaining controls at this time have only stub routines +that may eventually be completed to provide actual control. Do not be misled by the fact that a +parameter can be set using the NT4 Domain User Manager or in the <filename>NTConfig.POL</filename>. +</para> + +</sect1> +<sect1> +<title>Management Tools</title> + +<para> +Anyone who wishes to create or manage Group Policies will need to be familiar with a number of tools. +The following sections describe a few key tools that will help you to create a low maintenance user +environment. +</para> + + <sect2> + <title>Samba Editreg Tool-set</title> + + <para> +<indexterm><primary>editreg</primary></indexterm> +<indexterm><primary>NTUser.DAT</primary></indexterm> +<indexterm><primary>NTConfig.POL</primary></indexterm> + A new tool called <command>editreg</command> is under development. This tool can be used + to edit registry files (called <filename>NTUser.DAT</filename>) that are stored in user + and group profiles. <filename>NTConfig.POL</filename> files have the same structure as the + <filename>NTUser.DAT</filename> file and can be edited using this tool. <command>editreg</command> + is being built with the intent to enable <filename>NTConfig.POL</filename> files to be saved in text format and to + permit the building of new <filename>NTConfig.POL</filename> files with extended capabilities. It is proving difficult + to realize this capability, so do not be surprised if this feature does not materialize. Formal + capabilities will be announced at the time that this tool is released for production use. + </para> + + </sect2> + + <sect2> + <title>Windows NT4/200x</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, and the Registry Editor (regedt32.exe). + Under MS Windows 200x/XP, this is done using the Microsoft Management Console (MMC) with appropriate + <quote>snap-ins,</quote> 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 user account and policy information include: + <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> +<title>System Startup and Logon Processing Overview</title> + +<para> +The following attempts to document the order of processing the system and user policies following a system +reboot and as part of the user logon: +</para> + +<orderedlist> + <listitem><para> + Network starts, then Remote Procedure Call System Service (RPCSS) and Multiple Universal Naming + Convention Provider (MUP) start. + </para></listitem> + + <listitem><para> + Where Active Directory is involved, an ordered list of Group Policy Objects (GPOs) is downloaded + and applied. The list may include GPOs that: +<itemizedlist> + <listitem><para>Apply to the location of machines in a Directory.</para></listitem> + <listitem><para>Apply only when settings have changed.</para></listitem> + <listitem><para>Depend on configuration of the scope of applicability: local, + site, domain, organizational unit, and so on.</para></listitem> +</itemizedlist> + No desktop user interface is presented until the above have been processed. + </para></listitem> + + <listitem><para> + Execution of start-up scripts (hidden and synchronous by default). + </para></listitem> + + <listitem><para> + A keyboard action to effect start of logon (Ctrl-Alt-Del). + </para></listitem> + + <listitem><para> + User credentials are validated, user profile is loaded (depends on policy settings). + </para></listitem> + + <listitem><para> + An ordered list of user GPOs is obtained. The list contents depends on what is configured in respect of: + +<itemizedlist> + <listitem><para>Is the user a Domain Member, thus subject to particular policies?</para></listitem> + <listitem><para>Loopback enablement, and the state of the loopback policy (Merge or Replace).</para></listitem> + <listitem><para>Location of the Active Directory itself.</para></listitem> + <listitem><para>Has the list of GPOs changed? No processing is needed if not changed.</para></listitem> +</itemizedlist> + </para></listitem> + + <listitem><para> + User Policies are applied from Active Directory. Note: There are several types. + </para></listitem> + + <listitem><para> + Logon scripts are run. New to Windows 200x and Active Directory, logon scripts may be obtained based on Group + Policy objects (hidden and executed synchronously). NT4-style logon scripts are then run in a normal + window. + </para></listitem> + + <listitem><para> + The User Interface as determined from the GPOs is presented. Note: In a Samba domain (like an NT4 + Domain), machine (system) policies are applied at start-up; user policies are applied at logon. + </para></listitem> +</orderedlist> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +Policy-related problems can be quite 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> +<quote>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 do not see it. It worked fine with Win 98 but does not +work any longer since we upgraded to Win XP Pro. Any hints?</quote> +</para> + +<para> +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 it is in the +correct format for your MS Windows XP Pro clients. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Portability.xml b/docs/Samba3-HOWTO/TOSHARG-Portability.xml new file mode 100644 index 0000000000..a5455a6c67 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Portability.xml @@ -0,0 +1,244 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="Portability"> +<chapterinfo> + &author.jelmer; + &author.jht; + <!-- Some other people as well, but there were no author names in the text files this file is based on--> +</chapterinfo> + +<title>Portability</title> + +<para>Samba works on a wide range of platforms but the interface all the +platforms provide is not always compatible. This chapter contains +platform-specific information about compiling and using Samba.</para> + +<sect1> +<title>HPUX</title> + +<para> +HP's implementation of supplementary groups is non-standard (for +historical 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 <filename>/etc/group</filename> to <filename>/etc/logingroup</filename> +(hard link does not work for reasons too obtuse 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> + +<para> +If you encounter this problem, make sure the programs that are failing +to initgroups() are run as users, not in any groups with GIDs outside the +allowed range. +</para> + +<para>This is documented in the HP manual pages under setgroups(2) and passwd(4). +</para> + +<para> +On HP-UX you must use gcc or the HP ANSI compiler. The free compiler +that comes with HP-UX is not ANSI compliant and cannot compile Samba. +</para> + +</sect1> + +<sect1> +<title>SCO UNIX</title> + +<para> +If you run an old version of SCO UNIX, 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 (<ulink noescape="1" url="ftp://ftp.sco.com/">ftp.sco.com</ulink>, directory SLS, +files uod385a.Z and uod385a.ltr.Z). +</para> + +<para> +The information provided here refers to an old version of SCO UNIX. If you require +binaries for more recent SCO UNIX products, please contact SCO to obtain packages that are +ready to install. You should also verify with SCO that your platform is up-to-date for the +binary packages you will install. This is important if you wish to avoid data corruption +problems with your installation. To build Samba for SCO UNIX products may +require significant patching of Samba source code. It is much easier to obtain binary +packages directly from SCO. +</para> + +</sect1> + +<sect1> +<title>DNIX</title> + +<para> +DNIX has a problem with seteuid() and setegid(). These routines are +needed for Samba to work correctly, but they were left out of the DNIX +C library for some reason. +</para> + +<para> +For this reason Samba by default defines the macro NO_EID in the DNIX +section of includes.h. This works around the problem in a limited way, +but it is far from ideal, and some things still will not work right. +</para> + +<para> +To fix the problem properly, you need to assemble the following two +functions and then either add them to your C library or link them into +Samba. Put the following in the file <filename>setegid.s</filename>: +</para> + +<para><programlisting> + .globl _setegid +_setegid: + moveq #47,d0 + movl #100,a0 + moveq #1,d1 + movl 4(sp),a1 + trap #9 + bccs 1$ + jmp cerror +1$: + clrl d0 + rts +</programlisting></para> + +<para> +Put this in the file <filename>seteuid.s</filename>: +</para> + +<para><programlisting> + .globl _seteuid +_seteuid: + moveq #47,d0 + movl #100,a0 + moveq #0,d1 + movl 4(sp),a1 + trap #9 + bccs 1$ + jmp cerror +1$: + clrl d0 + rts +</programlisting></para> + +<para> +After creating the above files, you then assemble them using +</para> + +<screen> +&prompt;<userinput>as seteuid.s</userinput> +&prompt;<userinput>as setegid.s</userinput> +</screen> + +<para> +that should produce the files <filename>seteuid.o</filename> and +<filename>setegid.o</filename> +</para> + +<para> +Then you need to add these to the LIBSM line in the DNIX section of +the Samba Makefile. Your LIBSM line will then look something like this: +</para> + +<para><programlisting> +LIBSM = setegid.o seteuid.o -ln +</programlisting></para> + +<para> +You should then remove the line: +</para> + +<para><programlisting> +#define NO_EID +</programlisting></para> + +<para>from the DNIX section of <filename>includes.h</filename>.</para> + +</sect1> + +<sect1> +<title>Red Hat Linux</title> + +<para> +By default during installation, some versions of Red Hat Linux add an +entry to <filename>/etc/hosts</filename> as follows: +<programlisting> + 127.0.0.1 loopback "hostname"."domainname" +</programlisting> +</para> + +<para> +This causes Samba to loop back onto the loopback interface. +The result is that Samba fails to communicate correctly with +the world and therefore may fail to correctly negotiate who +is the master browse list holder and who is the master browser. +</para> + +<para> +Corrective Action: Delete the entry after the word "loopback" +in the line starting 127.0.0.1. +</para> +</sect1> + +<sect1> +<title>AIX</title> +<sect2> +<title>Sequential Read Ahead</title> +<!-- From an email by William Jojo <jojowil@hvcc.edu> --> +<para> +Disabling Sequential Read Ahead using <userinput>vmtune -r 0</userinput> improves +Samba performance significantly. +</para> +</sect2> +</sect1> + +<sect1> +<title>Solaris</title> + +<sect2> +<title>Locking Improvements</title> + +<para>Some people have been experiencing problems with F_SETLKW64/fcntl +when running Samba on Solaris. The built-in file locking mechanism was +not scalable. Performance would degrade to the point where processes would +get into loops of trying to lock a file. It would try a lock, then fail, +then try again. The lock attempt was failing before the grant was +occurring. So the visible manifestation of this would be a handful of +processes stealing all of the CPU, and when they were truss-ed they would +be stuck if F_SETLKW64 loops. +</para> + +<para> +Sun released patches for Solaris 2.6, 8, and 9. The patch for Solaris 7 +has not been released yet. +</para> + +<para> +The patch revision for 2.6 is 105181-34, for 8 is 108528-19 and for 9 is 112233-04. +</para> + +<para> +After the install of these patches, it is recommended to reconfigure +and rebuild Samba. +</para> + +<para>Thanks to Joe Meslovich for reporting this.</para> + +</sect2> + +<sect2 id="winbind-solaris9"> +<title>Winbind on Solaris 9</title> +<para> +Nsswitch on Solaris 9 refuses to use the Winbind NSS module. This behavior +is fixed by Sun in patch <ulink url="http://sunsolve.sun.com/pub-cgi/findPatch.pl?patchId=112960;rev=14">112960-14</ulink>. +</para> +</sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Printing.xml b/docs/Samba3-HOWTO/TOSHARG-Printing.xml new file mode 100644 index 0000000000..349d64f7f9 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Printing.xml @@ -0,0 +1,3115 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="printing"> + +<chapterinfo> + <author> + <firstname>Kurt</firstname><surname>Pfeifle</surname> + <affiliation> + <orgname> Danka Deutschland GmbH </orgname> + <address><email>kpfeifle@danka.de</email></address> + </affiliation> + </author> + &author.jerry; + &author.jht; + <pubdate>May 31, 2003</pubdate> +</chapterinfo> + +<title>Classical Printing Support</title> + +<sect1> +<title>Features and Benefits</title> + +<para> +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> +A Samba print service may be run on a Stand-alone or 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 +<quote>Point'n'Print</quote> mechanism. Printer installations executed by +<quote>Logon Scripts</quote> are no problem. Administrators can upload and +manage drivers to be used by clients through the familiar <quote>Add Printer +Wizard</quote>. As an additional benefit, driver and printer management may +be run from the command line 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 function is best supported by +the newer Common UNIX Printing System (CUPS) +as the print subsystem underneath the Samba hood. +</para> + +<para> +This chapter deals with the foundations of Samba printing as they +are implemented by the more traditional UNIX (BSD and System V-style) +printing systems. Many things covered in this chapter apply also to CUPS. +If you use CUPS, you may be tempted +to jump to the next chapter but you will certainly miss a few things if +you do. It is recommended that you read this chapter as well as <link +linkend="CUPS-printing">CUPS Printing Support</link>. +</para> + +<note> +<para> +Most of the following examples have been verified on Windows XP +Professional clients. Where this document describes the responses to +commands given, bear in mind that Windows 200x/XP clients are quite +similar, but may differ in minor details. Windows NT is somewhat different +again. +</para> +</note> + +</sect1> + +<sect1> +<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 <quote>middleman.</quote> It takes +print files from Windows (or other SMB) clients and passes them to the real +printing system for further processing, therefore, it needs to communicate with +both sides: the Windows print clients and 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. +</para> + +<para> +This deals with the traditional way of UNIX printing. The next chapter +covers in great detail the more modern <emphasis>Common UNIX Printing +System</emphasis> (CUPS). +</para> + +<important><para>CUPS users, be warned: do not just jump on to the next +chapter. You might miss important information only found here! +</para></important> + +<para> +It is apparent from postings on the Samba mailing list that print configuration +is one of the most problematic aspects of Samba administration today. Many +new Samba administrators have the impression that Samba performs some sort +of print processing. Rest assured, Samba does not perform any type of print +processing. It does not do any form of print filtering. +</para> + +<para> +Samba obtains from its clients a data stream (print job) that it spools to a +local spool area. When the entire print job has been received, Samba invokes +a local UNIX/Linux print command and passes the spooled file to it. It is +up to the local system printing subsystems to correctly process the print +job and to submit it to the printer. +</para> + +<sect2> +<title>Client to Samba Print Job Processing</title> + +<para> +Successful printing from a Windows client via a Samba print server to a UNIX +printer involves six (potentially seven) stages: +</para> + +<orderedlist> +<listitem><para>Windows opens a connection to the printer share.</para></listitem> + +<listitem><para>Samba must authenticate the user.</para></listitem> + +<listitem><para>Windows sends a copy of the print file over the network +into Samba's spooling area.</para></listitem> + +<listitem><para>Windows closes the connection.</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 print file may need to be explicitly deleted +from the Samba spooling area. This item depends on your print spooler +configuration settings.</para></listitem> + +</orderedlist> +</sect2> + +<sect2> +<title>Printing Related Configuration Parameters</title> + +<para> +There are a number of configuration parameters to control Samba's +printing behavior. Please refer to the man page for &smb.conf; for an +overview of 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> + +<variablelist> + <varlistentry><term>Global Parameters</term> + <listitem><para> These <emphasis>may not</emphasis> go into + individual share definitions. If they go in by error, + the <command>testparm</command> utility can discover this + (if you run it) and tell you so. + </para></listitem> + </varlistentry> + + <varlistentry><term>Service Level Parameters</term> + <listitem><para> These may be specified in the + <smbconfsection name="[global]"/> section of &smb.conf;. + In this case they define the default behavior of all individual + or service level shares (provided they do not have a different + setting defined for the same parameter, thus overriding the + global default). + </para></listitem> + </varlistentry> +</variablelist> +</sect2> + +</sect1> + +<sect1> +<title>Simple Print Configuration</title> + +<para> +<link linkend="simpleprc">Following example</link> shows a simple printing configuration. +If you compare this with your own, you may find +additional parameters that have been pre-configured by your OS +vendor. Below is a discussion and explanation of the +parameters. This example does not use many parameters. +However, in many environments these are enough to provide a valid +&smb.conf; file that enables all clients to print. +</para> + +<para> +<smbconfexample id="simpleprc"> +<title>Simple configuration with BSD printing</title> +<smbconfsection name="[global]"/> +<smbconfoption name="printing">bsd</smbconfoption> +<smbconfoption name="load printers">yes</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="printable">yes</smbconfoption> +<smbconfoption name="public">yes</smbconfoption> +<smbconfoption name="writable">no</smbconfoption> +</smbconfexample></para> + +<para> +This is only an example configuration. Samba assigns default values to +all configuration parameters. The defaults are conservative +and sensible. When a parameter is specified in the &smb.conf; file, this +overwrites the default value. The <command>testparm</command> utility when +run as root is capable of reporting all setting, both default as well as +&smb.conf; file settings. <command>Testparm</command> gives warnings for all +mis-configured settings. The complete output is easily 340 lines and more, +so 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 is not very picky about its syntax. As has been explained +elsewhere in this document, Samba tolerates some spelling errors (such +as <smbconfoption name="browseable"/> instead of +<smbconfoption name="browseable"/>), and spelling is +case-insensitive. It is permissible to use <parameter>Yes/No</parameter> +or <parameter>True/False</parameter> for Boolean settings. Lists of names +may be separated by commas, spaces or tabs. +</para> + +<sect2> +<title>Verifying Configuration 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. This command greps +for all occurrences of <constant>lp, print, spool, driver, ports</constant> +and <constant>[</constant> in testparms output. This provides a convenient +overview of the running <command>smbd</command> print configuration. This +command does not show individually created printer shares or the spooling +paths they may use. Here is the output of my Samba setup, with settings +shown in <link linkend="simpleprc">the example above</link>: +</para> + +<para><screen> +&rootprompt;<userinput>testparm -s -v | egrep "(lp|print|spool|driver|ports|\[)"</userinput> + Load smb config files from /etc/samba/smb.conf + Processing section "[homes]" + Processing section "[printers]" + + [global] + smb ports = 445 139 + lpq cache time = 10 + 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 behavior. <emphasis>Remember: it may +be important in your future dealings with Samba.</emphasis> +</para> + +<note><para> testparm in Samba-3 behaves differently from that in 2.2.x: used +without the <quote>-v</quote> switch it only shows you the settings actually +written into! To see the complete +configuration used, add the <quote>-v</quote> parameter to testparm.</para></note> + +</sect2> + +<sect2> +<title>Rapid Configuration Validation</title> + +<para> +Should you need to troubleshoot at any stage, please always come back +to this point first and verify if <command>testparm</command> shows the parameters you +expect. To give you a warning from personal experience, +try to just comment out the <smbconfoption name="load printers"/> +parameter. If your 2.2.x system behaves like mine, you'll see this: +</para> + +<para><screen> +&rootprompt;grep "load printers" /etc/samba/smb.conf + # load printers = Yes + # This setting is commented out!! + +&rootprompt;testparm -v /etc/samba/smb.conf | egrep "(load printers)" + load printers = Yes +</screen></para> + +<para> +I assumed that commenting out of this setting should prevent Samba from +publishing my printers, but it still did. It took some time to figure out +the reason. But I am no longer fooled ... at least not by this. +</para> + +<para><screen> +&rootprompt;<userinput>grep -A1 "load printers" /etc/samba/smb.conf</userinput> + load printers = No + # The above setting is what I want! + # load printers = Yes + # This setting is commented out! + +&rootprompt;<userinput>testparm -s -v smb.conf.simpleprinting | egrep "(load printers)"</userinput> + load printers = No + +</screen></para> + +<para> +Only when the parameter is explicitly set to +<smbconfoption name="load printers">No</smbconfoption> +would Samba conform with my intentions. So, my strong advice is: +</para> + +<itemizedlist> +<listitem><para>Never rely on commented out parameters.</para></listitem> + +<listitem><para>Always set parameters explicitly as you intend them to +behave.</para></listitem> + +<listitem><para>Use <command>testparm</command> to uncover hidden +settings that might not reflect your intentions.</para></listitem> + +</itemizedlist> + +<para> +The following is the most minimal configuration file: +<screen> +&rootprompt;<userinput>cat /etc/samba/smb.conf-minimal</userinput> + [printers] +</screen></para> + +<para> +This example should show that you can use testparm to test any Samba +configuration file. Actually, we encourage you <emphasis>not</emphasis> +to change your working system (unless you know exactly what you are +doing). Don't rely on the assumption that changes will only take effect after +you re-start smbd! This is not the case. Samba re-reads it 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. You will now +note a few more interesting things; <command>testparm</command> is useful to +identify what the Samba print configuration would be if you used this minimalistic +configuration. Here is what you can expect to find: +</para> + +<para><screen> +&rootprompt;<userinput>testparm -v smb.conf-minimal | egrep "(print|lpq|spool|driver|ports|[)"</userinput> + Processing section "[printers]" + WARNING: [printers] service MUST be printable! + No path in service printers - using /tmp + + lpq cache time = 10 + 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> +testparm issued two warnings: +</para> + +<itemizedlist> + <listitem><para>We did not specify the <smbconfsection name="[printers]"/> section as printable.</para></listitem> + <listitem><para>We did not tell Samba which spool directory to use.</para></listitem> +</itemizedlist> + +<para> +However, this was not fatal and Samba will default to values that will +work. Please, do not rely on this and do not use this example. This was +included to encourage you to be careful to design and specify your setup to do +precisely what you require. The outcome on your system may vary for some +parameters given, since Samba may have been built with different compile-time +options. <emphasis>Warning:</emphasis> do not put a comment sign +<emphasis>at the end</emphasis> of a valid 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 versions. But the man page clearly says: +<quote>Internal whitespace in a parameter value is retained verbatim.</quote> +This means that a line consisting of, for example: +</para> + +<para><smbconfblock> +<smbconfcomment>This defines LPRng as the printing system</smbconfcomment> +<smbconfoption name="printing"> lprng</smbconfoption> +</smbconfblock></para> + +<para> +will regard the whole of the string after the +<quote><constant>=</constant></quote> sign as the value you want to +define. This is an invalid value that will be ignored and a default +value will be +used in its place. +</para> +</sect2> +</sect1> + +<sect1> +<title>Extended Printing Configuration</title> + +<para> +<link linkend="extbsdpr">Next configuration</link> shows a more verbose example configuration +for print-related settings in a BSD-style printing environment. What follows +is a discussion and explanation of the various parameters. We chose to +use BSD-style printing here because it is still the most commonly used +system on legacy UNIX/Linux installations. New installations predominantly +use CUPS, which is discussed in a separate chapter. The example explicitly +names many parameters that do not need to be specified because they are set +by default. You could use a much leaner &smb.conf; file. Alternately, you can use +<command>testparm</command> or <command>SWAT</command> to optimize the &smb.conf; +file to remove all parameters that are set at default. +</para> + +<para><smbconfexample id="extbsdpr"> + <title>Extended BSD Printing Configuration</title> +<smbconfsection name="[global]"/> +<smbconfoption name="printing">bsd</smbconfoption> +<smbconfoption name="load printers">yes</smbconfoption> +<smbconfoption name="show add printer wizard">yes</smbconfoption> +<smbconfoption name="printcap name">/etc/printcap</smbconfoption> +<smbconfoption name="printer admin">@ntadmin, root</smbconfoption> +<smbconfoption name="max print jobs">100</smbconfoption> +<smbconfoption name="lpq cache time">20</smbconfoption> +<smbconfoption name="use client driver">no</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="printable">yes</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="browseable">no</smbconfoption> +<smbconfoption name="guest ok">yes</smbconfoption> +<smbconfoption name="public">yes</smbconfoption> +<smbconfoption name="read only">yes</smbconfoption> +<smbconfoption name="writable">no </smbconfoption> + +<smbconfsection name="[my_printer_name]"/> +<smbconfoption name="comment">Printer with Restricted Access</smbconfoption> +<smbconfoption name="path">/var/spool/samba_my_printer</smbconfoption> +<smbconfoption name="printer admin">kurt</smbconfoption> +<smbconfoption name="browseable">yes</smbconfoption> +<smbconfoption name="printable">yes</smbconfoption> +<smbconfoption name="writable">no</smbconfoption> +<smbconfoption name="hosts allow">0.0.0.0</smbconfoption> +<smbconfoption name="hosts deny">turbo_xp, 10.160.50.23, 10.160.51.60</smbconfoption> +<smbconfoption name="guest ok">no</smbconfoption> +</smbconfexample></para> + +<para> +This is an example configuration. You may not find all the settings that are in +the configuration file that was provided by the OS vendor. Samba configuration +parameters, if not explicitly set default to a sensible value. +To see all settings, as <constant>root</constant> use the <command>testparm</command> +utility. <command>testparm</command> gives warnings for mis-configured settings. +</para> + +<sect2> +<title>Detailed Explanation Settings</title> + +<para> +The following is a discussion of the settings from above shown example. +</para> + +<sect3> +<title>The [global] Section</title> + +<para> +The <smbconfsection name="[global]"/> section is one of four special +sections (along with [<smbconfsection name="[homes]"/>, +<smbconfsection name="[printers]"/> +and <smbconfsection name="[print$]"/>...). The +<smbconfsection name="[global]"/> contains all parameters which apply +to the server as a whole. It is the place for parameters that have only a +global meaning. It may also contain service level parameters that 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 settings and specify other values). +</para> + +<variablelist> + <varlistentry><term><smbconfoption name="printing">bsd </smbconfoption></term> + <listitem><para>Causes Samba to use default print commands + applicable for the BSD (also known as RFC 1179 style or LPR/LPD) printing + system. In general, the <parameter>printing</parameter> 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 <smbconfoption name="print command"/> (and other queue control + commands).</para> + + <caution><para>The <smbconfoption name="printing"/> parameter is + normally a service level parameter. Since it is included here in the + <smbconfsection name="[global]"/> section, it will take effect for all + printer shares that are not defined differently. Samba-3 no longer + supports the SOFTQ printing system.</para></caution> + </listitem></varlistentry> + + <varlistentry><term><smbconfoption name="load printers">yes </smbconfoption></term> + <listitem><para>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 + <smbconfsection name="[printers]"/> section. (The <parameter>load printers + = no</parameter> setting will allow you to specify each UNIX printer + you want to share separately, leaving out some you do not want to be + publicly visible and available).</para> + </listitem></varlistentry> + + <varlistentry><term><smbconfoption name="show add printer wizard">yes </smbconfoption></term> + <listitem><para>Setting is normally enabled by default (even if the parameter is not specified in &smb.conf;). + It causes the <guiicon>Add Printer Wizard</guiicon> icon to appear + in the <guiicon>Printers</guiicon> folder of the Samba host's + share listing (as shown in <guiicon>Network Neighborhood</guiicon> or + by the <command>net view</command> command). To disable it, you need to + explicitly set it to <constant>no</constant> (commenting it out + will not suffice). The <parameter>Add Printer Wizard</parameter> lets you upload printer + drivers to the <smbconfsection name="[print$]"/> share and associate it + with a printer (if the respective queue exists before the + action), or exchange a printer's driver against any other previously + uploaded driver.</para> + </listitem></varlistentry> + + <varlistentry><term><smbconfoption name="max print jobs">100 </smbconfoption></term> + <listitem><para>Sets the upper limit to 100 print jobs + being active on the Samba server at any one time. Should a client + submit a job that 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 zero (the default) means there is + <emphasis>no</emphasis> limit at all. + </para></listitem></varlistentry> + + <varlistentry><term><smbconfoption name="printcap name">/etc/printcap </smbconfoption></term> + <listitem><para>Tells Samba where to look for a list of + available printer names. Where CUPS is used, make sure that a printcap + file is written. This is controlled by the <constant>Printcap</constant> directive in the + <filename>cupsd.conf</filename> file. + </para></listitem></varlistentry> + + <varlistentry><term><smbconfoption name="printer admin">@ntadmin </smbconfoption></term> + <listitem><para>Members of the ntadmin group should be able to add + drivers and set printer properties (<constant>ntadmin</constant> is only an example name, + it needs to be a valid UNIX group name); root is implicitly always a + <smbconfoption name="printer admin"/>. The @ sign precedes group names in the + <filename>/etc/group</filename>. A printer admin can do anything to + printers via the remote administration interfaces offered by MS-RPC + (see below). In larger installations, the <smbconfoption name="printer admin"/> + parameter is normally a per-share parameter. This permits different groups to administer each printer share. + </para></listitem></varlistentry> + + <varlistentry><term><smbconfoption name="lpq cache time">20 </smbconfoption></term> + <listitem><para>Controls the cache time for the results of the + lpq command. It prevents the lpq command being called too often and + reduces the load on a heavily used print server. + </para></listitem></varlistentry> + + <varlistentry><term><smbconfoption name="use client driver">no </smbconfoption></term> + <listitem><para>If set to <constant>yes</constant>, only + takes effect for Windows NT/200x/XP clients (and not for Win 95/98/ME). Its + default value is <constant>No</constant> (or <constant>False</constant>). + It must <emphasis>not</emphasis> be enabled on print shares + (with a <constant>yes</constant> or <constant>true</constant> setting) that + have valid drivers installed on the Samba server. For more detailed + explanations see the &smb.conf; man page. + </para></listitem></varlistentry> +</variablelist> + +</sect3> + +<sect3 id="ptrsect"> +<title>The [printers] Section</title> + +<para> +This is the second special section. If a section with this name appears in +the &smb.conf;, 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 printer name 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 that should +apply as default to all printers. (For more details see the &smb.conf; +man page.) Settings inside this container must be Share Level parameters. +</para> + +<variablelist> + <varlistentry><term><smbconfoption name="comment">All printers </smbconfoption></term> + <listitem><para> + The <smbconfoption name="comment"/> is shown next to the share if + a client queries the server, either via <guiicon>Network Neighborhood</guiicon> or with + the <command>net view</command> command to list available shares. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="printable">yes </smbconfoption></term> + <listitem><para> + The <smbconfsection name="[printers]"/> service <emphasis>must</emphasis> + be declared as printable. If you specify otherwise, smbd will refuse to load at + startup. This parameter allows connected clients to open, write to and submit spool files + into the directory specified with the <smbconfoption name="path"/> + parameter for this service. It is used by Samba to differentiate printer shares from + file shares. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="path">/var/spool/samba </smbconfoption></term> + <listitem><para> + 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 typically points to a directory that is world + writable, with the <quote>sticky</quote> bit set to it. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="browseable">no </smbconfoption></term> + <listitem><para> + Is always set to <constant>no</constant> if + <smbconfoption name="printable">yes</smbconfoption>. It makes + the <smbconfsection name="[printer]"/> share itself invisible in the list of + available shares in a <command>net view</command> command or in the Explorer browse + list. (You will of course see the individual printers). + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="guest ok">yes </smbconfoption></term> + <listitem><para> + If this parameter is set to <constant>yes</constant>, no password is required to + connect to the printer's service. Access will be granted with the privileges of the + <smbconfoption name="guest account"/>. On many systems the guest + account will map to a user named <quote>nobody</quote>. This user will usually be found + in the UNIX passwd file with an empty password, but with no valid UNIX login. (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 <command>su - guest</command> and run a system + print command like: + </para> + + <para> + <userinput>lpr -P printername /etc/motd</userinput> + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="public">yes </smbconfoption></term> + <listitem><para> + Is a synonym for <smbconfoption name="guest ok">yes</smbconfoption>. + Since we have <smbconfoption name="guest ok">yes</smbconfoption>, it + really does not need to be here. (This leads to the interesting question: <quote>What if I + by accident have two contradictory settings for the same share?</quote> The answer is the + last one encountered by Samba wins. Testparm does not complain about different settings + of the same parameter for the same share. You can test this by setting up multiple + lines for the <parameter>guest account</parameter> parameter with different usernames, + and then run testparm to see which one is actually used by Samba.) + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="read only">yes </smbconfoption></term> + <listitem><para> + Normally (for other types of shares) prevents users from creating or modifying files + in the service's directory. However, in a <quote>printable</quote> 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 permitted. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="writable">no </smbconfoption></term> + <listitem><para> + Is a synonym for <smbconfoption name="read only">yes</smbconfoption>. + </para></listitem> + </varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>Any [my_printer_name] Section</title> + +<para> +If a section appears in the &smb.conf; file, which when given the parameter +<smbconfoption name="printable">yes</smbconfoption> causes Samba to configure it +as a printer share. Windows 9x/Me clients may have problems with connecting or loading printer drivers +if the share name has more than eight characters. Do not name a printer share with a name that may conflict +with an existing user or file share name. On Client connection requests, Samba always tries to find file +shares with that name first. If it finds one, it will connect to this and will not connect +to a printer with the same name! +</para> + +<variablelist> + <varlistentry><term><smbconfoption name="comment">Printer with Restricted Access </smbconfoption></term> + <listitem><para> + The comment says it all. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="path">/var/spool/samba_my_printer </smbconfoption></term> + <listitem><para> + Sets the spooling area for this printer to a directory other than the default. It is not + necessary to set it differently, but the option is available. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="printer admin">kurt </smbconfoption></term> + <listitem><para> + The printer admin definition is different for this explicitly defined printer share from the general + <smbconfsection name="[printers]"/> share. It is not a requirement; we + did it to show that it is possible. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="browseable">yes </smbconfoption></term> + <listitem><para> + This makes the printer browseable so the clients may conveniently find it when browsing the + <guiicon>Network Neighborhood</guiicon>. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="printable">yes </smbconfoption></term> + <listitem><para> + See <link linkend="ptrsect">The [printers] Section</link>. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="writable">no </smbconfoption></term> + <listitem><para> + See <link linkend="ptrsect">The [printers] Section</link>. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="hosts allow">10.160.50.,10.160.51. </smbconfoption></term> + <listitem><para> + Here we exercise a certain degree of access control by using the <smbconfoption name="hosts allow"/> and <smbconfoption name="hosts deny"/> + parameters. 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><smbconfoption name="hosts deny">turbo_xp,10.160.50.23,10.160.51.60 </smbconfoption></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><smbconfoption name="guest ok">no </smbconfoption></term> + <listitem><para> + This printer is not open for the guest account. + </para></listitem> + </varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>Print Commands</title> + +<para> +In each section defining a printer (or in the <smbconfsection name="[printers]"/> section), +a <parameter>print command</parameter> parameter may be defined. It sets a command to process the files +that have been placed into the Samba print spool directory for that printer. (That spool directory was, +if you remember, set up with the <smbconfoption name="path"/> 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 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> +</sect3> + +<sect3> +<title>Default UNIX System Printing Commands</title> + +<para> +You learned earlier on that Samba, in most cases, uses its built-in settings for many parameters +if it cannot find an explicitly stated one in its configuration file. The same is true for the +<smbconfoption name="print command"/>. The default print command varies depending +on the <smbconfoption name="printing"/> 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>, and so on. These letters stand for printer name, spool-file and job ID, respectively. +They are explained in more detail further below. <link linkend="printOptions">Next table</link> presents an overview of key +printing options but excludes the special case of CUPS that is discussed in <link linkend="CUPS-printing">CUPS Printing Support</link>. +</para> + +<table frame='all' id="printOptions"> + <title>Default Printing Settings</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec align="left"/> + <colspec align="left"/> + <thead> + <row> + <entry>Setting</entry> + <entry>Default Printing Commands</entry> + </row> + </thead> + <tbody> + <row> + <entry><smbconfoption name="printing">bsd|aix|lprng|plp</smbconfoption></entry> + <entry>print command is <command>lpr -r -P%p %s</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">sysv|hpux</smbconfoption></entry> + <entry>print command is <command>lp -c -P%p %s; rm %s</command></entry> + </row> + <row> + <entry> <smbconfoption name="printing">qnx</smbconfoption></entry> + <entry>print command is <command>lp -r -P%p -s %s</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">bsd|aix|lprng|plp</smbconfoption></entry> + <entry>lpq command is <command>lpq -P%p</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">sysv|hpux</smbconfoption></entry> + <entry>lpq command is <command>lpstat -o%p</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">qnx</smbconfoption></entry> + <entry>lpq command is <command>lpq -P%p</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">bsd|aix|lprng|plp</smbconfoption></entry> + <entry>lprm command is <command>lprm -P%p %j</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">sysv|hpux</smbconfoption></entry> + <entry>lprm command is <command>cancel %p-%j</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">qnx</smbconfoption></entry> + <entry>lprm command is <command>cancel %p-%j</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">bsd|aix|lprng|plp</smbconfoption></entry> + <entry>lppause command is <command>lp -i %p-%j -H hold</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">sysv|hpux</smbconfoption></entry> + <entry>lppause command (...is empty)</entry> + </row> + <row> + <entry><smbconfoption name="printing">qnx</smbconfoption></entry> + <entry>lppause command (...is empty)</entry> + </row> + <row> + <entry><smbconfoption name="printing">bsd|aix|lprng|plp</smbconfoption></entry> + <entry>lpresume command is <command>lp -i %p-%j -H resume</command></entry> + </row> + <row> + <entry><smbconfoption name="printing">sysv|hpux</smbconfoption></entry> + <entry>lpresume command (...is empty)</entry> + </row> + <row> + <entry><smbconfoption name="printing">qnx</smbconfoption></entry> + <entry>lpresume command (...is empty)</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +We excluded the special case of CUPS here, because it is discussed in the next chapter. For +<parameter>printing = CUPS</parameter>, if Samba is compiled against libcups, it uses the CUPS API to submit +jobs. (It is a good idea also to set <smbconfoption name="printcap">cups</smbconfoption> +in case your <filename>cupsd.conf</filename> is set to write its auto-generated 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> + +</sect3> + +<sect3> +<title>Custom Print Commands</title> + +<para> +After a print job has finished spooling to a service, the <smbconfoption name="print command"/> + 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 may not remove the spool +file on its own. So whatever command you specify, 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 do not wish to roll your own, you should be well informed about the default +built-in commands that Samba uses for each printing subsystem (see +Table 17.1). 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><parameter>%s, %f</parameter> &smbmdash; the path to the spool file name.</para></listitem> + <listitem><para><parameter>%p</parameter> &smbmdash; the appropriate printer name.</para></listitem> + <listitem><para><parameter>%J</parameter> &smbmdash; the job name as transmitted by the client.</para></listitem> + <listitem><para><parameter>%c</parameter> &smbmdash; the number of printed pages of the spooled job (if known).</para></listitem> + <listitem><para><parameter>%z</parameter> &smbmdash; the size of the spooled print job (in bytes).</para></listitem> +</itemizedlist> + +<para> +The print command must contain at least one occurrence of <parameter>%s</parameter> or +the <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> +If specified in the <smbconfsection name="[global]"/> 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! Most importantly, print files will not be removed, so they will consume disk space. +</para> + +<para> +Printing may fail on some UNIX systems when using the <quote>nobody</quote> account. If this happens, create an +alternative guest account and give it the privilege to print. Set up this guest account in the +<smbconfsection name="[global]"/> 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 the Samba print command is <parameter>%$variable</parameter>.) To give you a working +<smbconfoption name="print command"/> example, the following will log a print job +to <filename>/tmp/print.log</filename>, print the file, then remove it. The semicolon (<quote>;</quote> +is the usual separator for commands in shell scripts: +</para> + +<para><smbconfblock> + <smbconfoption name="print command">echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s</smbconfoption> +</smbconfblock></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 <smbconfoption name="print command"/> +parameter varies depending on the setting of the <smbconfoption name="printing"/> +parameter. Another example is: +</para> + +<para><smbconfblock> +<smbconfoption name="print command">/usr/local/samba/bin/myprintscript %p %s</smbconfoption> +</smbconfblock></para> +</sect3> +</sect2> +</sect1> + +<sect1> +<title>Printing Developments Since Samba-2.2</title> + +<para> +Prior to Samba-2.2.x, print server support for Windows clients was limited to <emphasis>LanMan</emphasis> +printing calls. This is the same protocol level as Windows 9x/Me 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 <ulink url="http://imprints.sourceforge.net/">Imprints</ulink> tool set. + </para></listitem> + + <listitem><para> + Support for the native MS-RPC printing calls such as + StartDocPrinter, EnumJobs(), and so on. (See the + <ulink url="http://msdn.microsoft.com/">MSDN documentation</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> +A benefit of updating is that Samba-3 is able to publish its printers to Active Directory (or LDAP). +</para> + +<para> +A fundamental difference exists between MS Windows NT print servers and Samba operation. Windows NT +permits the installation of local printers that are not shared. This is an artifact of the fact that +any Windows NT machine (server or client) may be used by a user as a workstation. Samba will publish all +printers that are made available, either by default or by specific declaration via printer-specific shares. +</para> + +<para> +Windows NT/200x/XP Professional clients do not have to use the standard SMB printer share; they can +print directly to any printer on another Windows NT host using MS-RPC. This, of course, assumes that +the client has the necessary privileges on the remote host that serves the printer resource. 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 Windows 9x/Me can only print to shared +printers). +</para> + +<sect2> +<title>Point'n'Print Client Drivers on Samba Servers</title> + +<para> +There is much confusion about what all this means. The question is often asked, <quote>Is it or is +it not necessary for printer drivers to be installed on a Samba host in order to support printing from +Windows clients?</quote> The answer to this is no, it is not necessary. +</para> + +<para> +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 used by Windows 9x/Me +clients. (However, a <emphasis>bug</emphasis> existed in Samba 2.2.0 that 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> +But it is a new capability to install the printer drivers into the <smbconfsection name="[print$]"/> +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 +<smbconfsection name="[print$]"/> 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/200x/XP Professional client (this does not work from 95/98/ME clients). + </para></listitem> + + <listitem><para> + Using the <emphasis>Imprints</emphasis> tool-set. + </para></listitem> + + <listitem><para> + Using the <emphasis>smbclient</emphasis> and <emphasis>rpcclient</emphasis> command-line tools. + </para></listitem> + + <listitem><para> + Using <emphasis>cupsaddsmb</emphasis> (only works for the CUPS + printing system, not for LPR/LPD, LPRng, and so on). + </para></listitem> +</itemizedlist> + +<para> +Samba does not use these uploaded drivers in any way to process spooled files. These drivers are utilized +entirely by the clients who download and install them via the <quote>Point'n'Print</quote> 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, as needed. +</para> +</sect2> + +<sect2> +<title>The Obsoleted [printer$] Section</title> + + <para> + Versions of Samba prior to 2.2 made it possible to use a share named + <parameter>[printer$]</parameter>. This name was taken from the same named service created by + Windows 9x/Me clients when a printer was shared by them. Windows 9x/Me printer servers always + have a <smbconfsection name="[printer$]"/> service that provides read-only access (with + no password required) 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. + </para> + + <para> + These parameters, including the <parameter>printer driver file</parameter> parameter, + are now removed and cannot be used in installations of Samba-3. The share name + <smbconfsection name="[print$]"/> is now used for the location of download-able printer + drivers. It is taken from the <smbconfsection name="[print$]"/> service created + by Windows NT PCs when a printer is shared by them. Windows NT print servers always have a + <smbconfsection name="[print$]"/> service that provides read-write access (in the context + of its ACLs) to support printer driver downloads and uploads. This does not mean Windows + 9x/Me clients are now thrown aside. They can use Samba's <smbconfsection name="[print$]"/> + share support just fine. + </para> +</sect2> + +<sect2> +<title>Creating the [print$] Share</title> + +<para> +In order to support the uploading and downloading of printer driver files, you must first configure a +file share named <smbconfsection name="[print$]"/>. The public name of this share is hard coded +in the MS Windows clients. 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> + +<para> +You should modify the server's file to add the global parameters and create the +<smbconfsection name="[print$]"/> file share (of course, some of the parameter values, such +as <smbconfoption name="path"/> are arbitrary and should be replaced with appropriate values for your +site). See <link linkend="prtdollar">next example</link>. +</para> + +<para> +<smbconfexample id="prtdollar"> +<title>[print\$] example</title> +<smbconfsection name="[global]"/> +<smbconfcomment>members of the ntadmin group should be able to add drivers and set</smbconfcomment> +<smbconfcomment>printer properties. root is implicitly always a 'printer admin'.</smbconfcomment> +<smbconfoption name="printer admin">@ntadmin</smbconfoption> +<member>...</member> +<smbconfsection name="[printers]"/> +<member>...</member> +<smbconfsection name="[print$]"/> +<smbconfoption name="comment">Printer Driver Download Area</smbconfoption> +<smbconfoption name="path">/etc/samba/drivers</smbconfoption> +<smbconfoption name="browseable">yes</smbconfoption> +<smbconfoption name="guest ok">yes</smbconfoption> +<smbconfoption name="read only">yes</smbconfoption> +<smbconfoption name="write list">@ntadmin, root</smbconfoption> +</smbconfexample> +</para> + +<para> +Of course, you also need to ensure that the directory named by the +<smbconfoption name="path"/> parameter exists on the UNIX file system. +</para> + +</sect2> + +<sect2> +<title>[print$] Section Parameters</title> + +<para> +The <smbconfsection name="[print$]"/> is a special section in &smb.conf;. It contains settings relevant to +potential printer driver download and is used by windows clients for local print driver installation. +The following parameters are frequently needed in this share section: +</para> + +<variablelist> + <varlistentry><term><smbconfoption name="comment">Printer Driver Download Area </smbconfoption></term> + <listitem><para> + The comment appears next to the share name if it is listed in a share list (usually Windows + clients will not see it, but it will also appear up in a <command>smbclient -L sambaserver + </command> output). + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="path">/etc/samba/printers </smbconfoption></term> + <listitem><para> + Is the path to the location of the Windows driver file deposit from the UNIX point of view. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="browseable">no </smbconfoption></term> + <listitem><para> + Makes the <smbconfsection name="[print$]"/> share invisible to clients from the + <guimenu>Network Neighborhood</guimenu>. 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 + <guimenu>Connect network drive menu></guimenu> from Windows Explorer. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="guest ok">yes </smbconfoption></term> + <listitem><para> + Gives read-only access to this share for all guest users. Access may be granted to + download and install printer drivers on clients. The requirement for <parameter>guest ok + = yes</parameter> depends on 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> + 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 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 print without worrying about silly accounts and security, then configure the share for + guest access. You should consider adding <smbconfoption name="map to guest">Bad User</smbconfoption> in the <smbconfsection name="[global]"/> section + as well. Make sure you understand what this parameter does before using it. + </para></note> + </listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="read only">yes </smbconfoption></term> + <listitem><para> + Because we do not want everybody to upload driver files (or even change driver settings), + we tagged this share as not writable. + </para></listitem> + </varlistentry> + + <varlistentry><term><smbconfoption name="write list">@ntadmin, root </smbconfoption></term> + <listitem><para> + The <smbconfsection name="[print$]"/> was made read-only by the previous + setting so we should create a <parameter>write list</parameter> entry also. UNIX + groups (denoted with a leading <quote>@</quote> character). 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 + account 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 <smbconfoption name="printer admin"/> + parameter. See the &smb.conf; man page for more information on configuring file shares. + </para></listitem> + </varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title>The [print$] Share Directory</title> + +<para> +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 <smbconfsection name="[print$]"/> +service (i.e., the UNIX directory named by the <smbconfoption name="path"/> +parameter). These correspond to each of the supported client architectures. Samba follows this model as +well. Just like the name of the <smbconfsection name="[print$]"/> share itself, the subdirectories +must be exactly the names listed below (you may leave out the subdirectories of architectures you do +not need to support). +</para> + +<para> +Therefore, create a directory tree below the +<smbconfsection name="[print$]"/> share for each architecture you wish +to support like this: +</para> + +<para><programlisting> +[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 +</programlisting> +</para> + +<important><title>Required permissions</title> + <para> + In order to add a new driver to your Samba host, one of two conditions must hold true: + </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 have write access to add files to the subdirectories beneath + <smbconfsection name="[print$]"/>. Remember that all file shares are set to <quote>read-only</quote> by default. + </para> +</important> + +<para> +Once you have created the required <smbconfsection name="[print$]"/> service and +associated subdirectories, go to a Windows NT 4.0/200x/XP client workstation. Open <guiicon>Network +Neighborhood</guiicon> or <guiicon>My Network Places</guiicon> and browse for the Samba host. Once you +have located the server, navigate to its <guiicon>Printers and Faxes</guiicon> 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> +Have you successfully created the <smbconfsection name="[print$]"/> share in &smb.conf;, and have your forced Samba +to re-read its &smb.conf; file? Good. But you are not yet ready to use the new facility. The client driver +files need to be installed into this share. So far it is still an empty share. Unfortunately, it is +not enough to just copy the driver files over. They need to be +correctly installed so that appropriate +records for each driver will exist in the Samba internal databases so it can provide the correct +drivers as they are requested from MS Windows clients. And that is a bit tricky, to say the least. We +now discuss two alternative ways to install the drivers into <smbconfsection name="[print$]"/>: +</para> + +<itemizedlist> + <listitem><para> + Using the Samba command-line 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 (<guiicon>Printer Properties</guiicon> and <guiicon>Add Printer Wizard</guiicon>) + from any Windows NT/200x/XP client workstation. + </para></listitem> +</itemizedlist> + +<para> +The latter option is probably the easier one (even if the process may seem a little bit weird at first). +</para> + +<sect2> +<title>Add Printer Wizard Driver Installation</title> + +<para> +The initial listing of printers in the Samba host's <guiicon>Printers</guiicon> folder accessed from a +client's Explorer will have no real printer driver assigned to them. By default this driver name is set +to a null string. This must be changed now. The local <guiicon>Add Printer Wizard</guiicon> (APW), run from +NT/2000/XP clients, will help us in this task. +</para> + +<para> +Installation of a valid printer driver is not straightforward. You must attempt +to view the printer properties for the printer to which you want the driver assigned. Open the Windows +Explorer, open <guiicon>Network Neighborhood</guiicon>, browse to the Samba host, open Samba's <guiicon>Printers</guiicon> +folder, right-click on the printer icon and select <guimenu>Properties...</guimenu>. You are now trying to +view printer and driver properties for a queue that has this default <constant>NULL</constant> driver +assigned. This will result in the following error message: +</para> + + <para><errorname> + 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? + </errorname></para> + +<para> +Do not click on <guibutton>Yes</guibutton>! Instead, click on <guibutton>No</guibutton> 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 now have the choice of: +</para> + +<itemizedlist> + <listitem><para> + Select a driver from the pop-up list of installed drivers. Initially this list will be empty. + </para></listitem> + + <listitem><para> + Click on <guibutton>New Driver</guibutton> to install a new printer driver (which will + start up the APW). + </para></listitem> +</itemizedlist> + +<para> +Once the APW is started, the procedure is exactly the same as the one you are familiar with in Windows (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 <smbconfoption name="printer admin"/> +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 <application>Windows NT x86</application>, +you will need to use the <guilabel>Sharing</guilabel> tab of the printer properties dialog. +</para> + +<para> +Assuming you have connected with an administrative (or root) account (as named by the +<smbconfoption name="printer admin"/> 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 in <link linkend="inst-rpc">Installing Print Drivers Using <command>rpcclient</command></link>. +</para> +</sect2> + +<sect2 id="inst-rpc"> +<title>Installing Print Drivers Using <command>rpcclient</command></title> + +<para> +The second way to install printer drivers into <smbconfsection name="[print$]"/> and set them +up in a valid way is to do it from the UNIX command line. This involves four distinct steps: +</para> + +<orderedlist> + <listitem><para> + Gather info about required driver files and collect the files. + </para></listitem> + + <listitem><para> + Deposit the driver files into the <smbconfsection name="[print$]"/> share's correct subdirectories + (possibly by using <command>smbclient</command>). + </para></listitem> + + <listitem><para> + Run the <command>rpcclient</command> command line utility once with the <command>adddriver</command> + subcommand. + </para></listitem> + + <listitem><para> + Run <command>rpcclient</command> a second time with the <command>setdriver</command> subcommand. + </para></listitem> +</orderedlist> + +<para> +We provide detailed hints for each of these steps in the paragraphs that follow. +</para> + +<sect3> +<title>Identifying Driver Files</title> + +<para> +To find out about the driver files, you have two options. You could check the contents of the driver +CDROM that came with your printer. Study the <filename>*.inf</filename> files lcoated on the CDROM. This +may not be possible, since the <filename>*.inf</filename> file might be missing. Unfortunately, vendors have now started +to use their own installation programs. These installations packages are often in some Windows platform +archive format. Additionally, the files may be re-named during the installation process. This makes it +extremely difficult to identify the driver files required. +</para> + +<para> +Then you only have the second option. Install the driver locally on a Windows client and +investigate which file names and paths it uses after they are installed. (You need to repeat +this procedure for every client platform you want to support. We show it here for the +<application>W32X86</application> platform only, a name used by Microsoft for all Windows NT/200x/XP +clients.) +</para> + +<para> +A good method to recognize the driver files is to print the test page from the driver's +<guilabel>Properties</guilabel> dialog (<guilabel>General</guilabel> 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 +<guilabel>Driver File</guilabel>, <guilabel>Data File</guilabel>, <guilabel>Config File</guilabel>, +<guilabel>Help File</guilabel> and (optionally) the <guilabel>Dependent Driver Files</guilabel> +(this may vary slightly for Windows NT). You need to take a note of all file names 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 at the <filename>3</filename> info 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). I installed the driver locally to TURBO_XP, from a Samba server called <constant>KDE-BITSHOP</constant>. +We could run an interactive <command>rpcclient</command> session; then we would get an +<command>rpcclient /></command> 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 <option>-c</option> +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> +&rootprompt;<userinput>rpcclient -U'Danka%xxxx' -c \ + 'getdriver "Heidelberg Digimaster 9110 (PS)" 3' TURBO_XP</userinput> +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\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\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 large number of <guilabel>Dependent files</guilabel> +(there are worse cases, however). Also, strangely, the +<guilabel>Driver File</guilabel> is tagged here +<guilabel>Driver Path</guilabel>. We do not yet have support for the so-called +<application>WIN40</application> architecture installed. This name is used by Microsoft for the Windows +9x/Me platforms. If we want to support these, we need to install the Windows 9x/Me driver files in +addition to those for <application>W32X86</application> (i.e., the Windows NT72000/XP clients) onto a +Windows PC. This PC can also host the Windows 9x/Me drivers, even if it runs on Windows NT, 2000 or XP. +</para> + +<para> +Since the <smbconfsection name="[print$]"/> share is usually accessible through the <guiicon>Network +Neighborhood</guiicon>, you can also use the UNC notation from Windows Explorer to poke at it. The Windows +9x/Me driver files will end up in subdirectory <filename>0</filename> of the <filename>WIN40</filename> +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 Windows XP are installed into the <quote>3</quote> subdirectory +instead of the <quote>2</quote>. 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 types of drivers install into the <quote>3</quote> subdirectory. +</para></note> +</sect3> + +<sect3> +<title>Obtaining Driver Files from Windows Client [print$] Shares</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 <smbconfsection name="[print$]"/> +share that 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 that were leaked to us by <command>getdriver</command>. The +listing is edited to include line breaks for readability: +</para> + +<para><screen> +&rootprompt;<userinput>smbclient //TURBO_XP/print\$ -U'Danka%xxxx' \ + -c 'cd W32X86/2;mget HD*_de.* hd*ppd Hd*_de.* Hddm*dll HDN*Aux.DLL'</userinput> + +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] +<prompt>Get file Hddm91c1_de.ABD? </prompt><userinput>n</userinput> +<prompt>Get file Hddm91c1_de.def? </prompt><userinput>y</userinput> +getting file \W32X86\2\Hddm91c1_de.def of size 428 as Hddm91c1_de.def +<prompt>Get file Hddm91c1_de.DLL? </prompt><userinput>y</userinput> +getting file \W32X86\2\Hddm91c1_de.DLL of size 876544 as Hddm91c1_de.DLL +[...] +</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 <option>-c</option> 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> +Remember to repeat the procedure for the <application>WIN40</application> architecture should +you need to support Windows 9x/Me/XP clients. Remember too, the files for these architectures are in the +<filename>WIN40/0/</filename> subdirectory. Once this is complete, we can run <command>smbclient ... +put</command> to store the collected files on the Samba server's <smbconfsection name="[print$]"/> +share. +</para> +</sect3> + +<sect3> +<title>Installing Driver Files into [print$]</title> + +<para> +We are now going to locate the driver files into the <smbconfsection name="[print$]"/> +share. Remember, the UNIX path to this share has been defined +previously in your words missing here. You +also have created subdirectories for the different Windows client types you want to +support. Supposing your <smbconfsection name="[print$]"/> 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> but + not (yet) into the <filename>2</filename> subdirectory. + </para></listitem> + + <listitem><para> + For all Windows 95, 98 and ME clients into <filename>/etc/samba/drivers/WIN40/</filename> but not + (yet) into the <filename>0</filename> subdirectory. + </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 <smbconfsection name="[print$]"/> share. +</para> + +<para><screen> +&rootprompt;<userinput>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'</userinput> + +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 +putting file Hddm91c1_de.ppd as \W32X86\Hddm91c1_de.ppd +putting file HDNIS01U_de.DLL as \W32X86\HDNIS01U_de.DLL +putting file HDNIS01U_de.HLP as \W32X86\HDNIS01U_de.HLP +putting file Hddm91c1_de.DLL as \W32X86\Hddm91c1_de.DLL +putting file Hddm91c1_de.INI as \W32X86\Hddm91c1_de.INI +putting file Hddm91c1KMMin.DLL as \W32X86\Hddm91c1KMMin.DLL +putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat +putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat +putting file Hddm91c1_de.def as \W32X86\Hddm91c1_de.def +putting file Hddm91c1_de.hre as \W32X86\Hddm91c1_de.hre +putting file Hddm91c1_de.vnd as \W32X86\Hddm91c1_de.vnd +putting file Hddm91c1_de.hlp as \W32X86\Hddm91c1_de.hlp +putting file Hddm91c1_de_reg.HLP as \W32X86\Hddm91c1_de_reg.HLP +putting file HDNIS01Aux.dll as \W32X86\HDNIS01Aux.dll +putting file HDNIS01_de.NTF as \W32X86\HDNIS01_de.NTF +</screen> + +Whew &smbmdash; that was a lot of typing! Most drivers are a lot smaller &smbmdash; many only having three generic +PostScript driver files plus one PPD. While we did retrieve the files from the <filename>2</filename> +subdirectory of the <filename>W32X86</filename> directory from the Windows box, we do not put them +(for now) in this same subdirectory of the Samba box. This relocation will automatically be done by the +<command>adddriver</command> command, which we will run shortly (and do not forget to also put the files +for the Windows 9x/Me architecture into the <filename>WIN40/</filename> subdirectory should you need them). +</para> +</sect3> + +<sect3> +<title><command>smbclient</command> to Confirm Driver Installation</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): +</para> + +<para><screen> +&rootprompt;<userinput>smbclient //SAMBA-CUPS/print\$ -U 'root%xxxx' \ + -c 'cd W32X86; pwd; dir; cd 2; pwd; dir'</userinput> + 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.8a] + +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> subdirectory (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 does not yet know that +these files are something special, namely <emphasis>printer driver files</emphasis> and it does not know +to which print queue(s) these driver files belong. +</para> +</sect3> + +<sect3> +<title>Running <command>rpcclient</command> with <command>adddriver</command></title> + +<para> +Next, you must tell Samba about the special category of the files you just uploaded into the +<smbconfsection name="[print$]"/> 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> +&rootprompt;<userinput>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</userinput> + +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 +careful when typing the command. Don't exchange the order of the fields. Some changes would lead to +an <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 +provides a more detailed description, should you need it. +</para> +</sect3> + +<sect3> +<title>Checking <command>adddriver</command> Completion</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> +&rootprompt;<userinput>smbclient //SAMBA-CUPS/print\$ -Uroot%xx \ + -c 'cd W32X86;dir;pwd;cd 2;dir;pwd'</userinput> + 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 file size has increased). +</para> +</sect3> + +<sect3> +<title>Check Samba for Driver Recognition</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 not yet associated with a particular printer. We may check the driver +status of the files by at least three methods: +</para> + +<itemizedlist> + <listitem><para> + From any Windows client browse Network Neighborhood, find the Samba host and open the Samba + <guiicon>Printers and Faxes</guiicon> folder. Select any printer icon, right-click and select + the printer <guimenuitem>Properties</guimenuitem>. Click the <guilabel>Advanced</guilabel> + tab. Here is a field indicating the driver for that printer. A drop-down menu allows you to + change that driver (be careful not to do this unwittingly). You can use this list to view + all drivers known to Samba. Your new one should be among them. (Each type of client will only + see his own architecture's list. If you do not have every driver installed for each platform, + the list will differ if you look at it from Windows95/98/ME or Windows NT/2000/XP.) + </para></listitem> + + <listitem><para> + From a Windows 200x/XP client (not Windows NT) browse <guiicon>Network Neighborhood</guiicon>, + search for the Samba server and open the server's <guiicon>Printers</guiicon> folder, + right-click on the white background (with no printer highlighted). Select <guimenuitem>Server + Properties</guimenuitem>. On the <guilabel>Drivers</guilabel> tab you will see the new driver + listed. This view enables you to also inspect the list of files belonging to that driver + (this does not work on Windows NT, but only on Windows 2000 and Windows XP; Windows NT does not + provide the <guimenuitem>Drivers</guimenuitem> tab). An + alternative and 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 <replaceable>SAMBA-CUPS</replaceable>): + </para> + + <para><userinput>rundll32 printui.dll,PrintUIEntry /s /t2 /n\\<replaceable>SAMBA-CUPS</replaceable></userinput></para> + </listitem> + + <listitem><para> + From a UNIX prompt, run this command (or a variant thereof) where + <replaceable>SAMBA-CUPS</replaceable> is the name of the Samba host and xxxx represents the + actual Samba password assigned to root: + </para> + + <para><userinput>rpcclient -U'root%xxxx' -c 'enumdrivers' <replaceable>SAMBA-CUPS</replaceable></userinput></para> + + <para> + You will see a listing of all drivers Samba knows about. Your new one should be among + them. But it is only listed under the <parameter>[Windows NT x86]</parameter> heading, not under + <smbconfsection name="[Windows 4.0]"/>, since you didn't install that part. Or did you? + You will see a listing of all drivers Samba knows about. Your new one should be among them. In + our example it is named <constant>dm9110</constant>. Note that the third column shows the other + installed drivers twice, one time for each supported architecture. Our new driver only shows up + for <application>Windows NT 4.0 or 2000</application>. To have it present for <application>Windows + 95, 98 and ME</application>, you'll have to repeat the whole procedure with the WIN40 architecture + and subdirectory. + </para></listitem> +</itemizedlist> +</sect3> + +<sect3> +<title>Specific Driver Name Flexibility</title> + +<para> +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><screen> +&rootprompt;<userinput>rpcclient -Uroot%xxxx \ + -c 'adddriver "Windows NT x86" \ + "mydrivername: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 + </userinput> + +cmd = adddriver "Windows NT x86" \ + "mydrivername: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 mydrivername successfully installed. +</screen></para> + +<para> +You will be able to bind that driver to any print queue (however, you are responsible that +you associate drivers to queues that make sense with respect to target printers). You cannot run the +<command>rpcclient</command> <command>adddriver</command> command repeatedly. Each run consumes the +files you had put into the <smbconfsection name="[print$]"/> share by moving them into the +respective subdirectories. So you must execute an <command>smbclient ... put</command> command before +each <command>rpcclient ... adddriver</command> command. +</para> +</sect3> + +<sect3> +<title>Running <command>rpcclient</command> with the <command>setdriver</command></title> + +<para> +Samba needs to know which printer owns which driver. Create a mapping of the driver to a printer, and +store this info in Samba's memory, the TDB files. The <command>rpcclient setdriver</command> command +achieves exactly this: +</para> + +<para><screen> +&rootprompt;<userinput>rpcclient -U'root%xxxx' -c 'setdriver dm9110 mydrivername' <replaceable>SAMBA-CUPS</replaceable></userinput> + cmd = setdriver dm9110 mydrivername + +Successfully set dm9110 to driver mydrivername. +</screen></para> + +<para> +Ah, no, I did not want to do that. Repeat, this time with the name I intended: +</para> + +<para><screen> +&rootprompt;<userinput>rpcclient -U'root%xxxx' -c 'setdriver dm9110 dm9110' <replaceable>SAMBA-CUPS</replaceable></userinput> + cmd = setdriver dm9110 dm9110 +Successfully set dm9110 to driver dm9110. +</screen></para> + +<para> +The syntax of the command is: +<screen> +<userinput>rpcclient -U'root%<replaceable>sambapassword</replaceable>' -c 'setdriver <replaceable>printername</replaceable> \ + <replaceable>drivername</replaceable>' <replaceable>SAMBA-Hostname</replaceable></userinput>. +</screen> +Now we have done most of the work, but not all of it. +</para> + +<note><para> +The <command>setdriver</command> command will only succeed if the +printer is already known to Samba. A +bug in 2.2.x prevented Samba from recognizing freshly installed printers. You had to restart Samba, +or at least send an HUP signal to all running smbd processes to work around this: <userinput>kill -HUP +`pidof smbd`</userinput>. +</para></note> +</sect3> +</sect2> +</sect1> + +<sect1> +<title>Client Driver Installation Procedure</title> + +<para> +As Don Quixote said: <quote>The proof of the pudding is 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>First Client Driver Installation</title> + +<para> +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. You should guarantee that your connection is not unwittingly mapped to <emphasis>bad +user</emphasis> nobody. In a DOS box type: +</para> + +<para><userinput>net use \\<replaceable>SAMBA-SERVER</replaceable>\print$ /user:root</userinput></para> + +<para> +Replace root, if needed, by another valid <smbconfoption name="printer admin"/> user as given in +the definition. Should you already be connected as a different user, you will get an error message. There +is no easy way to get rid of that connection, because Windows does not seem to know a concept of logging +off from a share connection (do not confuse this with logging off from the local workstation; that is +a different matter). On Windows NT/2K, you can force a logoff from all smb/cifs connections by restarting the +<quote>workstation</quote> service. You can try to close all Windows file explorer and Internet Explorer for +Windows. As a last resort, you may have to reboot. Make sure there is no automatic reconnection 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> + +<procedure> + <step><para> + Open <guiicon>Network Neighborhood</guiicon>. + </para></step> + + <step><para> + Browse to Samba server. + </para></step> + + <step><para> + Open its <guiicon>Printers and Faxes</guiicon> folder. + </para></step> + + <step><para> + Highlight and right-click on the printer. + </para></step> + + <step><para> + Select <guimenuitem>Connect</guimenuitem> (for Windows NT4/200x + it is possibly <guimenuitem>Install</guimenuitem>). + </para></step> +</procedure> + +<para> +A new printer (named <replaceable>printername</replaceable> on Samba-server) should now have +appeared in your <emphasis>local</emphasis> Printer folder (check <guimenu>Start</guimenu> -- +<guimenuitem>Settings</guimenuitem> -- <guimenuitem>Control Panel</guimenuitem> -- <guiicon>Printers +and Faxes</guiicon>). +</para> + +<para> +Most likely you are now tempted to try to print a test page. After all, you now can open the printer +properties, and on the <guimenu>General</guimenu> tab there is a button offering to do just that. But +chances are that you get an error message saying <errorname>Unable to print Test Page</errorname>. The +reason might be that there is not yet a valid Device Mode set for the driver, or that the <quote>Printer +Driver Data</quote> set is still incomplete. +</para> + +<para> +You must make sure that a valid <parameter>Device Mode</parameter> is set for the +driver. We now explain what that means. +</para> +</sect2> + +<sect2> +<title>Setting Device Modes on New Printers</title> + +<para> +For a printer to be truly usable by a Windows NT/200x/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). + </para></listitem> + + <listitem><para> + A complete set of <emphasis>Printer Driver Data</emphasis> generated by the driver. + </para></listitem> +</itemizedlist> + +<para> +If either 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 it produces a harvest of +error messages when attempting to print. Samba stores the named values and all printing related information 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> +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 (the Samba host) to healthy +values so 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 200x/XP) client, as is discussed +in the following paragraphs. +</para> + +<para> +Be aware that a valid Device Mode can only be initiated by a +<smbconfoption name="printer admin"/>, or root +(the reason should be obvious). Device Modes can only be correctly +set by executing the printer driver program itself. Since Samba cannot 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 automatically generate the Printer Driver Data that is needed when they are uploaded to the +<smbconfsection name="[print$]"/> share with the help of the APW or rpcclient. +</para> + +<para> +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/200x/XP printer properties page from a Window client for this: +</para> + +<procedure> + <step><para> + Browse the <guiicon>Network Neighborhood.</guiicon> + </para></step> + + <step><para> + Find the Samba server. + </para></step> + + <step><para> + Open the Samba server's <guiicon>Printers and Faxes</guiicon> folder. + </para></step> + + <step><para> + Highlight the shared printer in question. + </para></step> + + <step><para> + Right-click on the printer (you may already be here, if you followed the last section's description). + </para></step> + + <step><para> + At the bottom of the context menu select <guimenu>Properties</guimenu> (if the menu still offers the + <guimenuitem>Connect</guimenuitem> entry further above, you + need to click on that one first to achieve the driver + installation as shown in the last section). + </para></step> + + <step><para> + Go to the <guilabel>Advanced</guilabel> tab; click on <guibutton>Printing Defaults</guibutton>. + </para></step> + + <step><para> + Change the <guimenuitem>Portrait</guimenuitem> page setting to <guimenuitem>Landscape</guimenuitem> (and back). + </para></step> + + <step><para> + Make sure to apply changes between swapping the page orientation to cause the change to actually take effect. + </para></step> + + <step><para> + While you are at it, you may 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></step> +</procedure> + +<para> +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> <guiicon>Printers</guiicon> +folder, too, if you are a Samba printer admin user. From now on, printing should work as expected. +</para> + +<para> +Samba 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> + +<sect2> +<title>Additional Client Driver Installation</title> + +<para> +Every additional driver may be installed, along the lines described +above. Browse network, open the +<guiicon>Printers</guiicon> folder on Samba server, right-click on <guiicon>Printer</guiicon> and choose +<guimenuitem>Connect...</guimenuitem>. 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 <guiicon>Printers and Faxes</guiicon> folder. +</para> + +<para> +You can also open your local <guiicon>Printers and Faxes</guiicon> folder by +using this command on Windows 200x/XP Professional workstations: +</para> + +<para><userinput>rundll32 shell32.dll,SHHelpShortcuts_RunDLL PrintersFolder</userinput></para> + +<para> +or this command on Windows NT 4.0 workstations: +</para> + +<para><userinput> +rundll32 shell32.dll,Control_RunDLL MAIN.CPL @2 +</userinput></para> + +<para> +You can enter the commands either inside a <guilabel>DOS box</guilabel> window or in the <guimenuitem>Run +command...</guimenuitem> field from the <guimenu>Start</guimenu> menu. +</para> +</sect2> + +<sect2> +<title>Always Make First Client Connection as root or <quote>printer admin</quote></title> + +<para> +After you installed the driver on the Samba server (in its <smbconfsection name="[print$]"/> +share, you should always make sure that your first client installation completes correctly. Make it a +habit for yourself to build the very first connection from a client as <smbconfoption name="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). + </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 on <guiicon>Apply</guiicon>, and then change it +back again. Next, modify the other settings (for example, you do not want the default media size set to +<guiicon>Letter</guiicon> when you are all using <guiicon>A4</guiicon>, right? You may want to set the +printer for <guiicon>duplex</guiicon> as the default, and so on). +</para> + +<para> +To connect as root to a Samba printer, try this command from a Windows 200x/XP DOS box command prompt: +</para> + +<para><screen> +&dosprompt;<userinput>runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry /p /t3 /n + \\<replaceable>SAMBA-SERVER</replaceable>\<replaceable>printername</replaceable>"</userinput> +</screen> +</para> + +<para> +You will be prompted for root's Samba-password; type it, wait a few +seconds, click on <guibutton>Printing +Defaults</guibutton>, and proceed to set the job options that should be used as defaults by all +clients. Alternately, instead of root you can name one other member of the <smbconfoption name="printer admin"/> from the setting. +</para> + +<para> + Now all the other users downloading and installing the driver the same way <?latex \linebreak ?>(called +<quote>Point'n'Print</quote>) will have the same defaults set for them. If you miss this step +you'll get a lot of Help Desk 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 now ready for Point'n'Print +installation by the clients. You may have tried to download and use it +onto your first client machine, but +wait. Let's make sure you are acquainted first with a few tips and tricks you may find useful. For example, +suppose you did not set the defaults on the printer, as advised in the preceding +paragraphs. 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 will not store it.</quote>) +</para> + +<sect2> +<title>Setting Default Print Options for Client Drivers</title> + +<para> +The last sentence might be viewed with mixed feelings by some users and +Admins. They have struggled for hours and could not arrive at a point +where their settings seemed to be saved. It is not their fault. The confusing +thing is that in the multi-tabbed dialog that pops up when you right-click +on the printer name and select <guimenuitem>Properties</guimenuitem>, you +can arrive at two dialogs that appear identical, 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 not set and save default print options +for all users on Windows 200x/XP. Why not?</quote></title> + +<para> +How are you doing it? I bet the wrong way. (It is not easy to find out, though). There are three different +ways to bring you to a dialog that seems to set everything. All three +dialogs look the same, but only one +of them does what you intend. You need to be Administrator or Print Administrator to do this for all +users. Here is how I reproduce it in an XP Professional: +</para> + +<orderedlist numeration="upperalpha"> + <listitem><para>The first <quote>wrong</quote> way: + <orderedlist numeration="arabic"> + <listitem><para>Open the <guiicon>Printers</guiicon> folder.</para></listitem> + + <listitem><para>Right-click on the printer (<emphasis>remoteprinter on cupshost</emphasis>) and + select in context menu <guimenu>Printing Preferences...</guimenu>.</para></listitem> + + <listitem><para>Look at this dialog closely and remember what it looks like.</para></listitem> + </orderedlist></para></listitem> + + <listitem><para>The second <quote>wrong</quote> way: + <orderedlist numeration="arabic"> + <listitem><para>Open the <guimenu>Printers</guimenu> folder.</para></listitem> + + <listitem><para>Right-click on the printer (<emphasis>remoteprinter on + cupshost</emphasis>) and select in the context menu + <guimenuitem>Properties</guimenuitem></para></listitem> + + <listitem><para>Click on the <guilabel>General</guilabel> + tab.</para></listitem> + + <listitem><para>Click on the <guibutton>Printing + Preferences...</guibutton> button.</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 and correct way: (should you do this from the beginning, just carry out steps 1 + and 2 from the second method above). + </para> + + <orderedlist numeration="arabic"> + <listitem><para>Click on the <guilabel>Advanced</guilabel> + tab. (If everything is <quote>grayed out,</quote> then you are not logged + in as a user with enough privileges).</para></listitem> + + <listitem><para>Click on the <guibutton>Printing + Defaults</guibutton> button.</para></listitem> + + <listitem><para>On any of the two new tabs, + click on the + <guilabel>Advanced</guilabel> button.</para></listitem> + + <listitem><para>A new dialog opens. Compare + this one to the other. Are they + identical looking comparing one from + <quote>B.5</quote> and one from A.3".</para></listitem> + </orderedlist> + </listitem> +</orderedlist> + +<para> +Do you see any difference in the two settings dialogs? I do not either. However, only the last one, which +you arrived at with steps C.1 through 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 (<smbconfoption name="printer admin"/> in ) before +a client downloads the driver (the clients can later set their own per-user defaults +by following procedures A or B above). Windows 200x/XP allow per-user 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 +<quote><computeroutput>Print Settings for Printer Foo on Server Bar</computeroutput></quote>. The last one is the one you +arrive at when you right-click on the printer and select <guimenuitem>Print Settings...</guimenuitem>. This +is the one that you were taught to use back in the days of Windows NT, so it is only natural to try the +same way with Windows 200x/XP. You would not dream that there is now a different path to arrive at an +identically looking, but functionally different, dialog to set defaults for all users. +</para></formalpara> + +<tip><para>Try (on Windows 200x/XP) to run this command (as a user with the right privileges): +</para> + +<para><userinput> +rundll32 printui.dll,PrintUIEntry /p /t3 /n\\<replaceable>SAMBA-SERVER</replaceable>\<replaceable>printersharename</replaceable> +</userinput></para> + +<para> +To see the tab with the <guilabel>Printing Defaults</guilabel> button (the one you need),also run this command: +</para> + +<para><userinput> +rundll32 printui.dll,PrintUIEntry /p /t0 /n\\<replaceable>SAMBA-SERVER</replaceable>\<replaceable>printersharename</replaceable> +</userinput></para> + +<para> +To see the tab with the <guilabel>Printing Preferences</guilabel> +button (the one which does not set system-wide defaults), you can +start the commands from inside a DOS box" or from <guimenu>Start</guimenu> -> <guimenuitem>Run</guimenuitem>. +</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 hundreds of printers. Using Windows NT APW here is somewhat awkward (to say the least). If +you do not want to acquire RSS pains from 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 +<smbconfsection name="[print$]"/> 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> +repeatedly). The following is an example of how this could be accomplished: +</para> + +<para><screen> +&rootprompt;<userinput>rpcclient <replaceable>SAMBA-CUPS</replaceable> -U root%<replaceable>secret</replaceable> -c 'enumdrivers'</userinput> + 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: [mydrivername] + + [....] +</screen> + +<screen> +&rootprompt;<userinput>rpcclient <replaceable>SAMBA-CUPS</replaceable> -U root%<replaceable>secret</replaceable> -c 'enumprinters'</userinput> + cmd = enumprinters + flags:[0x800000] + name:[\\SAMBA-CUPS\dm9110] + description:[\\SAMBA-CUPS\dm9110,,110ppm HiVolume DANKA Stuttgart] + comment:[110 ppm HiVolume DANKA Stuttgart] + [....] +</screen> + +<screen> +&rootprompt;<userinput>rpcclient <replaceable>SAMBA-CUPS</replaceable> -U root%<replaceable>secret</replaceable> -c \ + 'setdriver <replaceable>dm9110</replaceable> "<replaceable>Heidelberg Digimaster 9110 (PS)</replaceable>"'</userinput> + cmd = setdriver dm9110 Heidelberg Digimaster 9110 (PPD) + Successfully set dm9110 to driver Heidelberg Digimaster 9110 (PS). +</screen> + +<screen> +&rootprompt;<userinput>rpcclient <replaceable>SAMBA-CUPS</replaceable> -U root%<replaceable>secret</replaceable> -c 'enumprinters'</userinput> + 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] + [....] +</screen> + +<screen> +&rootprompt;<userinput>rpcclient <replaceable>SAMBA-CUPS</replaceable> -U root%<replaceable>secret</replaceable> -c 'setdriver <replaceable>dm9110</replaceable> <replaceable>mydrivername</replaceable>'</userinput> + cmd = setdriver dm9110 mydrivername + Successfully set dm9110 to mydrivername. +</screen> + +<screen> +&rootprompt;<userinput>rpcclient <replaceable>SAMBA-CUPS</replaceable> -U root%<replaceable>secret</replaceable> -c 'enumprinters'</userinput> + cmd = enumprinters + flags:[0x800000] + name:[\\SAMBA-CUPS\dm9110] + description:[\\SAMBA-CUPS\dm9110,mydrivername,\ + 110ppm HiVolume DANKA Stuttgart] + comment:[110ppm HiVolume DANKA Stuttgart] + [....] +</screen></para> + +<para> +It may not be easy to recognize that the first call to <command>enumprinters</command> showed the +<quote>dm9110</quote> 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. +</para> +</sect2> + +<sect2> +<title>Adding New Printers with the Windows NT APW</title> + +<para> +By default, Samba exhibits all printer shares defined in &smb.conf; in the <guiicon>Printers</guiicon> +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 <smbconfoption name="printer admin"/>). + </para> + + <tip><para> Try this from a Windows 200x/XP DOS box command prompt: + </para> + + <para><userinput> + runas /netonly /user:root rundll32 printui.dll,PrintUIEntry /p /t0 /n \\<replaceable>SAMBA-SERVER</replaceable>\<replaceable>printersharename</replaceable> + </userinput></para> + + <para> + Click on <guibutton>Printing Preferences</guibutton>. + </para></tip></listitem> + + <listitem><para>... contains the setting + <smbconfoption name="show add printer wizard">yes</smbconfoption> (the + default).</para></listitem> +</itemizedlist> + +<para> +The APW can do various things: +</para> + +<itemizedlist> + <listitem><para> + Upload a new driver to the Samba <smbconfsection name="[print$]"/> 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 + <smbconfoption name="add printer command"/>. A corresponding + <smbconfoption name="delete printer command"/> for removing entries from the + <guiicon>Printers</guiicon> folder may also be provided). + </para></listitem> +</itemizedlist> + +<para> +The last one (add a new printer) requires more effort than the previous ones. To use +the APW to successfully add a printer to a Samba server, the <smbconfoption name="add printer command"/> 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 &smb.conf; if necessary. +</para> + +<para> +When using the APW from a client, if the named printer share does not exist, smbd will execute the +<smbconfoption name="add printer command"/> and re-parse to the to attempt to locate the new printer +share. If the share is still not defined, an error of <errorname>Access Denied</errorname> is returned to +the client. The <smbconfoption name="add printer command"/> is executed +under the context of the connected user, not necessarily a root account. A <smbconfoption name="map to guest">bad user</smbconfoption> may have connected you unwittingly under the wrong +privilege. You should check it by using the <command>smbstatus</command> command. +</para> + +</sect2> + +<sect2> +<title>Error Message: <quote><errorname>Cannot connect under a different Name</errorname></quote></title> + +<para> +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: + <quote>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, + esp. the shared resource, and try again.</quote> + </para></listitem> + + <listitem><para> + Every attempt to <quote>connect a network drive</quote> to <filename>\\SAMBASERVER\\print$</filename> + to <constant>z:</constant> is countered by the pertinacious message: <quote>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</quote>. + </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 more connections. You kill them all. The client +still gives you the same error message. You watch the smbd.log file on a high debug level and try +reconnect. 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 &smbmdash; and this times it works! Windows seems to cache connection information somewhere and +does not keep it up-to-date (if you are unlucky you might need to reboot to get rid of the error message). +</para> + +<para> +The easiest way to forcefully terminate all connections from your client to a server is by executing: +<screen> +&dosprompt; net use * /delete +</screen> +This will disconnect all mapped drives also and will allow you create fresh connection as required. +</para> +</sect2> + +<sect2> +<title>Take Care When Assembling Driver Files</title> + +<para> +You need to be extremely careful when you take notes about the files and belonging to a particular +driver. Don't confuse the files for driver version <quote>0</quote> (for Windows 9x/Me, going into +<filename>[print$]/WIN/0/</filename>), driver version <filename>2</filename> (Kernel Mode driver for Windows NT, +going into <filename>[print$]/W32X86/2/</filename> may be used on Windows 200x/XP also), and +driver version <quote>3</quote> (non-Kernel Mode driver going into <filename>[print$]/W32X86/3/</filename> +cannot be used on Windows NT). Quite often these different driver versions contain +files that have the same name but actually are very different. 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 <command>enumdrivers</command> 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> +Here is an example. You are invited to look 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> +&rootprompt;<userinput>rpcclient -U 'Administrator%<replaceable>secret</replaceable>' -c 'enumdrivers 3' 10.160.50.8 </userinput> + + 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 we write the <quote>version 2</quote> files and the <quote>version 3</quote> files +into different text files and compare the result, we see this +picture: +</para> + +<para><screen> +&rootprompt;<userinput>sdiff 2-files 3-files</userinput> + +<![CDATA[ + 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> + +Do not be fooled! 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> +&rootprompt;<userinput>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</userinput> + + 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> +In my example were even more differences than shown here. Conclusion: you must be careful to select +the correct driver files for each driver version. Don't rely on the +names alone and don't interchange files +belonging to different driver versions. +</para> +</sect2> + +<sect2> +<title>Samba and Printer Ports</title> + +<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>, and so on. Samba must also +support the concept of ports associated with a printer. By default, only one printer port, named <quote>Samba +Printer Port</quote>, exists on a system. Samba does not really need such a <quote>port</quote> in order +to print; rather it is a requirement of Windows clients. They insist on being told about an available +port when they request this information, otherwise they throw an error message at you. So Samba fakes the port +information to keep the Windows clients happy. +</para> + +<para> +Samba does not support the concept of <constant>Printer Pooling</constant> 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 multiple ports be defined for some reason or another (my users and my boss should not know +that they are working with Samba), configure <smbconfoption name="enumports command"/> +which can be used to define an external program that generates a listing of ports on a system. +</para> +</sect2> + +<sect2> +<title>Avoiding Common Client Driver Mis-configuration</title> + +<para> +So now the printing works, but there are still problems. Most jobs print well, some do not print at +all. Some jobs have problems with fonts, which do not look good. Some jobs print fast and some +are dead-slow. We cannot cover it all, but we want to encourage you to read the brief paragraph about +<quote>Avoiding the Wrong PostScript Driver Settings</quote> in the CUPS Printing part of this document. +</para> +</sect2> +</sect1> + +<sect1> +<title>The Imprints Tool-set</title> + +<para> +The Imprints tool set provides a UNIX equivalent of the Windows NT Add Printer +Wizard. For complete information, please refer to the +<ulink url="http://imprints.sourceforge.net/">Imprints</ulink> Web site as well as the documentation +included with the imprints source distribution. This section only provides a brief introduction to +the features of Imprints. +</para> + +<para> +Unfortunately, the Imprints tool-set is no longer maintained. As of December 2000, the project is in +need of a new maintainer. The most important skill to have is Perl coding and an interest in MS-RPC-based +printing used in Samba. If you wish to volunteer, please coordinate +your efforts on the Samba technical +mailing list. The tool-set 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> + +<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 of 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 that 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>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 +the package downloaded is actually +the one referred in the Imprints database. It is strongly recommended that this security check +not be disabled. +</para> +</sect2> + +<sect2> +<title>The Installation Client</title> + +<para> +More information regarding the Imprints installation client is available from the the documentation file +<filename>Imprints-Client-HOWTO.ps</filename> that is included with the Imprints source package. 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> + +<itemizedlist> + <listitem><para> + For each supported architecture for a given driver: + <orderedlist> + <listitem><para>rpcclient: Get the appropriate upload directory on the remote server.</para></listitem> + <listitem><para>smbclient: Upload the driver files.</para></listitem> + <listitem><para>rpcclient: Issues an AddPrinterDriver() MS-RPC.</para></listitem> + </orderedlist> + </para></listitem> + + <listitem><para>rpcclient: Issue an AddPrinterEx() MS-RPC to actually create the printer.</para></listitem> +</itemizedlist> + +<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 <quote>Apple LaserWriter +II NTX v51.8</quote> and Windows 95 calls its version of this driver <quote>Apple LaserWriter II NTX</quote>. +</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><filename> + HKLM\System\CurrentControlSet\Control\Print\Environment +</filename></para> + +<para> +will reveal that Windows NT always uses the NT driver name. This is okay as Windows NT always requires +that at least the Windows NT version of the printer driver is present. Samba does not have the +requirement internally, therefore, <quote>How can you use the NT driver name if it has not already been installed?</quote> +</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 the NT driver is installed first. +</para> +</sect2> +</sect1> + +<sect1> +<title>Adding Network Printers 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. +The ideas sketched out in this section are inspired by this article, which describes a command-line method that 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 the command prompt (<command>DOS box</command>): +</para> + +<para><userinput>rundll32 printui.dll,PrintUIEntry /?</userinput></para> + +<para> +A window pops up that shows you all of the command-line switches available. An extensive list of examples +is also provided. This is only for Win 200x/XP, it does not work on +Windows NT. Windows NT probably has +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 200x/XP Windows +clients access printers via Samba, and works for Windows-based print servers too): +</para> + +<para><screen> +<userinput>rundll32 printui.dll,PrintUIEntry /dn /n "\\cupsserver\infotec2105-IPDS" /q</userinput> +<userinput>rundll32 printui.dll,PrintUIEntry /in /n "\\cupsserver\infotec2105-PS"</userinput> +<userinput>rundll32 printui.dll,PrintUIEntry /y /n "\\cupsserver\infotec2105-PS"</userinput> +</screen></para> + +<para> +Here is a list of the used command-line 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> + +<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 that was + converted to CUPS). The <command>/q</command> at the end eliminates Confirm + or error dialog boxes from 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 the 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 must 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 decide for a + default printer). The default printer selection may, of course, be different for different users. + </para></listitem> +</itemizedlist> + +<para> +The second line only works if the printer <emphasis>infotec2105-PS</emphasis> has an already working +print queue on the <constant>cupsserver</constant>, and if the +printer drivers have been successfully uploaded +(via the <command>APW</command>, <command>smbclient/rpcclient</command>, or <command>cupsaddsmb</command>) +into the <smbconfsection name="[print$]"/> driver repository of Samba. 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, +do not bother checking, just allow the de-installation/re-installation 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 <quote>roaming</quote> 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 few extra 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 from 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, +and so on). 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, 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</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 Windows 9x/Me-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 Samba-2.2.x. 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 Windows NT printer driver support, you also need to migrate the + Windows 9x/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 no longer work with Samba-3. In 3.0, smbd attempts + to locate a Windows 9x/Me driver files for the printer in <smbconfsection name="[print$]"/> + 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 backward compatibility for this. + </para></listitem> + + <listitem><para>You need to install a Windows 9x/Me driver into the + <smbconfsection name="[print$]"/> share for a printer on your Samba + host. The driver files will be stored in the <quote>WIN40/0</quote> subdirectory of + <smbconfsection name="[print$]"/>, and some other settings and information 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 + only current + solution is to use the Windows NT APW to install the NT drivers + and the 9x/Me drivers. This can be scripted using smbclient and + rpcclient. See the Imprints installation client at: + </para> + + <para> + <ulink noescape="1" url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink> + </para> + + <para> + for an example. See also the discussion of rpcclient usage in the + <quote>CUPS Printing</quote> section.</para></listitem> +</itemizedlist> +</sect1> + +<sect1> +<title>Publishing Printer Information in Active Directory or LDAP</title> + +<para> +This will be addressed in a later update of this document. If you wish to volunteer your services to help +document this, please contact <ulink url="mail://jht@samba.org">John H Terpstra.</ulink> +</para> +</sect1> + +<sect1> +<title>Common Errors</title> + +<sect2> +<title>I Give My Root Password but I Do Not Get Access</title> + +<para> +Do not 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 does not know the UNIX password. Root access to Samba resources +requires that a Samba account for root must first be created. This is done with the <command>smbpasswd</command> +command as follows: +</para> + +<para><screen> +&rootprompt; smbpasswd -a root +New SMB password: secret +Retype new SMB password: secret +</screen></para> + +</sect2> + +<sect2> +<title>My Print Jobs Get Spooled into the Spooling Directory, but Then Get Lost</title> + +<para> +Do not use the existing UNIX print system spool directory for the Samba spool directory. It may seem +convenient and a savings of space, but it only leads to problems. The two must be separate. +</para> + +</sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Problems.xml b/docs/Samba3-HOWTO/TOSHARG-Problems.xml new file mode 100644 index 0000000000..1aa065d1c8 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Problems.xml @@ -0,0 +1,295 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="problems"> + +<chapterinfo> + &author.jerry; + &author.jelmer; + &author.dbannon; + &author.danshearer; + <pubdate>8 Apr 2003</pubdate> +</chapterinfo> + +<title>Analyzing and Solving Samba Problems</title> + +<para> +There are many sources of information available in the form +of mailing lists, RFCs and documentation. The documentation that comes +with the Samba distribution contains good explanations of +general SMB topics such as browsing.</para> + +<sect1> +<title>Diagnostics Tools</title> + +<para>With SMB networking, it is often not immediately clear what +the cause is of a certain problem. Samba itself provides rather +useful information, but in some cases you might have to fall back +to using a <emphasis>sniffer</emphasis>. A sniffer is a program that +listens on your LAN, analyzes the data sent on it and displays it +on the screen.</para> + +<sect2> +<title>Debugging with Samba Itself</title> + +<para> +One of the best diagnostic tools for debugging problems is Samba itself. +You can use the <option>-d option</option> for both &smbd; and &nmbd; to specify the +<smbconfoption name="debug level"/> at which to run. +See the man pages for <command>smbd, nmbd</command> and +&smb.conf; for more information regarding 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 information in the binaries and +allow you to attach gdb to the running <command>smbd/nmbd</command> process. +To attach <command>gdb</command> to an <command>smbd</command> +process for an NT workstation, first get the workstation to make the +connection. Pressing ctrl-alt-delete and going down to the domain box +is sufficient (at least, the first time you join the domain) to +generate a <parameter>LsaEnumTrustedDomains</parameter>. Thereafter, the workstation +maintains an open connection and there will be an smbd +process running (assuming that you haven't set a really short smbd +idle timeout). So, in between pressing <command>ctrl-alt-delete</command> and actually +typing in your password, you can attach <command>gdb</command> and continue. +</para> + +<para> +Some useful Samba commands worth investigating are: +</para> + +<screen> +&prompt;<userinput>testparm | more</userinput> +&prompt;<userinput>smbclient -L //{netbios name of server}</userinput> +</screen> + +</sect2> + +<sect2> + <title>Tcpdump</title> + +<para> +<ulink url="http://www.tcpdump.org/">Tcpdump</ulink> was the first +UNIX sniffer with SMB support. It is a command-line utility and +now, its SMB support is somewhat lagging that of <command>ethereal</command> +and <command>tethereal</command>. +</para> + +</sect2> + +<sect2> + <title>Ethereal</title> + +<para> +<ulink url="http://www.ethereal.com/">Ethereal</ulink> is a graphical +sniffer, available for both UNIX (Gtk) and Windows. Ethereal's +SMB support is quite good.</para> + +<para>For details on the use of <command>ethereal</command>, read the well-written +Ethereal User Guide.</para> + +<image id="ethereal1"><imagedescription>Starting a capture.</imagedescription><imagefile>ethereal1</imagefile></image> + +<para>Listen for data on ports 137, 138, 139, and 445. For example, use +the filter <userinput>port 137, port 138, port 139, or port +445</userinput> as seen in <link linkend="ethereal1">Starting a capture</link> snapshot.</para> + +<para>A console version of ethereal is available as well and is called +<command>tethereal</command>.</para> + +<image id="ethereal2"><imagedescription>Main ethereal data window.</imagedescription><imagefile>ethereal2</imagefile></image> + +</sect2> + +<sect2> +<title>The Windows Network Monitor</title> + +<para> +For tracing things on Microsoft Windows NT, Network Monitor +(aka Netmon) is available on Microsoft Developer Network CDs, +the Windows NT Server install CD and the SMS CDs. The version of +Netmon that ships with SMS allows for dumping packets between any two +computers (i.e., placing the network interface in promiscuous mode). +The version on the NT Server install CD will only allow monitoring +of network traffic directed to the local NT box and broadcasts on the +local subnet. Be aware that Ethereal can read and write Netmon +formatted files. +</para> + +<sect3> +<title>Installing Network Monitor on an NT Workstation</title> + +<para> +Installing Netmon on an NT workstation requires a couple +of steps. The following are instructions for installing Netmon V4.00.349, which comes +with Microsoft Windows NT Server 4.0, on Microsoft Windows NT +Workstation 4.0. The process should be similar for other versions of +Windows NT version of Netmon. You will need both the Microsoft Windows +NT Server 4.0 Install CD and the Workstation 4.0 Install CD. +</para> + +<para> +Initially you will need to install <application>Network Monitor Tools and Agent</application> +on the NT Server to do this: +</para> + +<itemizedlist> + <listitem><para>Go to <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 <guilabel>Network Monitor Tools and Agent</guilabel> and click on <guibutton>OK</guibutton>.</para></listitem> + + <listitem><para>Click on <guibutton>OK</guibutton> on the Network Control Panel.</para></listitem> + + <listitem><para>Insert the Windows NT Server 4.0 install CD when prompted.</para></listitem> +</itemizedlist> + +<para> +At this point, the Netmon files should exist in <filename>%SYSTEMROOT%\System32\netmon\*.*</filename>. +Two subdirectories exist as well, <filename>parsers\</filename> which contains the necessary DLLs +for parsing the Netmon packet dump, and <filename>captures\</filename>. +</para> + +<para> +To install the Netmon tools on an NT Workstation, you will first need to install the +Network Monitor Agent from the Workstation install CD. +</para> + +<itemizedlist> + <listitem><para>Go to <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 <guilabel>Network Monitor Agent</guilabel>, click on <guibutton>OK</guibutton>.</para></listitem> + + <listitem><para>Click on <guibutton>OK</guibutton> in the Network Control Panel. + </para></listitem> + + <listitem><para>Insert the Windows NT Workstation 4.0 install CD when prompted.</para></listitem> +</itemizedlist> + +<para> +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> + +</sect3> +<sect3> +<title>Installing Network Monitor on Windows 9x/Me</title> +<para> +To install Netmon on Windows 9x/Me, install the Network Monitor Agent +from the Windows 9x/Me 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. +</para> +</sect3> +</sect2> +</sect1> + +<sect1> +<title>Useful URLs</title> +<itemizedlist> + +<listitem><para>See how Scott Merrill simulates a BDC behavior at + <ulink noescape="1" url="http://www.skippy.net/linux/smb-howto.html"> + http://www.skippy.net/linux/smb-howto.html</ulink>. </para></listitem> + +<listitem><para>FTP site for older SMB specs: + <ulink noescape="1" url="ftp://ftp.microsoft.com/developr/drg/CIFS/"> + ftp://ftp.microsoft.com/developr/drg/CIFS/</ulink></para></listitem> + +</itemizedlist> + +</sect1> + +<sect1> +<title>Getting Mailing List Help</title> + +<para> +There are a number of Samba-related mailing lists. Go to <ulink +noescape="1" url="http://samba.org">http://samba.org</ulink>, click on your nearest mirror +and then click on <command>Support</command> and next click on <command> +Samba-related mailing lists</command>. +</para> + +<para> +For questions relating to Samba TNG, go to +<ulink noescape="1" url="http://www.samba-tng.org/">http://www.samba-tng.org/.</ulink> +It has been requested that you do not post questions about Samba-TNG to the +main-stream Samba lists.</para> + +<para> +If you do post a message to one of the lists, please observe the following guidelines : +</para> + +<itemizedlist> + + <listitem><para>Always remember that the developers are volunteers, they are + not paid and they never guarantee to produce a particular feature at + a particular time. Any timelines are <quote>best guess</quote> and nothing more. + </para></listitem> + + <listitem><para>Always mention what version of Samba you are using and what + operating system it's running under. You should list the relevant sections of + your &smb.conf; file, at least the options in <smbconfsection name="[global]"/> + that affect PDC support. + </para></listitem> + + <listitem><para>In addition to the version, if you obtained Samba via + CVS, mention the date when you last checked it out.</para></listitem> + + <listitem><para> Try and make your questions clear and brief. Lots of long, + convoluted questions get deleted before they are completely read! + Do not post HTML encoded messages. Most people on mailing lists simply delete + them. + </para></listitem> + + <listitem><para> If you run one of those nifty <quote>I'm on holidays</quote> things when + you are away, make sure its configured to not answer mailing list traffic. Auto-responses + to mailing lists really irritate the thousands of people who end up having to deal + with such bad netiquet bahavior. + </para></listitem> + + <listitem><para>Don't cross post. Work out which is the best list to post to + and see what happens. Do not post to both samba-ntdom and samba-technical. + Many people active on the lists subscribe to more + than one list and get annoyed to see the same message two or more times. + Often someone will see a message and thinking it would be better dealt + with on another list, will forward it on for you.</para></listitem> + + <listitem><para>You might include <emphasis>partial</emphasis> + log files written at a debug level set to as much as 20. + Please do not send the entire log but just enough to give the context of the + error messages.</para></listitem> + + <listitem><para>If you have a complete Netmon trace (from the opening of + the pipe to the error), you can send the *.CAP file as well.</para></listitem> + + <listitem><para>Please think carefully before attaching a document to an email. + Consider pasting the relevant parts into the body of the message. The Samba + mailing lists go to a huge number of people. Do they all need a copy of your + &smb.conf; in their attach directory?</para></listitem> + +</itemizedlist> + +</sect1> + +<sect1> +<title>How to Get Off the Mailing Lists</title> + +<para>To have your name removed from a Samba mailing list, go to the same +place where you went to +subscribe to it. Go to <ulink noescape="1" url="http://lists.samba.org/">http://lists.samba.org</ulink>, +click on your nearest mirror, click on <command>Support</command> and +then click on<command> Samba related mailing lists</command>. +</para> + +<para> +Please do not post messages to the list asking to be removed. You will only +be referred to the above address (unless that process failed in some way). +</para> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml b/docs/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml new file mode 100644 index 0000000000..8b137dd4ef --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml @@ -0,0 +1,1125 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="ProfileMgmt"> +<chapterinfo> + &author.jht; + <pubdate>April 3 2003</pubdate> +</chapterinfo> + +<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 deal with those +situations. +</para> + +</sect1> + +<sect1> +<title>Roaming Profiles</title> + +<warning> +<para> +Roaming profiles support is different for Windows 9x/Me and Windows NT4/200x. +</para> +</warning> + +<para> +Before discussing how to configure roaming profiles, it is useful to see how +Windows 9x/Me and Windows NT4/200x clients implement these features. +</para> + +<para> +Windows 9x/Me clients send a NetUserGetInfo request to the server to get the user's +profiles location. However, the response does not have room for a separate +profiles location field, only the user's home share. This means that Windows 9x/Me +profiles are restricted to being stored in the user's home directory. +</para> + + +<para> +Windows NT4/200x clients send a NetSAMLogon RPC request, which contains many fields +including a separate field for the location of the user's profiles. +</para> + +<sect2> +<title>Samba Configuration for Profile Handling</title> + +<para> +This section documents how to configure Samba for MS Windows client profile support. +</para> + +<sect3> +<title>NT4/200x User Profiles</title> + +<para> +For example, to support Windows NT4/200x clients, set the following in the [global] section of the &smb.conf; file: +</para> + +<para> +<smbconfblock> + <smbconfoption name="logon path"> \\profileserver\profileshare\profilepath\%U\moreprofilepath</smbconfoption> +</smbconfblock> + +This is typically implemented like: + +<smbconfblock> +<smbconfoption name="logon path">\\%L\Profiles\%u</smbconfoption> +</smbconfblock> +where <quote>%L</quote> translates to the name of the Samba server and <quote>%u</quote> translates to the user name. +</para> + +<para> +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 that is specified in the logon path +browseable. Please refer to the man page for &smb.conf; in respect of the different +semantics of <quote>%L</quote> and <quote>%N</quote>, as well as <quote>%U</quote> and <quote>%u</quote>. +</para> + +<note> +<para> +MS Windows NT/200x clients at times do not disconnect a connection to a server between logons. It is recommended +to not use the <smbconfsection name="homes"/> meta-service name as part of the profile share path. +</para> +</note> +</sect3> + +<sect3> +<title>Windows 9x/Me User Profiles</title> + +<para> +To support Windows 9x/Me clients, you must use the <smbconfoption name="logon home"/> +parameter. Samba has been fixed so <userinput>net use /home</userinput> now works as well and it, too, relies +on the <command>logon home</command> parameter. +</para> + +<para> +By using the logon home parameter, you are restricted to putting Windows 9x/Me profiles in the user's home +directory. But wait! There is a trick you can use. If you set the following in the +<smbconfsection name="[global]"/> section of your &smb.conf; file: +</para> +<para><smbconfblock> +<smbconfoption name="logon home">\\%L\%U\.profiles</smbconfoption> +</smbconfblock></para> + +<para> +then your Windows 9x/Me clients will dutifully put their clients in a subdirectory +of your home directory called <filename>.profiles</filename> (making them hidden). +</para> + +<para> +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 <filename>\\%L\%U</filename> for <smbconfoption name="logon home"/>. +</para> +</sect3> + +<sect3> +<title>Mixed Windows 9x/Me and Windows NT4/200x User Profiles</title> + +<para> +You can support profiles for Windows 9x and Windows NT clients by setting both the +<smbconfoption name="logon home"/> and <smbconfoption name="logon path"/> parameters. For example: +</para> + +<para><smbconfblock> +<smbconfoption name="logon home">\\%L\%u\.profiles</smbconfoption> +<smbconfoption name="logon path">\\%L\profiles\%u</smbconfoption> +</smbconfblock></para> + +</sect3> +<sect3> +<title>Disabling Roaming Profile Support</title> + +<para> +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> +<indexterm><primary>roaming profiles</primary></indexterm> +There are three ways of doing this: +<indexterm><primary>windows registry settings</primary><secondary>roaming profiles</secondary></indexterm> +</para> + + +<variablelist> + <varlistentry> + <term>In &smb.conf;</term> + <listitem><para> + Affect the following settings and ALL clients will be forced to use a local profile: + <smbconfoption name="logon home"> </smbconfoption> and <smbconfoption name="logon path"> </smbconfoption> + </para> + + <para> + The arguments to these parameters must be left blank. It is necessary to include the <constant>=</constant> sign + to specifically assign the empty value. + </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: +<screen> +Local Computer Policy\ + Computer Configuration\ + Administrative Templates\ + System\ + User Profiles\ + +Disable: Only Allow Local User Profiles +Disable: Prevent Roaming Profile Change from Propagating to the Server +</screen> + </para> </listitem> + </varlistentry> + + <varlistentry> + <term>Change of Profile Type:</term> + <listitem><para>From the start menu right-click on <guiicon>My Computer icon</guiicon>, + select <guimenuitem>Properties</guimenuitem>, click on the <guilabel>User Profiles</guilabel> + tab, select the profile you wish to change from + <guimenu>Roaming</guimenu> type to <guimenu>Local</guimenu>, and click on + <guibutton>Change Type</guibutton>. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +Consult the MS Windows registry guide for your particular MS Windows version for more information +about which registry keys to change to enforce use of only local user profiles. +</para> + +<note><para> +The specifics of how to convert a local profile to a roaming profile, or a roaming profile +to a local one vary according to the version of MS Windows you are running. Consult the Microsoft MS +Windows Resource Kit for your version of Windows for specific information. +</para></note> + +</sect3> </sect2> + +<sect2> <title>Windows Client Profile Configuration Information</title> + +<sect3> <title>Windows 9x/Me Profile Setup</title> + +<para> +When a user first logs in on Windows 9X, the file user.DAT is created, 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 <filename>c:\windows\profiles\username</filename> on subsequent logins, taking the +most recent from each. You will need to use the <smbconfsection name="[global]"/> options +<smbconfoption name="preserve case">yes</smbconfoption>, +<smbconfoption name="short preserve case">yes</smbconfoption> and +<smbconfoption name="case sensitive">no</smbconfoption> +in order to maintain capital letters in shortcuts in any of the profile folders. +</para> + +<para> +The <filename>user.DAT</filename> file contains all the user's preferences. If you wish to enforce a set of preferences, +rename their <filename>user.DAT</filename> file to <filename>user.MAN</filename>, and deny them write access to this file. +</para> + +<orderedlist> + <listitem> <para> + 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 <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> +</orderedlist> + +<para> Under Windows 9x/ME, profiles are downloaded from the Primary Logon. If you have the Primary Logon +as <quote>Client for Novell Networks</quote>, then the profiles and logon script will be downloaded from +your Novell Server. If you have the Primary Logon as <quote>Windows Logon</quote>, then the profiles will +be loaded from the local machine &smbmdash; a bit against the concept of roaming profiles, it would seem! </para> + +<para> +You will now find that the Microsoft Networks Login box contains <constant>[user, password, domain]</constant> instead +of just <constant>[user, password]</constant>. Type in the Samba server's domain name (or any other domain known to exist, +but bear in mind that the user will be authenticated against this domain and profiles downloaded from it, +if that domain logon server supports it), user name and user's password. +</para> + +<para> Once the user has been successfully validated, the Windows 9x/Me machine will inform you that +<computeroutput>The user has not logged on before</computeroutput> and asks you <computeroutput>Do 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 <smbconfoption name="logon path"/> 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> These folders will be cached locally on the client, and updated when the user logs off (if +you haven't made them read-only by then). You will find that if the user creates further folders or +shortcut, that the client will merge the profile contents downloaded with the contents of the profile +directory already on the local client, taking the newest folders and shortcut from each set. </para> + +<para> If you have made the folders/files read-only on the Samba server, then you will get errors from +the Windows 9x/Me machine on logon and logout as it attempts to merge the local and remote profile. +Basically, if you have any errors reported by the Windows 9x/Me machine, check the UNIX file permissions +and ownership rights on the profile directory contents, on the Samba server. </para> + +<para> If you have problems creating user profiles, you can reset the user's local desktop cache, as +shown below. When this user next logs in, the user will be told that he/she is logging in <quote>for + the first time</quote>. + +<indexterm><primary>windows registry settings</primary><secondary>profile path</secondary></indexterm> + </para> + + +<orderedlist> + <listitem><para> + Instead of logging in under the [user, password, domain] dialog, press <guibutton>escape</guibutton>. + </para> </listitem> + + <listitem><para> + Run the <command>regedit.exe</command> program, and look in: + </para> + + <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 <filename>c:\windows\profiles\username</filename>), then delete the key + <parameter>ProfilePath</parameter> for the required user. + </para></listitem> + + <listitem><para> + Exit the registry editor. + </para></listitem> + + <listitem><para> + Search for the user's .PWL password-caching file in the <filename>c:\windows</filename> directory, and delete it. + </para></listitem> + + <listitem><para> + Log off the Windows 9x/Me client. + </para></listitem> + + <listitem><para> + Check the contents of the profile path (see <smbconfoption name="logon path"/> + 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> +</orderedlist> + +<warning><para> +Before deleting the contents of the directory listed in the <parameter>ProfilePath</parameter> +(this is likely to be <filename>c:\windows\profiles\username)</filename>, ask the owner if they have +any important files stored on their desktop or in their start menu. Delete the contents of the +directory <parameter>ProfilePath</parameter> (making a backup if any of the files are needed). +</para> + +<para> +This will have the effect of removing the local (read-only hidden system file) <filename>user.DAT</filename> +in their profile directory, as well as the local <quote>desktop,</quote> <quote>nethood,</quote> +<quote>start menu,</quote> and <quote>programs</quote> folders. +</para></warning> + +<para> +If all else fails, increase Samba's debug log levels to between 3 and 10, and/or run a packet +sniffer program such as ethereal or <command>netmon.exe</command>, and look for error messages. +</para> + +<para> If you have access to an Windows NT4/200x server, then first set up roaming profiles and/or +netlogons on the Windows NT4/200x server. Make a packet trace, or examine the example packet traces +provided with Windows NT4/200x server, and see what the differences are with the equivalent Samba trace. +</para> + +</sect3> + +<sect3> +<title>Windows NT4 Workstation</title> + +<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 <smbconfoption name="logon path"/> parameter. +</para> + +<para> There is a parameter that is now available for use with NT Profiles: <smbconfoption name="logon drive"/>. +This should be set to <filename>H:</filename> or any other drive, and should be used in conjunction with +the new <smbconfoption name="logon home"/> parameter. </para> + +<para> The entry for the NT4 profile is a directory not a file. The NT help on Profiles mentions that a +directory is also created with a .PDS extension. The user, while logging in, must have write permission +to create the full profile path (and the folder with the .PDS extension for those situations where it +might be created.) </para> + +<para> In the profile directory, Windows NT4 creates more folders than Windows 9x/Me. 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 <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 +<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 <filename>NTuser.DAT</filename> +or, for a mandatory profile, <filename>NTuser.MAN</filename>. </para> </sect3> + +<sect3> <title>Windows 2000/XP Professional</title> + +<para> You must first convert the profile from a local profile to a domain profile on the MS Windows +workstation as follows: </para> + +<procedure> + <step><para> Log on as the <emphasis>local</emphasis> workstation administrator. </para></step> + + <step><para> Right-click on the <guiicon>My Computer</guiicon> Icon, select + <guimenuitem>Properties</guimenuitem>.</para></step> + + <step><para> Click on the <guilabel>User Profiles</guilabel> tab.</para></step> + + <step><para> Select the profile you wish to convert (click it once).</para></step> + + <step><para> Click on the <guibutton>Copy To</guibutton> button.</para></step> + + <step><para> In the <guilabel>Permitted to use</guilabel> box, click on the + <guibutton>Change</guibutton> button. </para></step> + + <step><para> Click on the <guilabel>Look in</guilabel> 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. + For example, connect as <replaceable>DOMAIN</replaceable>\root, password: + <replaceable>mypassword</replaceable>.</para></note> </step> + + <step><para> To make the profile capable of being used by anyone, select <quote>Everyone</quote>. </para></step> + + <step><para> Click on <guibutton>OK</guibutton> and the Selection box will close. </para></step> + + <step><para> Now click on <guibutton>OK</guibutton> to create the profile in the path + you nominated. </para></step> +</procedure> + +<para> Done. You now have a profile that can be edited using the Samba <command>profiles</command> tool. +</para> + +<note><para> +Under Windows NT/200x, the use of mandatory profiles forces the use of MS Exchange storage of mail +data and keeps it out of the desktop profile. That keeps desktop profiles from becoming unusable. +</para> </note> + +<sect4> +<title>Windows XP Service Pack 1</title> + <para> + There 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 the Active Directory. The policy is called: + </para> + + <para> + <filename>Computer Configuration\Administrative Templates\System\User Profiles\<?latex \linebreak ?>Do not check for + user ownership of Roaming Profile Folders</filename>i + </para> + + <para> + This should be set to <constant>Enabled</constant>. + </para> + + <para> + 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> + + <para>If you cannot set group policies in Samba, then you may be able to set the policy locally on + each machine. If you want to try this, then do the following (N.B. I do not know for sure that this + will work in the same way as a domain group policy): + </para> + + +<procedure> + <step><para>On the XP workstation, log in with an Administrative account.</para></step> + + <step><para>Click on <guimenu>Start</guimenu> -> <guimenuitem>Run</guimenuitem>.</para></step> + <step><para>Type <command>mmc</command>.</para></step> + <step><para>Click on <guibutton>OK</guibutton>.</para></step> + <step><para>A Microsoft Management Console should appear.</para></step> + <step><para>Click on <guimenu>File</guimenu> -> <guimenuitem>Add/Remove Snap-in</guimenuitem> -> <guimenuitem>Add</guimenuitem>.</para></step> + <step><para>Double-click on <guiicon>Group Policy</guiicon>.</para></step> + <step><para>Click on <guibutton>Finish</guibutton> -> <guibutton>Close</guibutton>.</para></step> + <step><para>Click on <guibutton>OK</guibutton>.</para></step> + <step><para>In the <quote>Console Root</quote> window 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 on <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 on <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></step> + <step><para>Reboot.</para></step> +</procedure> +</sect4> +</sect3> +</sect2> + +<sect2> + <title>User Profile Hive Cleanup Service</title> + +<para> +There certain situations that cause a cached local copy of roaming profile not to be deleted on exit, even if +the policy to force such deletion is set. To deal with that situation special service was created. The application +<command>UPHClean</command> (User Profile Hive Cleanup) can be installed as service on Windows NT4/2000/XP Professional, +and Windows 2003. +</para> + +<para> +The UPHClean software package can be downloaded from <ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyID=1B286E6D-8912-4E18-B570-42470E2F3582&displaylang=en">User Profile Hive Cleanup Service.</ulink> +</para> + +</sect2> + +<sect2> + <title>Sharing Profiles between W9x/Me and NT4/200x/XP Workstations</title> + +<para> Sharing of desktop profiles between Windows versions is not recommended. Desktop profiles are an +evolving phenomenon and profiles for later versions of MS Windows clients add features that may interfere +with earlier versions of MS Windows clients. Probably the more salient reason to not mix profiles is +that when logging off an earlier version of MS Windows, the older format of profile contents may overwrite +information that belongs to the newer version resulting in loss of profile information content when that +user logs on again with the newer version of MS Windows. </para> + +<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 +<smbconfoption name="logon path"/> and +<smbconfoption name="logon home"/>. </para> + +<para> 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> + +<sect2> +<title>Profile Migration from Windows NT4/200x Server to Samba</title> + +<para> There is nothing to stop you from specifying any path that you like for the location of users' profiles. +Therefore, you could specify that the profile be stored on a Samba server, or any other SMB server, +as long as that SMB server supports encrypted passwords. </para> + +<sect3> +<title>Windows NT4 Profile Management Tools</title> + +<para> Unfortunately, the Resource Kit information is specific to the version of MS Windows NT4/200x. The +correct resource kit is required for each platform. </para> + +<para>Here is a quick guide:</para> + +<procedure> + <step><para> On your NT4 Domain Controller, right click on <guiicon>My Computer</guiicon>, then select the + tab labeled <guilabel>User Profiles</guilabel>. </para></step> + + <step><para> Select a user profile you want to migrate and click on it. </para> + + <note><para>I am using the term <quote>migrate</quote> loosely. You can copy a profile to create a group + profile. You can give the user <parameter>Everyone</parameter> 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></step> + + <step><para>Click on the <guibutton>Copy To</guibutton> button.</para></step> + + <step><para>In the box labeled <guilabel>Copy Profile to</guilabel> add your new path, e.g., + <filename>c:\temp\foobar</filename></para></step> + + <step><para>Click on <guibutton>Change</guibutton> in the <guilabel>Permitted to use</guilabel> box.</para></step> + + <step><para>Click on the group <quote>Everyone</quote>, click on <guibutton>OK</guibutton>. This + closes the <quote>choose user</quote> box.</para></step> + + <step><para>Now click on <guibutton>OK</guibutton>.</para></step> +</procedure> + +<para> Follow the above for every profile you need to migrate. </para> + +</sect3> + +<sect3> +<title>Side Bar Notes</title> + + +<para> +<indexterm><primary>SID</primary></indexterm> +You should obtain the SID of your NT4 domain. You can use smbpasswd to do this. Read the man +page.</para> + +</sect3> + +<sect3> <title>moveuser.exe</title> + +<para> The Windows 200x professional resource kit has <command>moveuser.exe</command>. <command>moveuser.exe</command> changes the security of a profile +from one user to another. This allows the account domain to change, and/or the user name to change.</para> + +<para> +This command is like the Samba <command>profiles</command> tool. +</para> + +</sect3> + +<sect3> +<title>Get SID</title> + +<para> +<indexterm><primary>SID</primary></indexterm> +You can identify the SID by using <command>GetSID.exe</command> from the Windows NT Server 4.0 Resource Kit. </para> + +<para> Windows NT 4.0 stores the local profile information in the registry under the following key: +<filename>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList</filename> </para> + +<para> Under the ProfileList key, there will be subkeys named with the SIDs of the users who have logged +on to this computer. (To find the profile information for the user whose locally cached profile you want +to move, find the SID for the user with the <command>GetSID.exe</command> utility.) Inside the appropriate user's subkey, +you will see a string value named <parameter>ProfileImagePath</parameter>. </para> + +</sect3> </sect2> </sect1> + +<sect1> <title>Mandatory Profiles</title> + +<para> +<indexterm><primary>mandatory profiles</primary></indexterm> +A Mandatory Profile is a profile that the user does not have the ability to overwrite. During the +user's session, it may be possible to change the desktop environment, however, as the user logs out all changes +made will be lost. If it is desired to not allow the user any ability to change the desktop environment, +then this must be done through policy settings. See the previous chapter. </para> + +<note><para> Under NO circumstances should the profile directory (or its +contents) be made read-only as this may render the profile un-usable. +Where it is essential to make a profile read-only within the UNIX file +system, this can be done but then you absolutely must use the +<command>fake-permissions</command> VFS module to instruct MS Windows +NT/200x/XP clients that the Profile has write permission for the user. +See <link linkend="fakeperms">fake_perms VFS module</link>. </para></note> + +<para> For MS Windows NT4/200x/XP, the above method can also be used to create mandatory profiles. To +convert a group profile into a mandatory profile, simply locate the <filename>NTUser.DAT</filename> file in the copied profile +and rename it to <filename>NTUser.MAN</filename>. </para> + +<para> For MS Windows 9x/ME, it is the <filename>User.DAT</filename> file that must be renamed to +<filename>User.MAN</filename> to effect a mandatory profile. </para> + +</sect1> + +<sect1> +<title>Creating and Managing Group Profiles</title> + +<para> +<indexterm><primary>group profiles</primary></indexterm> +Most organizations are arranged into departments. There is a nice benefit in this fact since usually +most users in a department require the same desktop applications and the same desktop layout. MS +Windows NT4/200x/XP will allow the use of Group Profiles. A Group Profile is a profile that is created +first using a template (example) user. Then using the profile migration tool (see above), the profile is +assigned access rights for the user group that needs to be given access to the group profile. </para> + +<para> The next step is rather important. Instead of assigning a group profile to users (Using User Manager) +on a <quote>per user</quote> basis, the group itself is assigned the now modified profile. </para> + +<note> +<para> Be careful with Group Profiles. If the user who is a member of a group also has a personal +profile, then the result will be a fusion (merge) of the two. </para> +</note> + +</sect1> + +<sect1> +<title>Default Profile for Windows Users</title> + +<para> +<indexterm><primary>default profile</primary></indexterm> +MS Windows 9x/Me and NT4/200x/XP will use a default profile for any user for whom a profile +does not already exist. Armed with a knowledge of where the default profile is located on the Windows +workstation, and knowing which registry keys effect the path from which the default profile is created, +it is possible to modify the default profile to one that has been optimized for the site. This has +significant administrative advantages. </para> + +<sect2> +<title>MS Windows 9x/Me</title> + +<para> 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 <application>System Policy +Editor</application>, then select <guimenu>File</guimenu> -> <guimenuitem>Open Registry</guimenuitem>, +next click on the <guiicon>Local Computer</guiicon> icon, click on <guilabel>Windows 98 System</guilabel>, +select <guilabel>User Profiles</guilabel>, and click on the enable box. Remember to save the registry +changes. </para> + +<para> To modify the registry directly, launch the <application>Registry Editor</application> +(<command>regedit.exe</command>) and select the hive <filename>HKEY_LOCAL_MACHINE\Network\Logon</filename>. Now +add a DWORD type key with the name <quote>User Profiles,</quote> to +enable user profiles to set the value +to 1; to disable user profiles set it to 0. </para> + +<sect3> +<title>User Profile Handling with Windows 9x/Me</title> + +<para> When a user logs on to a Windows 9x/Me machine, the local profile path, +<filename>HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\ProfileList</filename>, is checked +for an existing entry for that user. </para> + +<para> If the user has an entry in this registry location, Windows 9x/Me checks for a locally cached +version of the user profile. Windows 9x/Me also checks the user's home directory (or other specified +directory if the location has been modified) on the server for the User Profile. If a profile exists +in both locations, the newer of the two is used. If the User Profile exists on the server, but does not +exist on the local machine, the profile on the server is downloaded and used. If the User Profile only +exists on the local machine, that copy is used. </para> + +<para> If a User Profile is not found in either location, the Default User Profile from the Windows +9x/Me machine is used and copied to a newly created folder for the logged on user. At log off, any +changes that the user made are written to the user's local profile. If the user has a roaming profile, +the changes are written to the user's profile on the server. </para> + +</sect3> </sect2> + +<sect2> +<title>MS Windows NT4 Workstation</title> + +<para> 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:\Windows NT\Profiles</filename>. Under this directory on a clean install there will be three +(3) directories: <filename>Administrator</filename>, <filename>All +Users,</filename> and <filename>Default +User</filename>. </para> + +<para> The <filename>All Users</filename> directory contains menu settings that are common across all +system users. The <filename>Default User</filename> directory contains menu entries that are customizable +per user depending on the profile settings chosen/created. </para> + +<para> When a new user first logs onto an MS Windows NT4 machine, a new profile is created from: </para> + +<itemizedlist> + <listitem><para>All Users settings.</para></listitem> + <listitem><para>Default User settings (contains the default <filename>NTUser.DAT</filename> file).</para></listitem> +</itemizedlist> + +<para> When a user logs onto an MS Windows NT4 machine that is a member of a Microsoft security domain, + the following steps are followed in respect of profile handling: + +<indexterm><primary>NTConfig.POL</primary></indexterm> +</para> + + +<procedure> + <step> <para> The users' account information that is obtained during the logon process + contains the location of the users' desktop profile. The profile path may be local to + the machine or it may be located on a network share. If there exists a profile at the + location of the path from the user account, then this profile is copied to the location + <filename>%SystemRoot%\Profiles\%USERNAME%</filename>. This profile then inherits the settings + in the <filename>All Users</filename> profile in the <filename>%SystemRoot%\Profiles</filename> + location. </para> </step> + + <step> <para> If the user account has a profile path, but at its 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> </step> + + <step> <para> If the NETLOGON share on the authenticating server (logon server) contains + a policy file (<filename>NTConfig.POL</filename>), then its contents are applied to the + <filename>NTUser.DAT</filename> which is applied to the <filename>HKEY_CURRENT_USER</filename> + part of the registry. + </para> </step> + + <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 + recreated from the contents of the <filename>HKEY_CURRENT_USER</filename> contents. Thus, + should there not exist in the NETLOGON share an <filename>NTConfig.POL</filename> at the next + logon, the effect of the previous <filename>NTConfig.POL</filename> will still be held in the + profile. The effect of this is known as tattooing. + </para> </step> +</procedure> + +<para> MS Windows NT4 profiles may be <emphasis>local</emphasis> or <emphasis>roaming</emphasis>. A local +profile will stored in the <filename>%SystemRoot%\Profiles\%USERNAME%</filename> location. A roaming +profile will also remain stored in the same way, unless the following registry key is created as shown: </para> + +<para><screen> HKEY_LOCAL_MACHINE\SYSTEM\Software\Microsoft\Windows NT\CurrentVersion\ +winlogon\"DeleteRoamingCache"=dword:0000000 + </screen> +In this case, the local copy (in <filename>%SystemRoot%\Profiles\%USERNAME%</filename>) will be deleted +on logout.</para> + +<para> Under MS Windows NT4, default locations for common resources like <filename>My Documents</filename> +may be redirected to a network share by modifying the following registry keys. These changes may be +affected via use of the System Policy Editor. To do so may require that you create your own template +extension for the policy editor to allow this to be done through the GUI. Another way to do this is by +way of first creating a default user profile, then while logged in as that user, run <command>regedt32</command> to edit +the key settings. </para> + +<para> +The Registry Hive key that affects the behavior of folders that are part of the default user +profile are controlled by entries on Windows NT4 is: +<screen> +HKEY_CURRENT_USER + \Software + \Microsoft + \Windows + \CurrentVersion + \Explorer + \User Shell Folders +</screen> +<indexterm><primary>windows registry settings</primary><secondary>default profile locations</secondary></indexterm> +</para> + +<para> The above hive key contains a list of automatically managed +folders. The default entries are shown in <link linkend="ProfileLocs">the next table</link>. +</para> + +<table frame="all" id="ProfileLocs"> + <title>User Shell Folder Registry Keys Default Values</title> + <tgroup cols="2"> + <colspec align="left"/> + <colspec align="left"/> + <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> The registry key that contains the location of the default profile settings is: </para> + +<para> <filename>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\<?latex \linebreak ?> +User Shell Folders</filename> </para> + +<para> The default entries are shown in <link linkend="regkeys">the next table</link>.</para> + +<table frame="all" id="regkeys"> + <title>Defaults of Profile Settings Registry Keys</title> + <tgroup cols="2"> + <colspec align="left"/> + <colspec align="left"/> + <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\Programs\Startup</entry></row> + </tbody> + </tgroup> +</table> + +</sect2> + +<sect2> <title>MS Windows 200x/XP</title> + +<note><para> +<indexterm><primary>GPOs</primary></indexterm> +MS Windows XP Home Edition does use default per user profiles, but cannot participate +in domain security, cannot log onto an NT/ADS-style domain, and thus can obtain the profile only +from itself. While there are benefits in doing this, the beauty of those MS Windows clients that +can participate in domain logon processes allows the administrator to create a global default +profile and enforce it through the use of Group Policy Objects (GPOs). +</para></note> + +<para> When a new user first logs onto an MS Windows 200x/XP machine, the default profile is obtained from +<filename>C:\Documents and Settings\Default User</filename>. The administrator can modify or change the +contents of this location and MS Windows 200x/XP will gladly use it. This is far from the optimum arrangement +since it will involve copying a new default profile to every MS Windows 200x/XP client workstation. </para> + +<para> When MS Windows 200x/XP participates in a domain security context, and if the default user profile is + not found, then the client will search for a default profile in the NETLOGON share of the authenticating + server. In MS Windows parlance,<?latex \linebreak ?><filename>%LOGONSERVER%\NETLOGON\Default User,</filename> and if one +exists there it will copy this to the workstation to the <filename>C:\Documents and Settings\</filename> +under the Windows login name of the user. </para> + +<note> <para> This path translates, in Samba parlance, to the &smb.conf; +<smbconfsection name="[NETLOGON]"/> share. The directory should be created at the root +of this share and must be called <filename>Default User</filename>. +</para> </note> + +<para> If a default profile does not exist in this location, then MS Windows 200x/XP will use the local +default profile. </para> + +<para> On logging out, the users' desktop profile will be stored to the location specified in the registry +settings that pertain to the user. If no specific policies have been created or passed to the client +during the login process (as Samba does automatically), then the user's profile will be written to the +local machine only under the path <filename>C:\Documents and Settings\%USERNAME%</filename>. </para> + +<para> Those wishing to modify the default behavior can do so through these three methods: </para> + +<itemizedlist> + <listitem> <para> Modify the registry keys on the local machine manually and place the new + default profile in the NETLOGON share root. This is not recommended as it is maintenance intensive. + </para> </listitem> + + <listitem> <para> Create an NT4-style NTConfig.POL file that specified this behavior and locate + this file in the root of the NETLOGON share along with the new default profile. </para> </listitem> + + <listitem> <para> Create a GPO that enforces this through Active Directory, and place the new + default profile in the NETLOGON share. </para> </listitem> +</itemizedlist> + +<para>The registry hive key that effects the behavior of folders that are part of the default user +profile are controlled by entries on Windows 200x/XP is: </para> + +<para> <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 shown +in <link linkend="defregpthkeys">the next table</link> +<indexterm><primary>windows registry settings</primary><secondary>default profile locations</secondary></indexterm> +</para> + + +<table frame="all" id="defregpthkeys"> + <title>Defaults of Default User Profile Paths Registry Keys</title> + <tgroup cols="2"> + <colspec align="left"/> + <colspec align="left"/> + <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> There is also an entry called <quote>Default</quote> 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> It makes a huge difference to the speed of handling roaming user profiles if all the folders are +stored on a dedicated location on a network server. This means that it will not be necessary to write +the Outlook PST file over the network for every login and logout. </para> + +<para> To set this to a network location, you could use the following examples: </para> + +<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> + +<para><filename>\\<replaceable>SambaServer</replaceable>\<replaceable>FolderShare</replaceable>\%USERNAME%</filename></para> + +<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> + +<para> Please note that once you have created a default profile share, you MUST migrate a user's profile +(default or custom) to it. </para> + +<para> MS Windows 200x/XP profiles may be <emphasis>Local</emphasis> or <emphasis>Roaming</emphasis>. + A roaming profile will be cached locally unless the following registry key is created: + +<indexterm><primary>delete roaming profiles</primary></indexterm> +</para> + + +<para> <programlisting> HKEY_LOCAL_MACHINE\SYSTEM\Software\Microsoft\Windows NT\CurrentVersion\ + winlogon\"DeleteRoamingCache"=dword:00000001</programlisting></para> + +<para> +In this case, the local cache copy will be deleted on logout. +</para> +</sect2> +</sect1> + +<sect1> <title>Common Errors</title> + +<para> +The following are some typical errors, problems and questions that have been asked on the Samba mailing lists. +</para> + +<sect2> +<title>Configuring Roaming Profiles for a Few Users or Groups</title> + +<para> +With Samba-2.2.x, the choice you have is to enable or disable roaming profiles support. It is a +global only setting. The default is to have roaming profiles and the default path will locate them in +the user's home directory. +</para> + +<para> +If disabled globally, then no one will have roaming profile ability. If enabled and you want it +to apply only to certain machines, then on those machines on which roaming profile support is not wanted +it is then necessary to disable roaming profile handling in the registry of each such machine. +</para> + +<para> +With Samba-3, you can have a global profile setting in &smb.conf; and you can override this by +per-user settings using the Domain User Manager (as with MS Windows NT4/ Win 200xx). </para> + +<para> 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 cannot change).</para></listitem> + <listitem><para>A group profile (really should be mandatory, that is unchangable).</para></listitem> +</itemizedlist> + +</sect2> + +<sect2> <title>Cannot Use Roaming Profiles</title> + +<para> A user requested the following: <quote> I do not want Roaming profiles to be implemented. I want +to give users a local profile alone. Please help me, I am totally lost with this error. For the past +two days I tried everything, I googled around but found no useful pointers. Please help me. </quote></para> + +<para> The choices are: </para> + +<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> As a user logs onto the network, a centrally + stored profile is copied to the workstation to form a local profile. This local profile + will persist (remain on the workstation disk) unless a registry key is changed that will + cause this profile to be automatically deleted on logout. </para></listitem> + </varlistentry> +</variablelist> + +<para>The roaming profile choices are: </para> + +<variablelist> + <varlistentry> + <term>Personal roaming profiles</term> <listitem><para> These are typically stored in + a profile share on a central (or conveniently located local) server. </para> + + <para> Workstations cache (store) a local copy of the profile. This cached + copy is used when the profile cannot be downloaded at next logon. </para></listitem> + </varlistentry> + + <varlistentry> + <term>Group profiles</term> <listitem><para>These are loaded from a central profile + server.</para></listitem> + </varlistentry> + + <varlistentry> + <term>Mandatory profiles</term> <listitem><para> Mandatory profiles can be created for + a user as well as for any group that a user is a member of. Mandatory profiles cannot be + changed by ordinary users. Only the administrator can change or reconfigure a mandatory + profile. </para></listitem> + </varlistentry> +</variablelist> + +<para> A Windows NT4/200x/XP profile can vary in size from 130KB to very large. 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 profile 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 takes an hour to log onto a +workstation but they harvest the fruits 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 backend. This +removes the need for a PST file. </para> + +<para>Local profiles mean: </para> + +<itemizedlist> + <listitem><para>If each machine is used by many users, then much local disk storage is needed + for local profiles.</para></listitem> <listitem><para>Every workstation the user logs into has + its own profile; these can be very different from machine to machine.</para></listitem> +</itemizedlist> + +<para> On the other hand, use of roaming profiles means: </para> + +<itemizedlist> + <listitem><para>The network administrator can control the desktop environment of all users.</para></listitem> + <listitem><para>Use of mandatory profiles drastically reduces network management overheads.</para></listitem> + <listitem><para>In the long run, users will experience fewer problems.</para></listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Changing the Default Profile</title> + +<para><quote>When the client logs onto the Domain Controller, it searches +for a profile to download. Where do I put this default profile?</quote></para> + +<para> +<indexterm><primary>default profile</primary></indexterm> +First, the Samba server needs to be configured as a Domain Controller. This can be done by +setting in &smb.conf;: </para> + +<smbconfblock> +<smbconfoption name="security">user</smbconfoption> +<smbconfoption name="os level">32 (or more)</smbconfoption> +<smbconfoption name="domain logons">Yes</smbconfoption> +</smbconfblock> + +<para> There must be a <smbconfsection name="[netlogon]"/> 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), 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 <smbconfsection name="netlogon"/> +share root directory.</para></note> + +<para> Windows clients need to be members of the domain. Workgroup machines do not use network logons +so they do not interoperate with domain profiles. </para> + +<para> For roaming profiles, add to &smb.conf;: </para> + +<smbconfblock> +<smbconfoption name="logon path">\\%N\profiles\%U</smbconfoption> +<smbconfcomment>Default logon drive is Z:</smbconfcomment> +<smbconfoption name="logon drive">H:</smbconfoption> +<smbconfcomment>This requires a PROFILES share that is world writable.</smbconfcomment> +</smbconfblock> + +</sect2> +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml b/docs/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml new file mode 100644 index 0000000000..a8c2811511 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml @@ -0,0 +1,278 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="rights"> +<chapterinfo> + &author.jerry; + &author.jht; +</chapterinfo> + +<title>User Rights and Privileges</title> + +<para> +The administration of Windows user, group and machine accounts in the Samba +domain controlled network necessitates interfacing between the MS Windows +networking environment and the UNIX operating system environment. The right +(permission) to add machines to the Windows security domain can be assigned +(set) to non-administrative users both in Windows NT4 domains as well as in +Active Directory domains. +</para> + +<para> +The addition of Windows NT4/2kX/XPPro machines to the domain necessitates the +creation of a machine account for each machine added. The machine account is +a necessity that is used to validate that the machine can be trusted to permit +user logons. +</para> + +<para> +Machine accounts are analogous to user accounts, and thus in implementing them +on a UNIX machine that is hosting Samba (i.e.: On which Samba is running) it is +necessary to create a special type of user account. Machine accounts differ from +a normal user account in that the account name (login ID) is terminated with a $ +sign. An additional difference is that this type of account should not ever be able +to log into the UNIX environment as a system user and therefore is set to have a +shell of <command>/bin/false</command> and a home directory of +<command>/dev/null.</command> +</para> + +<para> +The creation of UNIX system accounts has traditionally been the sole right of +the system administrator, better known as the <constant>root</constant> account. +It is possible in the UNIX environment to create multiple users who have the +same UID. Any UNIX user who has a UID=0 is inherently the same as the +<constant>root</constant> account. +</para> + +<para> +All versions of Samba call system interface scripts that permit CIFS function +calls that are used to manage users, groups and machine accounts to be affected +in the UNIX environment. All versions of Samba up to and including version 3.0.10 +required the use of a Windows Administrator account that unambiguously maps to +the UNIX <constant>root</constant> account to permit the execution of these +interface scripts. The reuqirement to do this has understandably met with some +disdain and consternation among Samba administrators, particularly where it became +necessary to permit people who should not posses <constant>root</constant> level +access to the UNIX host system. +</para> + +<sect1> +<title>Rights Management Capabilities</title> + +<para> +Samba 3.0.11 introduces support for the Windows privilege model. This model +allows certain rights to be assigned to a user or group SID. In order to enable +this feature, <smbconfoption name="enable privileges">yes</smbconfoption> +must be defined in the <smbconfsection name="global"/> section of the &smb.conf; file. +</para> + +<para> +Currently, the rights supported in Samba 3 are listed in <link linkend="rp-privs"/>. +The remainder of this chapter explains how to manage and use these privileges on Samba servers. +</para> + +<table id="rp-privs"> + <title>Current Privilege Capabilities</title> + <tgroup cols="2"> + <colspec align="right"/> + <colspec align="left"/> + <thead> + <row> + <entry align="center">Privilege</entry> + <entry align="center">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><para>SeMachineAccountPrivilege</para></entry> + <entry><para>Add machines to domain</para></entry> + </row> + <row> + <entry><para>SePrintOperatorPrivilege</para></entry> + <entry><para>Manage printers</para></entry> + </row> + <row> + <entry><para>SeAddUsersPrivilege</para></entry> + <entry><para>Add users and groups to the domain</para></entry> + </row> + <row> + <entry><para>SeRemoteShutdownPrivilege</para></entry> + <entry><para>Force shutdown from a remote system</para></entry> + </row> + <row> + <entry><para>SeDiskOperatorPrivilege</para></entry> + <entry><para>Manage disk share</para></entry> + </row> + </tbody> + </tgroup> +</table> + +<sect2> +<title>Using the <quote>net rpc rights</quote> Utility</title> + +<para> +There are two primary means of managing the rights assigned to users and groups +on a Samba server. The <command>NT4 User Manager for Domains</command> may be +used from any Windows NT4, 2000 or XP Professional domain member client to +connect to a Samba domain controller and view/modify the rights assignments. +This application, however, appears to have bugs when run on a client running +Windows 2000 or later, therefore Samba provides a command line utility for +performing the necessary administrative actions. +</para> + +<para> +The <command>net rpc rights</command> utility in Samba 3.0.11 has 3 new subcommands: +</para> + +<variablelist> + <varlistentry><term>list [name|accounts]</term> + <listitem><para> + When called with no arguments, <command>net rpc list</command> + will simply list the available rights on the server. When passed + a specific user or group name, the tool lists the privileges + currently assigned to the specified account. When invoked using + the special string <constant>accounts</constant>, + <command>net rpc rights list</command> will return a list of all + privileged accounts on the server and the assigned rights. + </para></listitem> + </varlistentry> + + <varlistentry><term>grant <user> <right [right ...]></term> + <listitem><para> + When called with no arguments, This function is used to assign + a list of rights to a specified user or group. For example, + to grant the members of the Domain Admins group on a Samba DC + the capability to add client machines to the domain, one would run: +<screen> +&rootprompt; net -S server -U domadmin rpc rights grant \ + 'DOMAIN\Domain Admins' SeMachineAccountPrivilege +</screen> + More than one privilege can be assigned by specifying a + list of rights separated by spaces. The parameter 'Domain\Domain Admins' + must be quoted with single ticks or using double-quotes to prevent + the back-slash and the space from being interpreted by the system shell. + </para></listitem> + </varlistentry> + + <varlistentry><term>revoke <user> <right [right ...]></term> + <listitem><para> + This command is similar in format to <command>net rpc rights grant</command>. It's + effect is to remove an assigned right (or list of rights) from a user or group. + </para></listitem> + </varlistentry> + +</variablelist> + +<note><para> +You must be connected as a member of the Domain Admins group to be able to +grant or revoke privileges assigned to an account. This capability is +inherent to the Domain Admins group and is not configurable. +</para></note> + +<para> +By default, no privileges are initially assigned to any +account. The reason for this is that certain actions will +be performed as root once smbd determines that a user has +the necessary rights. For example, when joining a client to +a Windows domain, the 'add machine script' must be executed +with superuser rights in most cases. For this reason, you +should be very careful about handing out privileges to +accounts. +</para> + +<para> +Access as the root user (UID=0) bypasses all privilege checks. +</para> + +</sect2> + +<sect2> +<title>Description of Privileges</title> + +<para> +The privileges that have been implemented in Samba-3.0.11 are shown below. +It is possible, and likely, that additional privileges may be implemented in +later releases of Samba. It is also likely that any privileges currently implemented +but not used may be removed from future releases, thus it is important that +the successful as well as unsuccessful use of these facilities should be reported +on the Samba mailing lists. +</para> + +<variablelist> + <varlistentry><term>SeAddUsersPrivilege</term> + <listitem><para> + This right determines whether or not smbd will allow the + user to create new user or group accounts via such tools + as <command>net rpc user add</command> or + <command>NT4 User Manager for Domains.</command> + </para></listitem> + </varlistentry> + + <varlistentry><term>SeDiskOperatorPrivilege</term> + <listitem><para> + Accounts which posses this right will be able to execute + scripts defined by the <command>add/delete/change</command> + share command in &smb.conf; file as root. Such users will + also be able to modify the ACL associated with file shares + on the Samba server. + </para></listitem> + </varlistentry> + + <varlistentry><term>SeMachineAccountPrivilege</term> + <listitem><para> + Controls whether or not the user is able join client + machines to a Samba controlled domain. + </para></listitem> + </varlistentry> + + <varlistentry><term>SePrintOperatorPrivilege</term> + <listitem><para> + This privilege operates identically to the + <smbconfoption name="printer admin"/> + option in the &smb.conf; file (see section 5 man page for &smb.conf;) + except that it is a global right (not on a per printer basis). + Eventually the smb.conf option will be deprecated and administrative + rights to printers will be controlled exclusively by this right and + the security descriptor associated with the printer object in the + <filename>ntprinters.tdb</filename> file. + </para></listitem> + </varlistentry> + + <varlistentry><term>SeRemoteShutdownPrivilege</term> + <listitem><para> + Samba provides two hooks for shutting down or rebooting + the server and for aborting a previously issued shutdown + command. Since this is an operation normally limited by + the operating system to the root user, an account must possess this + right to be able to execute either of these hooks to have any effect. + </para></listitem> + </varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1> +<title>The Administrator Domain SID</title> + +<para> +Please note that when configured as a DC, it is now required +that an account in the server's passdb backend be set to the +domain SID of the default Administrator account. To obtain the +domain SID on a Samba DC, run the following command: + +<screen> +&rootprompt; net getlocalsid +SID for domain FOO is: S-1-5-21-4294955119-3368514841-2087710299 +</screen> +You may assign the Domain Administrator rid to an account using the <command>pdbedit</command> +command as shown here: +<screen> +&rootprompt; pdbedit -U S-1-5-21-4294955119-3368514841-2087710299-500 -u root -r +</screen> +</para> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-SWAT.xml b/docs/Samba3-HOWTO/TOSHARG-SWAT.xml new file mode 100644 index 0000000000..349312d61a --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-SWAT.xml @@ -0,0 +1,606 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="SWAT"> +<chapterinfo> + &author.jht; + <pubdate>April 21, 2003</pubdate> +</chapterinfo> + +<title>SWAT &smbmdash; The Samba Web Administration Tool</title> + +<para> +There are many and varied opinions regarding the usefulness of SWAT. +No matter how hard one tries to produce the perfect configuration tool, it remains +an object of personal taste. SWAT is a tool that will allow Web-based configuration +of Samba. It has a wizard that may help to get Samba configured +quickly, it has context-sensitive help on each &smb.conf; parameter, it provides for monitoring of current state +of connection information, and it allows network-wide MS Windows network password +management. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +SWAT is a facility that is part of the Samba suite. The main executable is called +<command>swat</command> and is invoked by the inter-networking super daemon. +See <link linkend="xinetd">appropriate section</link> for details. +</para> + +<para> +SWAT uses integral samba components to locate parameters supported by the particular +version of Samba. Unlike tools and utilities that are external to Samba, SWAT is always +up to date as known Samba parameters change. SWAT provides context-sensitive help for each +configuration parameter, directly from <command>man</command> page entries. +</para> + +<para> +There are network administrators who believe that it is a good idea to write systems +documentation inside configuration files, and for them SWAT will always be a nasty tool. SWAT +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, +as well as parameters that are no longer supported, will be lost from the &smb.conf; file. +Additionally, the parameters will be written back in internal ordering. +</para> + +<note><para> +Before using SWAT, please be warned &smbmdash; SWAT will completely replace your &smb.conf; with +a fully-optimized file that has been stripped of all comments you might have placed there +and only non-default settings will be written to the file. +</para></note> + +</sect1> + +<sect1> +<title>Guidelines and Technical Tips</title> + +<para> +This section aims to unlock the dark secrets behind how SWAT may be made to work, +may be made more secure, and how to solve Internationalization support problems. +</para> + +<sect2> +<title>Validate SWAT Installation</title> + +<para> +The very first step that should be taken before attempting to configure a host +system for SWAT operation is to check that it is installed. This may seem a trivial +point to some, however several Linux distributions do not install SWAT by default, +even though they do ship an install-able binary support package containing SWAT +on the distribution media. +</para> + +<para> +When you have confirmed that SWAT is installed it is necessary to validate +that the installation includes the binary <command>swat</command> file as well +as all the supporting text and Web files. A number of operating system distributions +in the past have failed to include the necessary support files, even though the +<command>swat</command> binary executable file was installed. +</para> + +<para> +Finally, when you are sure that SWAT has been fully installed, please check the SWAT +has been enabled in the control file for the inter-networking super-daemon (inetd or xinetd) +that is used on your operating system platform. +</para> + +<sect3> +<title>Locating the <command>swat</command> File</title> + +<para> +To validate that SWAT is installed, first locate the <command>swat</command> binary +file on the system. It may be found under the following directories: +<simplelist> + <member><filename>/usr/local/samba/bin</filename> &smbmdash; the default Samba location.</member> + <member><filename>/usr/sbin</filename> &smbmdash; the default location on most Linux systems.</member> + <member><filename>/opt/samba/bin</filename></member> +</simplelist> +</para> + +<para> +The actual location is much dependant on the choice of the operating system vendor, or as determined +by the administrator who compiled and installed Samba. +</para> + +<para> +There are a number methods that may be used to locate the <command>swat</command> binary file. +The following methods may be helpful: +</para> + +<para> +If <command>swat</command> is in your current operating system search path it will be easy to +find it. You can ask what are the command-line options for <command>swat</command> as shown here: +<screen> +frodo:~ # swat -? +Usage: swat [OPTION...] + -a, --disable-authentication Disable authentication (demo mode) + +Help options: + -?, --help Show this help message + --usage Display brief usage message + +Common samba options: + -d, --debuglevel=DEBUGLEVEL Set debug level + -s, --configfile=CONFIGFILE Use alternative configuration file + -l, --log-basename=LOGFILEBASE Basename for log/debug files + -V, --version Print version +</screen> +</para> + +</sect3> + +<sect3> +<title>Locating the SWAT Support Files</title> + +<para> +Now that you have found that <command>swat</command> is in the search path, it is easy +to identify where the file is located. Here is another simple way this may be done: +<screen> +frodo:~ # whereis swat +swat: /usr/sbin/swat /usr/share/man/man8/swat.8.gz +</screen> +</para> + +<para> +If the above measures fail to locate the <command>swat</command> binary, another approach +is needed. The following may be used: +<screen> +frodo:/ # find / -name swat -print +/etc/xinetd.d/swat +/usr/sbin/swat +/usr/share/samba/swat +frodo:/ # +</screen> +</para> + +<para> +This list shows that there is a control file for <command>xinetd</command>, the internetwork +super-daemon that is installed on this server. The location of the SWAT binary file is +<filename>/usr/sbin/swat</filename>, and the support files for it are located under the +directory <filename>/usr/share/samba/swat</filename>. +</para> + +<para> +We must now check where <command>swat</command> expects to find its support files. This can +be done as follows: +<screen> +frodo:/ # strings /usr/sbin/swat | grep "/swat" +/swat/ +... +/usr/share/samba/swat +frodo:/ # +</screen> +</para> + +<para> +The <filename>/usr/share/samba/swat/</filename> entry shown in this listing is the location of the +support files. You should verify that the support files exist under this directory. A sample +list is as shown: +<screen> +jht@frodo:/> find /usr/share/samba/swat -print +/usr/share/samba/swat +/usr/share/samba/swat/help +/usr/share/samba/swat/lang +/usr/share/samba/swat/lang/ja +/usr/share/samba/swat/lang/ja/help +/usr/share/samba/swat/lang/ja/help/welcome.html +/usr/share/samba/swat/lang/ja/images +/usr/share/samba/swat/lang/ja/images/home.gif +... +/usr/share/samba/swat/lang/ja/include +/usr/share/samba/swat/lang/ja/include/header.nocss.html +... +/usr/share/samba/swat/lang/tr +/usr/share/samba/swat/lang/tr/help +/usr/share/samba/swat/lang/tr/help/welcome.html +/usr/share/samba/swat/lang/tr/images +/usr/share/samba/swat/lang/tr/images/home.gif +... +/usr/share/samba/swat/lang/tr/include +/usr/share/samba/swat/lang/tr/include/header.html +/usr/share/samba/swat/using_samba +... +/usr/share/samba/swat/images +/usr/share/samba/swat/images/home.gif +... +/usr/share/samba/swat/include +/usr/share/samba/swat/include/footer.html +/usr/share/samba/swat/include/header.html +jht@frodo:/> +</screen> +</para> + +<para> +If the files needed are not available it will be necessary to obtain and install them +before SWAT can be used. +</para> + +</sect3> +</sect2> + +<sect2 id="xinetd"> +<title>Enabling SWAT for Use</title> + +<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 <command>inetd</command>- or +<command>xinetd</command>-based system. +</para> + +<para> +The nature and location of the network super-daemon varies with the operating system +implementation. The control file (or files) can be located in the file +<filename>/etc/inetd.conf</filename> or in the directory <filename>/etc/[x]inet[d].d</filename> +or similar. +</para> + +<para> +The control entry for the older style file might be: +<indexterm><primary>swat</primary><secondary>enable</secondary></indexterm> +</para> + + +<para><programlisting> + # swat is the Samba Web Administration Tool + swat stream tcp nowait.400 root /usr/sbin/swat swat +</programlisting></para> + +<para> +A control file for the newer style xinetd could be: +</para> + +<para> + <smbfile name="xinetd.swat"> +<programlisting> +# default: off +# description: SWAT is the Samba Web Admin Tool. Use swat \ +# to configure your Samba server. To use SWAT, \ +# connect to port 901 with your favorite web browser. +service swat +{ + port = 901 + socket_type = stream + wait = no + only_from = localhost + user = root + server = /usr/sbin/swat + log_on_failure += USERID + disable = no +} +</programlisting> +</smbfile> +In the above, the default setting for <parameter>disable</parameter> is <constant>yes</constant>. +This means that SWAT is disabled. To enable use of SWAT, set this parameter to <constant>no</constant> +as shown. +</para> + +<para> +Both of 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 its Help files +as well as other control information. The default location for this on most Linux +systems is in the directory <filename>/usr/share/samba/swat</filename>. The default +location using Samba defaults will be <filename>/usr/local/samba/swat</filename>. +</para> + +<para> +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: <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> +As 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 include: +<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> + +<sect2> +<title>Securing SWAT through SSL</title> + + +<para> +<indexterm><primary>swat</primary><secondary>security</secondary></indexterm> +Many people have asked about how to setup SWAT with SSL to allow for secure remote +administration of Samba. Here is a method that works, courtesy of Markus Krieger. +</para> + +<para> +Modifications to the SWAT setup are as follows: +</para> + +<procedure> + <step><para> + Install OpenSSL. + </para></step> + + <step><para> + Generate certificate and private key. + +<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> + + <step><para> + Remove swat-entry from [x]inetd. + </para></step> + + <step><para> + Start <command>stunnel</command>. + +<screen> +&rootprompt;<userinput>stunnel -p /etc/stunnel/stunnel.pem -d 901 \ + -l /usr/local/samba/bin/swat swat </userinput> +</screen></para></step> +</procedure> + +<para> +Afterward, simply connect to swat by using the URL <ulink noescape="1" url="https://myhost:901">https://myhost:901</ulink>, accept the certificate +and the SSL connection is up. +</para> + +</sect2> + +<sect2> +<title>Enabling SWAT Internationalization Support</title> + +<para> +SWAT can be configured to display its messages to match the settings of +the language configurations of your Web browser. It will be passed to SWAT +in the Accept-Language header of the HTTP request. +</para> + +<para> +To enable this feature: +</para> + +<itemizedlist> + <listitem><para> + Install the proper <command>msg</command> files from the Samba + <filename>source/po</filename> directory into $LIBDIR. + </para></listitem> + + <listitem><para> + Set your browsers language setting. + </para></listitem> +</itemizedlist> + +<para> +The name of msg file is same as the language ID sent by the browser. For +example en means "English", ja means "Japanese", fr means "French. +</para> + +<para> +If you do not like some of messages, or there are no <command>msg</command> files for +your locale, you can create them simply by copying the <command>en.msg</command> files +to the directory for <quote>your language ID.msg</quote> and filling in proper strings +to each <quote>msgstr</quote>. For example, in <filename>it.msg</filename>, the +<command>msg</command> file for the Italian locale, just set: +<screen> +msgid "Set Default" +msgstr "Imposta Default" +</screen> +and so on. If you find a mistake or create a new <command>msg</command> file, please email it +to us so we will include this in the next release of Samba. The <command>msg</command> file should be encoded in UTF-8. +</para> + +<para> +Note that if you enable this feature and the <smbconfoption name="display charset"/> is not +matched to your browsers setting, the SWAT display may be corrupted. In a future version of +Samba, SWAT will always display messages with UTF-8 encoding. You will then not need to set +this &smb.conf; file parameter. +</para> + +</sect2> + +</sect1> + +<sect1> +<title>Overview and Quick Tour</title> + +<para> +SWAT is a tools that many be used to configure Samba, or just to obtain useful links +to important reference materials such as the contents of this book, as well as other +documents that have been found useful for solving Windows networking problems. +</para> + +<sect2> +<title>The SWAT Home Page</title> + +<para> +The SWAT title page provides access to the latest Samba documentation. The manual page for +each Samba component is accessible from this page, as are the Samba HOWTO-Collection (this +document) as well as the O'Reilly book <quote>Using Samba.</quote> +</para> + +<para> +Administrators who wish to validate their Samba configuration may obtain useful information +from the man pages for the diagnostic utilities. These are available from the SWAT home page +also. One diagnostic tool that is not mentioned on this page, but that is particularly +useful is <ulink url="http://www.ethereal.com/"><command>ethereal</command>.</ulink> +</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. Allows +changes to &smb.conf; as well as general operation with root privileges. The option that +creates this ability is the <option>-a</option> flag to swat. <emphasis>Do not use this in a +production environment.</emphasis> +</para></warning> + +</sect2> + +<sect2> +<title>Global Settings</title> + +<para> +The <guibutton>GLOBALS</guibutton> button will expose a page that allows configuration of the global parameters +in &smb.conf;. There are two levels of exposure of the parameters: +</para> + +<itemizedlist> + <listitem><para> + <guibutton>Basic</guibutton> &smbmdash; exposes common configuration options. + </para></listitem> + + <listitem><para> + <guibutton>Advanced</guibutton> &smbmdash; exposes configuration options needed in more + complex environments. + </para></listitem> +</itemizedlist> + +<para> +To switch to other than <guibutton>Basic</guibutton> editing ability, click on <guibutton>Advanced</guibutton>. +You may also do this by clicking on the radio button, then click on the <guibutton>Commit Changes</guibutton> button. +</para> + +<para> +After making any changes to configuration parameters, make sure that +you click on the +<guibutton>Commit Changes</guibutton> button before moving to another area, otherwise +your changes will be lost. +</para> + +<note><para> +SWAT has context-sensitive help. To find out what each parameter is +for, simply click on the +<guibutton>Help</guibutton> link to the left of the configuration parameter. +</para></note> + +</sect2> + +<sect2> +<title>Share Settings</title> + +<para> +To effect a currently configured share, simply click on the pull down button between the +<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 +<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 labeled <guibutton>Create Share</guibutton> enter +into the text field the name of the share to be created, then click on the +<guibutton>Create Share</guibutton> button. +</para> + +</sect2> + +<sect2> +<title>Printers Settings</title> + +<para> +To affect a currently configured printer, simply click on the pull down button between the +<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 +<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 labeled <guibutton>Create Printer</guibutton> enter +into the text field the name of the share to be created, then click on the +<guibutton>Create Printer</guibutton> button. +</para> + +</sect2> + +<sect2> +<title>The SWAT Wizard</title> + +<para> +The purpose if the SWAT Wizard is to help the Microsoft-knowledgeable network administrator +to configure Samba with a minimum of effort. +</para> + +<para> +The Wizard page provides a tool for rewriting the &smb.conf; file in fully optimized format. +This will also happen if you press the <guibutton>Commit</guibutton> button. The two differ +since the <guibutton>Rewrite</guibutton> button ignores any changes that may have been made, +while the <guibutton>Commit</guibutton> button causes all changes to be affected. +</para> + +<para> +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> + +<para> +Finally, there are a limited set of options that will determine what type of server Samba +will be configured for, whether it will be a WINS server, participate as a WINS client, or +operate with no WINS support. By clicking one button, you can elect to expose (or not) user +home directories. +</para> + +</sect2> + +<sect2> +<title>The Status Page</title> + +<para> +The status page serves a limited purpose. First, it allows control of the Samba daemons. +The key daemons that create the Samba server environment are: &smbd;, &nmbd;, &winbindd;. +</para> + +<para> +The daemons may be controlled individually or as a total group. Additionally, you may set +an automatic screen refresh timing. As MS Windows clients interact with Samba, new smbd processes +will be continually spawned. The auto-refresh facility will allow you to track the changing +conditions with minimal effort. +</para> + +<para> +Lastly, the Status page may be used to terminate specific smbd client connections in order to +free files that may be locked. +</para> + +</sect2> + +<sect2> +<title>The View Page</title> + +<para> +This page allows the administrator to view the optimized &smb.conf; file and, if you are +particularly masochistic, will permit you also to see all possible global configuration +parameters and their settings. +</para> + +</sect2> + +<sect2> +<title>The Password Change Page</title> + +<para> +The Password Change page is a popular tool that allows the creation, deletion, deactivation, +and reactivation of MS Windows networking users on the local machine. Alternately, you can use +this tool to change a local password for a user account. +</para> + +<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 <emphasis>root</emphasis>, only the new password is +required. +</para> + +<para> +One popular use for this tool is to change user passwords across a range of remote MS Windows +servers. +</para> + +</sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-SecureLDAP.xml b/docs/Samba3-HOWTO/TOSHARG-SecureLDAP.xml new file mode 100644 index 0000000000..2fa4423d37 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-SecureLDAP.xml @@ -0,0 +1,390 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="ch-ldap-tls"> +<title>Transport Layer Security</title> + +<sect1 id="s1-intro-ldap-tls"> +<title>Introduction</title> + + <para> + <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Introduction</secondary></indexterm> + Up until now, we have discussed the straight forward configuration of <trademark>OpenLDAP</trademark>, + with some advanced features such as ACLs. This does not however, deal with the fact that the network + transmissions are still in plain text. This is where <firstterm>Transport Layer Security (TLS)</firstterm> + comes in. + </para> + + <para> + <trademark>OpenLDAP</trademark> clients and servers are capable of using the Transport Layer Security (TLS) + framework to provide integrity and confidentiality protections in accordance with - <ulink + url="http://rfc.net/rfc2830.html">RFC2830</ulink>; <emphasis>Lightweight Directory Access Protocol (v3): + Extension for Transport Layer Security.</emphasis> + </para> + + <para> + TLS uses X.509 certificates. All servers are required to have valid certificates, whereas client certificates + are optional. We will only be discussing server certificates. + </para> + + <tip><para> + The DN of a server certificate must use the CN attribute to name the server, and the CN must carry the + server's fully qualified domain name (FQDN). Additional alias names and wildcards may be present in the + <option>subjectAltName</option> certificate extension. More details on server certificate names are in <ulink + url="http://rfc.net/rfc2830.html">RFC2830</ulink>. + </para></tip> + + <para> + We will discuss this more in the next sections. + </para> + + </sect1> + + <sect1 id="s1-config-ldap-tls"> + <title>Configuring</title> + + <para> + <indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Configuring</secondary></indexterm> + Now on to the good bit. + </para> + + <sect2 id="s1-config-ldap-tls-certs"> + <title>Generating the Certificate Authority</title> + + <para> + In order to create the relevant certificates, we need to become our own Certificate Authority (CA). + <footnote><para>We could however, get our generated server certificate signed by proper CAs, like <ulink + url="http://www.thawte.com/">Thawte</ulink> and <ulink url="http://www.verisign.com/">VeriSign</ulink>, which + you pay for, or the free ones, via <ulink url="http://www.cacert.org/">CAcert</ulink> + </para></footnote> This is necessary, so we can sign the server certificate. + </para> + + <para> + We will be using the <ulink url="http://www.openssl.org">OpenSSL</ulink> <footnote><para>The downside to + making our own CA, is that the certificate is not automatically recognised by clients, like the commercial + ones are.</para></footnote> software for this, which is included with every great <trademark + class="registered">Linux</trademark> distribution. + </para> + + <para> + TLS is used for many types of servers, but the instructions<footnote><para>For information straight from the + horses mouth, please visit - <ulink + url="http://www.openssl.org/docs/HOWTO/">http://www.openssl.org/docs/HOWTO/</ulink>; the main OpenSSL + site.</para></footnote> presented here, are tailored for &OL;. + </para> + + <note><para> + The <emphasis>Common Name (CN)</emphasis>, if the following example, <emphasis>MUST</emphasis> be + the fully qualified domain name (fqdn) of your ldap server. + </para></note> + + <para> + First we need to generate the CA: +<screen width="90"> +<computeroutput> +&rootprompt; mkdir myCA +</computeroutput> +</screen> + Move into that directory: +<screen width="90"> +<computeroutput> +&rootprompt; cd myCA +</computeroutput> +</screen> + Now generate the CA:<footnote><para>Your <filename>CA.pl</filename> or <filename>CA.sh</filename> might not be + in the same location as mine is, you can find it by using the <command>locate</command> command, i.e. + <command>locate CA.pl</command>. If the command complains about the database being too old, run + <command>updatedb</command> as <emphasis>root</emphasis> to update it.</para></footnote> +<screen width="90"> +<computeroutput> +&rootprompt; /usr/share/ssl/misc/CA.pl -newca +CA certificate filename (or enter to create) + +Making CA certificate ... +Generating a 1024 bit RSA private key +.......................++++++ +.............................++++++ +writing new private key to './demoCA/private/cakey.pem' +Enter PEM pass phrase: +Verifying - Enter PEM pass phrase: +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:AU +State or Province Name (full name) [Some-State]:NSW +Locality Name (eg, city) []:Sydney +Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas +Organizational Unit Name (eg, section) []:IT +Common Name (eg, YOUR name) []:ldap.abmas.biz +Email Address []:support@abmas.biz +</computeroutput> +</screen> + </para> + + <para> + Now, there are some things to note here. + </para> + + <orderedlist> + <listitem> + <para> + You <emphasis>MUST</emphasis> remember the password, as we will need + it to sign the server certificate.. + </para> + </listitem> + + <listitem> + <para> + The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be the + fully qualified domain name (fqdn) of your ldap server. + </para> + </listitem> + </orderedlist> + + </sect2> + + <sect2 id="s1-config-ldap-tls-server"> + <title>Generating the Server Certificate</title> + + <para> + Now we need to generate the server certificate: +<screen width="90"> +<computeroutput> +&rootprompt; openssl req -new -nodes -keyout newreq.pem -out newreq.pem +Generating a 1024 bit RSA private key +.............++++++ +........................................................++++++ +writing new private key to 'newreq.pem' +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:AU +State or Province Name (full name) [Some-State]:NSW +Locality Name (eg, city) []:Sydney +Organization Name (eg, company) [Internet Widgits Pty Ltd]:Abmas +Organizational Unit Name (eg, section) []:IT +Common Name (eg, YOUR name) []:ldap.abmas.biz +Email Address []:support@abmas.biz + +Please enter the following 'extra' attributes +to be sent with your certificate request +A challenge password []: +An optional company name []: +</computeroutput> +</screen> + </para> + + <para> + Again, there are some things to note here. + </para> + + <orderedlist> + <listitem> + <para> + You should <emphasis>NOT</emphasis> enter a password. + </para> + </listitem> + + <listitem> + <para> + The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be + the fully qualified domain name (fqdn) of your ldap server. + </para> + </listitem> + </orderedlist> + + <para> + Now, we sign the certificate with the new CA: +<screen width="90"> +<computeroutput> +&rootprompt; /usr/share/ssl/misc/CA.pl -sign +Using configuration from /etc/ssl/openssl.cnf +Enter pass phrase for ./demoCA/private/cakey.pem: +Check that the request matches the signature +Signature ok +Certificate Details: +Serial Number: 1 (0x1) +Validity + Not Before: Mar 6 18:22:26 2005 EDT + Not After : Mar 6 18:22:26 2006 EDT +Subject: + countryName = AU + stateOrProvinceName = NSW + localityName = Sydney + organizationName = Abmas + organizationalUnitName = IT + commonName = ldap.abmas.biz + emailAddress = support@abmas.biz +X509v3 extensions: + X509v3 Basic Constraints: + CA:FALSE + Netscape Comment: + OpenSSL Generated Certificate + X509v3 Subject Key Identifier: + F7:84:87:25:C4:E8:46:6D:0F:47:27:91:F0:16:E0:86:6A:EE:A3:CE + X509v3 Authority Key Identifier: + keyid:27:44:63:3A:CB:09:DC:B1:FF:32:CC:93:23:A4:F1:B4:D5:F0:7E:CC + DirName:/C=AU/ST=NSW/L=Sydney/O=Abmas/OU=IT/CN=ldap.abmas.biz/emailAddress=support@abmas.biz + serial:00 + +Certificate is to be certified until Mar 6 18:22:26 2006 EDT (365 days) +Sign the certificate? [y/n]:y + + +1 out of 1 certificate requests certified, commit? [y/n]y +Write out database with 1 new entries +Data Base Updated +Signed certificate is in newcert.pem +</computeroutput> +</screen> + </para> + + <para> + That completes the server certificate generation. + </para> + + </sect2> + + <sect2 id="s1-config-ldap-tls-install"> + <title>Installing the Certificates</title> + + <para> + Now we need to copy the certificates to the right configuration directories, + rename them at the same time for convenience, change the ownership and + finally the permissions: +<screen width="90"> +<computeroutput> +&rootprompt; cp demoCA/cacert.pem /etc/openldap/ +&rootprompt; cp newcert.pem /etc/openldap/servercrt.pem +&rootprompt; cp newreq.pem /etc/openldap/serverkey.pem +&rootprompt; chown ldap.ldap /etc/openldap/*.pem +&rootprompt; chmod 640 /etc/openldap/cacert.pem; chmod 600 /etc/openldap/serverkey.pem +</computeroutput> +</screen> + </para> + + <para> + Now we just need to add these locations to <filename>slapd.conf</filename>, + anywhere before the <option>database</option> declaration as shown here: +<screen width="90"> +<computeroutput> +TLSCertificateFile /etc/openldap/servercrt.pem +TLSCertificateKeyFile /etc/openldap/serverkey.pem +TLSCACertificateFile /etc/openldap/cacert.pem +</computeroutput> +</screen> + </para> + + <para> + Here is the declaration and <filename>ldap.conf</filename>: +<filename>ldap.conf</filename> +<screen width="90"> +<computeroutput> +TLS_CACERT /etc/openldap/cacert.pem +</computeroutput> +</screen> + </para> + + <para> + That's all there is to it. Now on to <xref linkend="s1-test-ldap-tls"></xref> + </para> + + </sect2> + +</sect1> + +<sect1 id="s1-test-ldap-tls"> +<title>Testing</title> + +<para> +<indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Testing</secondary></indexterm> +This is the easy part. Restart the server: +<screen width="90"> +<computeroutput> +&rootprompt; /etc/init.d/ldap restart +Stopping slapd: [ OK ] +Checking configuration files for slapd: config file testing succeeded +Starting slapd: [ OK ] +</computeroutput> +</screen> + Then, using <command>ldapsearch</command>, test an anonymous search with the + <option>-ZZ</option><footnote><para>See <command>man ldapsearch</command></para></footnote> option: +<screen width="90"> +<computeroutput> +&rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" -H 'ldap://ldap.abmas.biz:389' -ZZ +</computeroutput> +</screen> + Your results should be the same as before you restarted the server, for example: +<screen width="90"> +<computeroutput> +&rootprompt; ldapsearch -x -b "dc=ldap,dc=abmas,dc=biz" \ + -H 'ldap://ldap.abmas.biz:389' -ZZ + +# extended LDIF +# +# LDAPv3 +# base <> with scope sub +# filter: (objectclass=*) +# requesting: ALL +# + +# abmas.biz +dn: dc=ldap,dc=abmas,dc=biz +objectClass: dcObject +objectClass: organization +o: Abmas +dc: abmas + +# Manager, ldap.abmas.biz +dn: cn=Manager,dc=ldap,dc=abmas,dc=biz +objectClass: organizationalRole +cn: Manager + +# ABMAS, abmas.biz +dn: sambaDomainName=ABMAS,dc=ldap,dc=abmas,dc=biz +sambaDomainName: ABMAS +sambaSID: S-1-5-21-238355452-1056757430-1592208922 +sambaAlgorithmicRidBase: 1000 +objectClass: sambaDomain +sambaNextUserRid: 67109862 +sambaNextGroupRid: 67109863 +</computeroutput> +</screen> + If you have any problems, please read <xref linkend="s1-int-ldap-tls"></xref> +</para> + +</sect1> + +<sect1 id="s1-int-ldap-tls"> +<title>Troubleshooting</title> + +<para> +<indexterm><primary>Transport Layer Seccurity, TLS</primary><secondary>Troubleshooting</secondary></indexterm> +The most common error when configuring TLS, as I have already mentioned numerous times, is that the +<emphasis>Common Name (CN)</emphasis> you entered in <xref linkend="s1-config-ldap-tls-server"></xref> is +<emphasis>NOT</emphasis> the Full Qualified Domain Name (FQDN) of your ldap server. +</para> + +<para> +Other errors could be that you have a typo somewhere in your <command>ldapsearch</command> command, or that +your have the wrong permissions on the <filename>servercrt.pem</filename> and <filename>cacert.pem</filename> +files. They should be set with <command>chmod 640</command>, as per <xref +linkend="s1-config-ldap-tls-install"></xref>. +</para> + +<para> +For anything else, it's best to read through your ldap logfile or join the &OL; mailing list. +</para> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Securing.xml b/docs/Samba3-HOWTO/TOSHARG-Securing.xml new file mode 100644 index 0000000000..b8d65c08ae --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Securing.xml @@ -0,0 +1,366 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="securing-samba"> + +<chapterinfo> + &author.tridge; + &author.jht; + <pubdate>May 26, 2003</pubdate> +</chapterinfo> + +<title>Securing Samba</title> + +<sect1> +<title>Introduction</title> +<para> +This note was attached to the Samba 2.2.8 release notes as it contained an +important security fix. The information contained here applies to Samba +installations in general. +</para> + +<blockquote> +<para> +A new apprentice reported for duty to the chief engineer of a boiler house. He said, <quote>Here I am, +if you will show me the boiler I'll start working on it.</quote> Then engineer replied, <quote>You're leaning +on it!</quote> +</para> +</blockquote> + +<para> +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>Features and Benefits</title> + +<para> +There are three levels at which security principals must be observed in order to render a site +at least moderately secure. They are the perimeter firewall, the configuration of the host +server that is running Samba and Samba itself. +</para> + +<para> +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> + +<para> +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 <quote>tcpwrappers,</quote> or it may be done be using <emphasis>interface-based exclusion</emphasis> +so &smbd; will bind only to specifically permitted interfaces. It is also +possible to set specific share or resource-based exclusions, for example on the <smbconfsection name="[IPC$]"/> +auto-share. The <smbconfsection name="[IPC$]"/> share is used for browsing purposes as well as to establish +TCP/IP connections. +</para> + +<para> +Another method by which Samba may be secured is by setting Access Control Entries (ACEs) in an Access +Control List (ACL) on the shares themselves. This is discussed in <link linkend="AccessControls">File, Directory and Share Access Controls</link>. +</para> + +</sect1> + +<sect1> +<title>Technical Discussion of Protective Measures and Issues</title> + +<para> +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 from 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 <smbconfoption name="hosts allow"/> and + <smbconfoption name="hosts deny"/> 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><smbconfblock> +<smbconfoption name="hosts allow">127.0.0.1 192.168.2.0/24 192.168.3.0/24</smbconfoption> +<smbconfoption name="hosts deny">0.0.0.0/0</smbconfoption> + </smbconfblock></para> + + <para> + The above will only allow SMB connections from <constant>localhost</constant> (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 <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; <smbconfsection name="[global]"/> section put: + </para> + + <para><smbconfblock> +<smbconfoption name="valid users">@smbusers, jacko</smbconfoption> + </smbconfblock></para> + + <para> + This 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 behavior using options like this: + </para> + + <para><smbconfblock> +<smbconfoption name="interfaces">eth* lo</smbconfoption> +<smbconfoption name="bind interfaces only">yes</smbconfoption> + </smbconfblock></para> + + <para> + This tells Samba to only listen for connections on interfaces with a + name starting with <constant>eth</constant> such as <constant>eth0, eth1</constant> plus on the loopback + interface called <constant>lo</constant>. 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 an SMB connection to + your host over a PPP interface called <constant>ppp0,</constant> 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 they do not + want exposed outside their network. This can be a good idea, + although I recommend using it in conjunction with the above + methods so you are protected even if your firewall is not active + for some reason. + </para> + + <para> + If you are setting up a firewall, 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 IPC$ Share-Based Denials </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 un-trustworthy + hosts. + </para> + + <para> + To do this you could use: + </para> + + <para><smbconfblock> +<smbconfsection name="[IPC$]"/> +<smbconfoption name="hosts allow">192.168.115.0/24 127.0.0.1</smbconfoption> +<smbconfoption name="hosts deny">0.0.0.0/0</smbconfoption> + </smbconfblock></para> + + <para> + This instructs Samba that IPC$ connections are not allowed from + anywhere except from the two listed network addresses (localhost and the 192.168.115 + subnet). Connections to other shares are still 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 valid username/password for your host. + </para> + + <para> + If you use this method, then clients will be given an <errorname>`access denied'</errorname> + reply when they try to access the IPC$ share. Those clients will not be able to + browse shares, and may also be unable to access some other resources. 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> + + <para> + <screen> + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa] + "lmcompatibilitylevel"=dword:00000003 + </screen> + </para> + + <para> + The value 0x00000003 means 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. + </para> + + <para> + <screen> + [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0] + "NtlmMinClientSec"=dword:00080000 + </screen> + </para> + + <para> + The value 0x00080000 means permit only NTLMv2 session security. If either NtlmMinClientSec or + NtlmMinServerSec is set to 0x00080000, the connection will fail if NTLMv2 + session security is not negotiated. + </para> + </sect2> +</sect1> + +<sect1> +<title>Upgrading Samba</title> + +<para> +Please check regularly on <ulink noescape="1" 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. Check with your OS vendor for OS specific upgrades. +</para> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +If all of Samba and host platform configuration were really as intuitive as one might like them to be, 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 the reason that most administrators who post what turns +out to be a security problem request are totally convinced that the problem is with Samba. +</para> + + <sect2> + <title>Smbclient Works on Localhost, but the Network Is Dead</title> + + <para> + This is a common problem. Red Hat Linux (and others) installs a default firewall. + With the default firewall in place, only traffic on the loopback adapter (IP address 127.0.0.1) + is allowed through the firewall. + </para> + + <para> + The solution is either to remove the firewall (stop it) or 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 to configure + Samba so that users may map only their own home directory. + </quote> + </para> + + <para><quote> + User xyzzy can map his home directory. Once mapped user xyzzy can also map + anyone else's 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 file system as when 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> + If your UNIX home directories are set up so that one user can happily <command>cd</command> + into another users directory and execute <command>ls</command>, the UNIX security solution is to change file + permissions on the user's home directories such that the <command>cd</command> and <command>ls</command> are 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 allows the behavior you require. Simply put the <smbconfoption name="only user">%S</smbconfoption> + option in the <smbconfsection name="[homes]"/> share definition. + </para> + + <para> + The <smbconfoption name="only user"></smbconfoption> works in conjunction with the <smbconfoption name="users">list</smbconfoption>, + so to get the behavior you require, add the line : + <smbconfblock> +<smbconfoption name="users">%S</smbconfoption> +</smbconfblock> + this is equivalent to adding + <smbconfblock> +<smbconfoption name="valid users">%S</smbconfoption> + </smbconfblock> + to the definition of the <smbconfsection name="[homes]"/> share, as recommended in + the &smb.conf; man page. + </para> + </sect2> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-ServerType.xml b/docs/Samba3-HOWTO/TOSHARG-ServerType.xml new file mode 100644 index 0000000000..cd7f578cc0 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-ServerType.xml @@ -0,0 +1,643 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="ServerType"> +<chapterinfo> + &author.tridge; + &author.jelmer; + &author.jht; +</chapterinfo> + +<title>Server Types and Security Modes</title> + +<para> +This chapter provides information regarding the types of server that Samba may be +configured to be. A Microsoft network administrator who wishes to migrate to or +use Samba will want to know the meaning, within a Samba context, of terms familiar to MS Windows +administrator. This means that it is essential also to define how critical security +modes function before we get into the details of how to configure the server itself. +</para> + +<para> +The chapter provides an overview of the security modes of which Samba is capable +and how they relate to MS Windows servers and clients. +</para> + +<para> +A question often asked is, <quote>Why would I want to use Samba?</quote> Most chapters contain a section +that highlights features and benefits. We hope that the information provided will help to +answer this question. Be warned though, we want to be fair and reasonable, so not all +features are positive towards Samba. The benefit may be on the side of our competition. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +Two men were walking down a dusty road, when one suddenly kicked up a small red stone. It +hurt his toe and lodged in his sandal. He took the stone out and cursed it with a passion +and fury befitting his anguish. The other looked at the stone and said, <quote>This is a garnet. +I can turn that into a precious gem and some day it will make a princess very happy!</quote> +</para> + +<para> +The moral of this tale: Two men, two very different perspectives regarding the same stone. +Like it or not, Samba is like that stone. Treat it the right way and it can bring great +pleasure, but if you are forced to use it and have no time for its secrets, then it can be +a source of discomfort. +</para> + +<para> +Samba started out as a project that sought to provide interoperability for MS Windows 3.x +clients with a UNIX server. It has grown up a lot since its humble beginnings and now provides +features and functionality fit for large scale deployment. It also has some warts. In sections +like this one we tell of both. +</para> + +<para> +So, what are the benefits of features mentioned in this chapter? +</para> + +<itemizedlist> + <listitem><para> + Samba-3 can replace an MS Windows NT4 Domain Controller. + </para></listitem> + + <listitem><para> + Samba-3 offers excellent interoperability with MS Windows NT4-style + domains as well as natively with Microsoft Active Directory domains. + </para></listitem> + + <listitem><para> + Samba-3 permits full NT4-style Interdomain Trusts. + </para></listitem> + + <listitem><para> + Samba has security modes that permit more flexible + authentication than is possible with MS Windows NT4 Domain Controllers. + </para></listitem> + + <listitem><para> + Samba-3 permits use of multiple account database backends. + </para></listitem> + + <listitem><para> + The account (password) database backends can be distributed + and replicated using multiple methods. This gives Samba-3 + greater flexibility than MS Windows NT4 and in many cases a + significantly higher utility than Active Directory domains + with MS Windows 200x. + </para></listitem> +</itemizedlist> + +</sect1> + +<sect1> +<title>Server Types</title> + + +<para> +<indexterm><primary>Server Type</primary></indexterm> +Administrators of Microsoft networks often refer to three +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> + </listitem> + <listitem><para>Domain Member Server</para> + <itemizedlist> + <listitem><para>Active Directory Domain Server</para></listitem> + <listitem><para>NT4 Style Domain Domain Server</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>Stand-alone Server</para></listitem> +</itemizedlist> + +<para> +The chapters covering Domain Control, Backup Domain Control and Domain Membership provide +pertinent information regarding Samba configuration for each of these server roles. +The reader is strongly encouraged to become intimately familiar with the information +presented. +</para> + +</sect1> + +<sect1> +<title>Samba Security Modes</title> + + +<para> +<indexterm><primary>Security Mode</primary></indexterm> +<indexterm><primary>security</primary></indexterm> +In this section the function and purpose of Samba's security +modes are described. An accurate 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. +</para> + +<para> +In the SMB/CIFS networking world, there are only two types of security: <emphasis>User Level</emphasis> +and <emphasis>Share Level</emphasis>. We refer to these collectively as <emphasis>security levels</emphasis>. +In implementing these two security levels, Samba provides flexibilities +that are not available with Microsoft Windows NT4/200x servers. In actual fact, Samba implements +<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>. They are known as: <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> +An SMB server tells the client at startup what security level it is running. There are two options: +Share Level and User Level. Which of these two the client receives affects the way the client then +tries to authenticate itself. It does not directly affect (to any great extent) the way the Samba +server does security. This may sound strange, but it fits in with the client/server approach of SMB. +In SMB everything is initiated and controlled by the client, and the server can only tell the client +what is available and whether an action is allowed. +</para> + +<sect2> +<title>User Level Security</title> + +<para> +We will describe User Level Security first, as its simpler. +In User Level Security, the client will send a +session setup request directly following protocol negotiation. +This request provides a username and password. The server can either accept or reject that +username/password combination. At this stage the server has no idea what +share the client will eventually try to connect to, so it can't base the +<emphasis>accept/reject</emphasis> on anything other than: +</para> + +<orderedlist> +<listitem><para>the username/password.</para></listitem> +<listitem><para>the name of the client machine.</para></listitem> +</orderedlist> + +<para> +If the server accepts the username/password then the client expects to be able to +mount shares (using a <emphasis>tree connection</emphasis>) without specifying a +password. It expects that all access rights will be as the username/password +specified in the <emphasis>session setup</emphasis>. +</para> + +<para> +It is also possible for a client to send multiple <emphasis>session setup</emphasis> +requests. When the server responds, it gives the client a <emphasis>uid</emphasis> to use +as an authentication tag for that username/password. The client can maintain multiple +authentication contexts in this way (WinDD is an example of an application that does this). +</para> + +<sect3> +<title>Example Configuration</title> + +<para> +The &smb.conf; parameter that sets user level security is: +</para> + +<para><smbconfblock> +<smbconfoption name="security">user</smbconfoption> +</smbconfblock></para> + +<para> +This is the default setting since Samba-2.2.x. +</para> + +</sect3> + +</sect2> +<sect2> +<title>Share Level Security</title> + +<para> +In Share Level security, the client authenticates +itself separately for each share. It sends a password along with each +tree connection (share mount). It does not explicitly send a +username with this operation. The client expects a password to be associated +with each share, independent of the user. This means that Samba has to work out what +username the client probably wants to use. It is never explicitly sent the username. +Some commercial SMB servers such as NT actually associate passwords directly with +shares in Share Level security, but Samba always uses the UNIX authentication scheme +where it is a username/password pair that is authenticated, not a share/password pair. +</para> + +<para> +To understand the MS Windows networking parallels, one should think +in terms of MS Windows 9x/Me where one can create a shared folder that provides read-only +or full access, with or without a password. +</para> + +<para> +Many clients send a session setup even if the server is in Share Level security. They +normally send a valid username but no password. Samba records this username in a list +of possible usernames. When the client then does a tree connection 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 <smbconfoption name="user"/> parameter in the &smb.conf; file. +The password is then checked in turn against these possible usernames. If a match is found +then the client is authenticated as that user. +</para> + +<sect3> +<title>Example Configuration</title> + +<para> +The &smb.conf; parameter that sets Share Level security is: +</para> + +<para><smbconfblock> +<smbconfoption name="security">share</smbconfoption> +</smbconfblock></para> + +</sect3> +</sect2> + +<sect2> +<title>Domain Security Mode (User Level Security)</title> + +<para> +<indexterm><primary>Domain Member</primary></indexterm> +When Samba is operating in <smbconfoption name="security">domain</smbconfoption> mode, +the Samba server has a domain security trust account (a machine account) and causes +all authentication requests to be passed through to the Domain Controllers. +In other words, this configuration makes the Samba server a Domain Member server. +</para> + +<sect3> +<title>Example Configuration</title> +<para><emphasis> +Samba as a Domain Member Server +</emphasis></para> + + +<para> +<indexterm><primary>Server Type</primary><secondary>Domain Member</secondary></indexterm> +This method involves addition of the following parameters in the &smb.conf; file: +</para> + +<para><smbconfblock> +<smbconfoption name="security">domain</smbconfoption> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +</smbconfblock></para> + +<para> +In order for this method to work, the Samba server needs to join the MS Windows NT +security domain. This is done as follows: +<indexterm><primary>net</primary><secondary>rpc</secondary></indexterm> +<indexterm><primary>Domain Member</primary><secondary>joining</secondary></indexterm> +</para> + + +<procedure> + <step><para>On the MS Windows NT Domain Controller, using + the Server Manager, add a machine account for the Samba server. + </para></step> + + <step><para>On the UNIX/Linux system execute:</para> + + <para><screen>&rootprompt;<userinput>net rpc join -U administrator%password</userinput></screen></para> + </step> +</procedure> + +<note><para> +Samba-2.2.4 and later can auto-join a Windows NT4-style Domain just by executing: +<screen> +&rootprompt;<userinput>smbpasswd -j <replaceable>DOMAIN_NAME</replaceable> -r <replaceable>PDC_NAME</replaceable> \ + -U Administrator%<replaceable>password</replaceable></userinput> +</screen> + +Samba-3 can do the same by executing: +<screen> +&rootprompt;<userinput>net rpc 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> +Use of this mode of authentication does require there to be a standard UNIX account +for each user in order to assign a UID once the account has been authenticated by +the remote Windows DC. This account can be blocked to prevent logons by clients other than +MS Windows through means such as setting an invalid shell in the +<filename>/etc/passwd</filename> entry. +</para> + +<para> +An alternative to assigning UIDs to Windows users on a Samba member server is +presented in <link linkend="winbind">Winbind: Use of Domain Accounts</link>. +</para> + +<para> +For more information regarding Domain Membership, see <link linkend="domain-member">Domain Membership</link>. +</para> + +</sect3> +</sect2> + +<sect2> +<title>ADS Security Mode (User Level Security)</title> + +<para> +Both Samba-2.2, and Samba-3 can join an Active Directory domain. This is +possible if the domain is run in native mode. Active Directory in +native mode perfectly allows NT4-style Domain Members. This is contrary to +popular belief. Active Directory in native mode prohibits only the use of +Backup Domain Controllers running MS Windows NT4. +</para> + +<para> +If you are using Active Directory, starting with Samba-3 you can +join as a native AD member. Why would you want to do that? +Your security policy might prohibit the use of NT-compatible +authentication protocols. All your machines are running Windows 2000 +and above and all use Kerberos. In this case Samba as an NT4-style +domain would still require NT-compatible authentication data. Samba in +AD-member mode can accept Kerberos tickets. +</para> + +<sect3> +<title>Example Configuration</title> + +<para><smbconfblock> +<smbconfoption name="realm">your.kerberos.REALM</smbconfoption> +<smbconfoption name="security">ADS</smbconfoption> +</smbconfblock></para> + +<para> +The following parameter may be required: +</para> + +<para><smbconfblock> +<smbconfoption name="password server">your.kerberos.server</smbconfoption> +</smbconfblock></para> + +<para> +Please refer to <link linkend="domain-member">Domain Membership</link> and <link linkend="ads-member">Samba ADS Domain Membership</link> +for more information regarding this configuration option. +</para> + +</sect3> +</sect2> + +<sect2> +<title>Server Security (User Level Security)</title> + +<para> +Server Security Mode is left over from the time when Samba was not capable of acting +as a Domain Member server. It is highly recommended not to use this feature. Server +security mode has many drawbacks that 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, which is 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> + +<para> +In Server Security Mode the Samba server reports to the client that it is in User Level +security. The client then does a session setup as described earlier. +The Samba server takes the username/password that the client sends and attempts to login to the +<smbconfoption name="password server"/> 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 client's connection. This allows the Samba server to use another SMB +server as the <smbconfoption name="password server"/>. +</para> + +<para> +You should also note that at the start of all this where the server tells the client +what security level it is in, it also tells the client if it supports encryption. If it +does, it supplies the client with a random cryptkey. The client will then send all +passwords in encrypted form. Samba supports this type of encryption by default. +</para> + +<para> +The parameter <smbconfoption name="security">server</smbconfoption> 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 <smbconfoption name="password server"/> that points to the real authentication server. +The real authentication server can be another Samba server, or it can be a Windows NT server, +the latter being natively capable of encrypted password support. +</para> + +<note><para> +When Samba is running in <emphasis>Server Security Mode</emphasis> it is essential that +the parameter <emphasis>password server</emphasis> is set to the precise NetBIOS machine +name of the target authentication server. Samba cannot determine this from NetBIOS name +lookups because the choice of the target authentication server is arbitrary and cannot +be determined from a domain name. In essence, a Samba server that is in +<emphasis>Server Security Mode</emphasis> is operating in what used to be known as +workgroup mode. +</para></note> + +<sect3> +<title>Example Configuration</title> +<para><emphasis> +Using MS Windows NT as an Authentication Server +</emphasis></para> + +<para> +This method involves the additions of the following parameters in the &smb.conf; file: +</para> + +<para><smbconfblock> +<smbconfoption name="encrypt passwords">Yes</smbconfoption> +<smbconfoption name="security">server</smbconfoption> +<smbconfoption name="password server">"NetBIOS_name_of_a_DC"</smbconfoption> +</smbconfblock></para> + + +<para> +There are two ways of identifying whether or not a username and password pair is valid. +One uses the reply information provided as part of the authentication messaging +process, the other uses just an error code. +</para> + +<para> +The downside of this mode of configuration is the fact that for security reasons Samba +will send the password server a bogus username and a bogus password and if the remote +server fails to reject the username and password pair then an alternative mode of +identification of validation is used. Where a site uses password lock out after a +certain number of failed authentication attempts this will result in user lockouts. +</para> + +<para> +Use of this mode of authentication requires a standard UNIX account for the user. +This account can be blocked to prevent logons by non-SMB/CIFS clients. +</para> + +</sect3> +</sect2> + +</sect1> + +<sect1> +<title>Password Checking</title> + +<para> +MS Windows clients may use encrypted passwords as part of a challenge/response +authentication model (a.k.a. NTLMv1 and NTLMv2) or alone, or clear-text strings for simple +password-based authentication. It should be realized that with the SMB protocol, +the password is passed over the network either in plain-text or encrypted, but +not both in the same authentication request. +</para> + +<para> +When encrypted passwords are used, a password that has been entered by the user +is encrypted in two ways: +</para> + +<itemizedlist> + <listitem><para>An MD4 hash of the unicode of the password + string. This is known as the NT hash. + </para></listitem> + + <listitem><para>The password is converted to upper case, + and then padded or truncated to 14 bytes. This string is + then appended with 5 bytes of NULL characters and split to + form two 56-bit DES keys to encrypt a <quote>magic</quote> 8-byte value. + The resulting 16 bytes form the LanMan hash. + </para></listitem> +</itemizedlist> + +<para> +MS Windows 95 pre-service pack 1, MS Windows NT versions 3.x and version 4.0 +pre-service pack 3 will use either mode of password authentication. All +versions of MS Windows that follow these versions no longer support plain +text passwords by default. +</para> + +<para> +MS Windows clients have a habit of dropping network mappings that have been idle +for 10 minutes or longer. When the user attempts to use the mapped drive +connection that has been dropped, the client re-establishes the connection using +a cached copy of the password. +</para> + +<para> +When Microsoft changed the default password mode, support was dropped for caching +of the plain-text password. This means that when the registry parameter is changed +to re-enable use of plain-text passwords it appears to work, but when a dropped +service connection mapping attempts to revalidate, this will fail if the remote +authentication server does not support encrypted passwords. It is definitely not +a good idea to re-enable plain-text password support in such clients. +</para> + +<para> +The following parameters can be used to work around the issue of Windows 9x/Me clients +upper-casing usernames and passwords before transmitting them to the SMB server +when using clear-text authentication: +</para> + +<para><smbconfblock> +<smbconfoption name="password level"><replaceable>integer</replaceable></smbconfoption> +<smbconfoption name="username level"><replaceable>integer</replaceable></smbconfoption> +</smbconfblock></para> + +<para> +By default Samba will convert to lower case the username before attempting to lookup the user +in the database of local system accounts. Because UNIX usernames conventionally +only contain lower-case characters, the <smbconfoption name="username level"/> parameter +is rarely needed. +</para> + +<para> +However, passwords on UNIX systems often make use of mixed-case characters. +This means that in order for a user on a Windows 9x/Me client to connect to a Samba +server using clear-text authentication, the <smbconfoption name="password level"/> +must be set to the maximum number of upper case letters that <emphasis>could</emphasis> +appear in a password. Note that if the server OS uses the traditional DES version +of crypt(), a <smbconfoption name="password level"/> of 8 will result in case +insensitive passwords as seen from Windows users. This will also result in longer +login times as Samba has to compute the permutations of the password string and +try them one by one until a match is located (or all combinations fail). +</para> + +<para> +The best option to adopt is to enable support for encrypted passwords wherever +Samba is used. Most attempts to apply the registry change to re-enable plain-text +passwords will eventually lead to user complaints and unhappiness. +</para> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +We all make mistakes. It is okay to make mistakes, as long as they are made in the right places +and at the right time. A mistake that causes lost productivity is seldom tolerated, however a mistake +made in a developmental test lab is expected. +</para> + +<para> +Here we look at common mistakes and misapprehensions that have been the subject of discussions +on the Samba mailing lists. Many of these are avoidable by doing your homework before attempting +a Samba implementation. Some are the result of a misunderstanding of the English language. The +English language, which has many phrases that are potentially vague and may be highly confusing +to those for whom English is not their native tongue. +</para> + +<sect2> +<title>What Makes Samba a Server?</title> + +<para> +To some the nature of the Samba <emphasis>security</emphasis> mode is obvious, but entirely +wrong all the same. It is assumed that <smbconfoption name="security">server</smbconfoption> means that Samba +will act as a server. Not so! This setting means that Samba will <emphasis>try</emphasis> +to use another SMB server as its source for user authentication alone. +</para> + +</sect2> + +<sect2> +<title>What Makes Samba a Domain Controller?</title> + +<para> +The &smb.conf; parameter <smbconfoption name="security">domain</smbconfoption> does not really make Samba behave +as a Domain Controller. This setting means we want Samba to be a Domain Member. See <link linkend="samba-pdc">Samba as a PDC</link> for more information. +</para> + +</sect2> + +<sect2> +<title>What Makes Samba a Domain Member?</title> + +<para> +Guess! So many others do. But whatever you do, do not think that <smbconfoption name="security">user</smbconfoption> +makes Samba act as a Domain Member. Read the manufacturer's manual before the warranty expires. See +<link linkend="domain-member">Domain Membership</link> for more information. +</para> + +</sect2> + + +<sect2> +<title>Constantly Losing Connections to Password Server</title> + +<para> + <quote> +Why does server_validate() simply give up rather than re-establish 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.</quote> +</para> + +<para> +Indeed. That's why <smbconfoption name="security">server</smbconfoption> +is at best a nasty hack. Please use <smbconfoption name="security">domain</smbconfoption>; +<smbconfoption name="security">server</smbconfoption> mode is also known as pass-through authentication. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Speed.xml b/docs/Samba3-HOWTO/TOSHARG-Speed.xml new file mode 100644 index 0000000000..1e74a22396 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Speed.xml @@ -0,0 +1,317 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="speed"> + +<chapterinfo> + <author> + <firstname>Paul</firstname><surname>Cochrane</surname> + <affiliation> + <orgname>Dundee Limb Fitting Centre</orgname> + <address><email>paulc@dth.scot.nhs.uk</email></address> + </affiliation> + </author> + &author.jelmer; + &author.jht; +</chapterinfo> + +<title>Samba Performance Tuning</title> + +<sect1> +<title>Comparisons</title> + +<para> +The Samba server uses TCP to talk to the client. Thus if you are +trying to see if it performs well, you should really compare it to +programs that use the same protocol. The most readily available +programs for file transfer that use TCP are ftp or another TCP-based +SMB server. +</para> + +<para> +If you want to test against something like an NT or Windows for Workgroups server, then +you will have to disable all but TCP on either the client or +server. Otherwise, you may well be using a totally different protocol +(such as NetBEUI) and comparisons may not be valid. +</para> + +<para> +Generally, you should find that Samba performs similarly to ftp at raw +transfer speed. It should perform quite a bit faster than NFS, +although this depends on your system. +</para> + +<para> +Several people have done comparisons between Samba and Novell, NFS or +Windows NT. In some cases Samba performed the best, in others the worst. I +suspect the biggest factor is not Samba versus some other system, but the +hardware and drivers used on the various systems. Given similar +hardware, Samba should certainly be competitive in speed with other +systems. +</para> + +</sect1> + +<sect1> +<title>Socket Options</title> + +<para> +There are a number of socket options that can greatly affect the +performance of a TCP-based server like Samba. +</para> + +<para> +The socket options that Samba uses are settable both on the command +line with the <option>-O</option> option, or in the &smb.conf; file. +</para> + +<para> +The <smbconfoption name="socket options"/> section of the &smb.conf; manual page describes how +to set these and gives recommendations. +</para> + +<para> +Getting the socket options correct can make a big difference to your +performance, but getting them wrong can degrade it by just as +much. The correct settings are very dependent on your local network. +</para> + +<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 +<?latex \linebreak ?><smbconfoption name="socket options">TCP_NODELAY</smbconfoption> +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> + +<para> +There have been reports that setting <parameter>socket options = SO_RCVBUF=8192</parameter> in smb.conf +can seriously degrade Samba performance on the loopback adaptor (IP Address 127.0.0.1). It is strongly +recommended that before specifying any settings for <parameter>socket options</parameter> the effect +first be quantitatively measured on the server being configured. +</para> + +</sect1> + +<sect1> +<title>Read Size</title> + +<para> +The option <smbconfoption name="read size"/> 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 +the data before it has received the whole packet from the network, or +in the case of SMBreadbraw, it begins writing to the network before +all the data has been read from disk. +</para> + +<para> +This overlapping works best when the speeds of disk and network access +are similar, having little effect when the speed of one is much +greater than the other. +</para> + +<para> +The default value is 16384, but little experimentation has been +done as yet to determine the optimal value, and it is likely that the best +value will vary greatly between systems anyway. A value over 65536 is +pointless and will cause you to allocate memory unnecessarily. +</para> + +</sect1> + +<sect1> +<title>Max Xmit</title> + +<para> + 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 <smbconfoption name="max xmit"/> 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 +honors this limit. +</para> + +<para> +It defaults to 65536 bytes (the maximum), but it is possible that some +clients may perform better with a smaller transmit unit. Trying values +of less than 2048 is likely to cause severe problems. +In most cases the default is the best option. +</para> + +</sect1> + +<sect1> +<title>Log Level</title> + +<para> +If you set the log level (also known as <smbconfoption name="debug level"/>) 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 quite +expensive. +</para> +</sect1> + +<sect1> +<title>Read Raw</title> + +<para> +The <smbconfoption name="read raw"/> operation is designed to be an optimized, low-latency +file read operation. A server may choose to not support it, +however, and Samba makes support for <smbconfoption name="read raw"/> optional, with it +being enabled by default. +</para> + +<para> +In some cases clients do not handle <smbconfoption name="read raw"/> 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 <smbconfoption name="read raw">no</smbconfoption> and see what happens on your +network. It might lower, raise or not effect your performance. Only +testing can really tell. +</para> + +</sect1> + +<sect1> +<title>Write Raw</title> + +<para> +The <smbconfoption name="write raw"/> operation is designed to be an optimized, low-latency +file write operation. A server may choose to not support it, however, and Samba makes support for +<smbconfoption name="write raw"/> optional, with it being enabled by default. +</para> + +<para> +Some machines may find <smbconfoption name="write raw"/> slower than normal write, in which +case you may wish to change this option. +</para> + +</sect1> + +<sect1> +<title>Slow Logins</title> + +<para> +Slow logins are almost always due to the password checking time. Using +the lowest practical <smbconfoption name="password level"/> will improve things. +</para> + +</sect1> + +<sect1> +<title>Client Tuning</title> + +<para> +Often a speed problem can be traced to the client. The client (for +example Windows for Workgroups) can often be tuned for better TCP +performance. Check the sections on the various clients in +<link linkend="Other-Clients">Samba and Other CIFS Clients</link>. +</para> + +</sect1> + +<sect1> +<title>Samba Performance Problem Due to Changing Linux Kernel</title> + +<para> +A user wrote the following to the mailing list: +</para> + +<para> +I am running Gentoo on my server and Samba 2.2.8a. Recently +I changed kernel version from <filename>linux-2.4.19-gentoo-r10</filename> to +<filename>linux-2.4.20-wolk4.0s</filename>. And now I have a performance issue with Samba. +Many of you will probably say, <quote>Move to vanilla sources!</quote> +Well, I tried that and it didn't work. I have a 100mb LAN and two computers (Linux and +Windows 2000). The Linux server shares directories with DivX files, the client +(Windows 2000) plays them via LAN. Before when I was running the 2.4.19 kernel +everything was fine, but now movies freeze and stop. I tried moving +files between the server and Windows and it is terribly slow. +</para> + +<para> +The answer he was given is: +</para> + +<para> +Grab the 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, and so on, look normal for ethernet. +</para> + +</sect1> + +<sect1> +<title>Corrupt tdb Files</title> + +<para> +Our Samba PDC server has been hosting three TB of data to our 500+ users +[Windows NT/XP] for the last three years using Samba without a problem. +Today all shares went 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 a lot of searching, I +decided to <command>rm /var/locks/*.tdb</command>. Happy again. +</para> + +<para> +<emphasis>Question:</emphasis> Is there any method of keeping the *.tdb files in top condition or +how can I detect early corruption? +</para> + +<para> +<emphasis>Answer:</emphasis> Yes, run <command>tdbbackup</command> each time after stopping nmbd and before starting nmbd. +</para> + +<para> +<emphasis>Question:</emphasis> What I also would like to mention is that the service latency seems +a lot lower than before the locks cleanup. Any ideas on keeping it top notch? +</para> + +<para> +<emphasis>Answer:</emphasis> Yes. Same answer as for previous question! +</para> + +</sect1> + +<sect1> +<title>Samba Performance is Very Slow</title> + +<para> +A site reported experiencing very baffling symptoms with MYOB Premier opening and +accessing it's data-files. Some operations on the file would take between 40 and +45 seconds. +</para> + +<para> +It turned out that the printer monitor program running on the windows +clients was causing the problems. From the logs, we saw activity coming +through with pauses of about 1 second. +</para> + +<para> +Stopping the monitor software resulted in the networks access at normal +(quick) speed. Restarting the program caused the speed to slow down +again. The printer was a cannon lbp810 and the relevant task was +something like CAPON (not sure on spelling). The monitor software +displayed a printing now dialog on the client during printing. +</para> + +<para> +We discovered this by starting with a clean install of windows and +trying the app at every step of the installation of other software +process (had to do this many times). +</para> + +<para> +Moral of the story, check everything (other software included)! +</para> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-StandAloneServer.xml b/docs/Samba3-HOWTO/TOSHARG-StandAloneServer.xml new file mode 100644 index 0000000000..ad1b69e79e --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-StandAloneServer.xml @@ -0,0 +1,244 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="StandAloneServer"> +<chapterinfo> + &author.jht; +</chapterinfo> +<title>Stand-alone Servers</title> + +<para> +Stand-alone Servers are independent of Domain Controllers on the network. +They are not Domain Members and function more like workgroup servers. In many +cases a Stand-alone Server is configured with a minimum of security control +with the intent that all data served will be readily accessible to all users. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +Stand-alone Servers can be as secure or as insecure as needs dictate. They can +have simple or complex configurations. Above all, despite the hoopla about +Domain Security they remain a common installation. +</para> + +<para> +If all that is needed is a server for read-only files, or for +printers alone, it may not make sense to effect a complex installation. +For example: A drafting office needs to store old drawings and reference +standards. No-one can write files to the server as it is legislatively +important that all documents remain unaltered. A share mode read-only Stand-alone +Server is an ideal solution. +</para> + +<para> +Another situation that warrants simplicity is an office that has many printers +that are queued off a single central server. Everyone needs to be able to print +to the printers, there is no need to effect any access controls and no files will +be served from the print server. Again, a share mode Stand-alone Server makes +a great solution. +</para> +</sect1> + +<sect1> +<title>Background</title> + +<para> +The term <emphasis>Stand-alone Server</emphasis> means that it +will provide local authentication and access control for all resources +that are available from it. In general this means that there will be a +local user database. In more technical terms, it means resources +on the machine will be made available in either SHARE mode or in +USER mode. +</para> + +<para> +No special action is needed other than to create user accounts. Stand-alone +servers do not provide network logon services. This means that machines that +use this server do not perform a domain logon to it. Whatever logon facility +the workstations are subject to is independent of this machine. It is, however, +necessary to accommodate any network user so the logon name they use will +be translated (mapped) locally on the Stand-alone Server to a locally known +user name. There are several ways this can be done. +</para> + +<para> +Samba tends to blur the distinction a little in respect of what is +a Stand-alone Server. This is because the authentication database may be +local or on a remote server, even if from the SMB protocol perspective +the Samba server is not a member of a domain security context. +</para> + +<para> +Through the use of Pluggable Authentication Modules (PAM) and the name service switcher (NSSWITCH), +which maintains the UNIX-user database) 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 +(<filename>/etc/passwd</filename> or <filename>/etc/shadow</filename>), may use a +local smbpasswd file, or may use an LDAP backend, or even via PAM and Winbind another CIFS/SMB server +for authentication. +</para> + +</sect1> + +<sect1> +<title>Example Configuration</title> + +<para> +The examples, <link linkend="simplynice">Reference Documentation Server</link>, and +<link linkend="SimplePrintServer">Central Print Serving</link>, +are designed to inspire simplicity. It is too easy to attempt a high level of creativity +and to introduce too much complexity in server and network design. +</para> + +<sect2 id="RefDocServer"> +<title>Reference Documentation Server</title> + +<para> +Configuration of a read-only data server that everyone can access is very simple. +<link linkend="simplynice">Following example</link> is the &smb.conf; file that will do this. Assume that all the reference documents +are stored in the directory <filename>/export</filename>, and the documents are owned by a user other than +nobody. No home directories are shared, and there are no users in the <filename>/etc/passwd</filename> +UNIX system database. This is a simple system to administer. +</para> + +<smbconfexample id="simplynice"> +<title>smb.conf for Reference Documentation Server</title> +<smbconfcomment> Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +<smbconfoption name="netbios name">&example.server.samba;</smbconfoption> +<smbconfoption name="security">SHARE</smbconfoption> +<smbconfoption name="passdb backend">guest</smbconfoption> +<smbconfoption name="wins server">192.168.1.1</smbconfoption> +<smbconfsection name="[data]"/> +<smbconfoption name="comment">Data</smbconfoption> +<smbconfoption name="path">/export</smbconfoption> +<smbconfoption name="guest only">Yes</smbconfoption> +</smbconfexample> + +<para> +In <link linkend="simplynice">the example</link> above, the machine name is set to &example.server.samba;, the workgroup is set to the name +of the local workgroup (&example.workgroup;) so the machine will appear together with systems with +which users are familiar. The only password backend required is the <quote>guest</quote> backend to allow default +unprivileged account names to be used. As there is a WINS server on this network, we of obviously make use of it. +</para> + +</sect2> + +<sect2 id="SimplePrintServer"> +<title>Central Print Serving</title> + +<para> +Configuration of a simple print server is easy if you have all the right tools +on your system. +</para> + +<orderedlist> +<title> Assumptions:</title> + <listitem><para> + The print server must require no administration. + </para></listitem> + + <listitem><para> + The print spooling and processing system on our print server will be CUPS. + (Please refer to <link linkend="CUPS-printing">CUPS Printing Support</link> for more information). + </para></listitem> + + <listitem><para> + The print server will service only network printers. The network administrator + will correctly configure the CUPS environment to support the printers. + </para></listitem> + + <listitem><para> + All workstations will use only postscript drivers. The printer driver + of choice is the one shipped with the Windows OS for the Apple Color LaserWriter. + </para></listitem> +</orderedlist> + +<para> +In this example our print server will spool all incoming print jobs to +<filename>/var/spool/samba</filename> until the job is ready to be submitted by +Samba to the CUPS print processor. Since all incoming connections will be as +the anonymous (guest) user, two things will be required: +</para> + +<itemizedlist> +<title>Enabling Anonymous Printing</title> + <listitem><para> + The UNIX/Linux system must have a <command>guest</command> account. + 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: +<screen> +&prompt;<userinput>testparm -s -v | grep "guest account"</userinput> +</screen> + Make sure that this account exists in your system password + database (<filename>/etc/passwd</filename>). + </para></listitem> + + <listitem><para> + 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: +<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> +The contents of the &smb.conf; file is shown in <link linkend="AnonPtrSvr">the next example</link>. +</para> + +<para> +<smbconfexample id="AnonPtrSvr"> +<title>&smb.conf; for Anonymous Printing</title> +<smbconfcomment> Global parameters</smbconfcomment> +<smbconfsection name="[global]"/> +<smbconfoption name="workgroup">&example.workgroup;</smbconfoption> +<smbconfoption name="netbios name">&example.server.samba;</smbconfoption> +<smbconfoption name="security">SHARE</smbconfoption> +<smbconfoption name="passdb backend">guest</smbconfoption> +<smbconfoption name="printing">cups</smbconfoption> +<smbconfoption name="printcap name">cups</smbconfoption> + +<smbconfsection name="[printers]"/> +<smbconfoption name="comment">All Printers</smbconfoption> +<smbconfoption name="path">/var/spool/samba</smbconfoption> +<smbconfoption name="printer admin">root</smbconfoption> +<smbconfoption name="guest ok">Yes</smbconfoption> +<smbconfoption name="printable">Yes</smbconfoption> +<smbconfoption name="use client driver">Yes</smbconfoption> +<smbconfoption name="browseable">No</smbconfoption> +</smbconfexample> +</para> + + +<note><para> +<indexterm><primary>MIME</primary><secondary>raw</secondary></indexterm> +<indexterm><primary>raw printing</primary></indexterm> +On CUPS-enabled systems there is a facility to pass raw data directly to the printer without +intermediate processing via CUPS print filters. Where use of this mode of operation is desired, +it is necessary to configure a raw printing device. It is also necessary to enable the raw mime +handler in the <filename>/etc/mime.conv</filename> and <filename>/etc/mime.types</filename> +files. Refer to <link linkend="cups-raw">Explicitly Enable <quote>raw</quote> Printing for +<emphasis>application/octet-stream</emphasis></link>. +</para></note> + +</sect2> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +The greatest mistake so often made is to make a network configuration too complex. +It pays to use the simplest solution that will meet the needs of the moment. +</para> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml b/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml new file mode 100644 index 0000000000..e811fa150c --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml @@ -0,0 +1,1537 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> + +<chapter id="NetCommand"> +<chapterinfo> + &author.jht; + &author.vl; + &author.gd; + <pubdate>May 9, 2005</pubdate> +</chapterinfo> + +<title>Remote and Local Management &smbmdash; The Net Command</title> + +<para> +The <command>net</command> command is one of the new features of Samba-3 and is an attempt to provide a useful +tool into which the majority of remote management operations necessary for common tasks. The +<command>net</command> tool is flexible by design and is intended for command line use as well as for scripted +control application. +</para> + +<para> +Originally introduced with the intent to mimic the Microsoft Windows command that has the same name, the +<command>net</command> command has morphed into a very powerful instrument that has become an essential part +of the Samba network administrator's toolbox. The Samba Team have introduced tools, such as +<command>smbgroupedit, rpcclient</command> from which really useful have been integrated into the +<command>net</command>. The <command>smbgroupedit</command> command was absorbed entirely into the +<command>net</command>, while only some features of the <command>rpcclient</command> command have been +ported to it. Anyone who finds older references to these utilities and to the functionality they provided +should look at the <command>net</command> command before searching elsewhere. +</para> + +<para> +A Samba-3 administrator can not afford to gloss over this chapter because to do so will almost certainly cause +the infliction of self induced pain, agony and desperation. Be warned, this is an important chapter. +</para> + + <sect1> + <title>Overview</title> + + <para> + The tasks that follow the installation of a Samba-3 server, whether Stand-Alone, Domain Member, of a + Domain Controller (PDC or BDC) begins with the need to create administrative rights. Of course, the + creation of user and group accounts is essential for both a Stand-Alone server as well as for a PDC. + In the case of a BDC or a Domain Member server (DMS) Domain user and group accounts are obtained from + the central domain authentication backend. + </para> + + <para> + Regardless of the type of server being installed, local UNIX groups must be mapped to the Windows + networking domain global group accounts. Do you ask, why? Because Samba always limits its access to + the resources of the host server by way of traditional UNIX UID/GID controls. This means that local + groups must be mapped to domain global groups so that domain users who are members of the domain + global groups can be given access rights based on UIDs and GIDs local to the server that is hosting + Samba. Such mappings are implemented using the <command>net</command> command. + </para> + + <para> + UNIX systems that are hosting a Samba-3 server that is running as a member (PDC, BDC, or DMS) must have + a machine security account in the domain authentication database (or directory). The creation of such + security (or trust) accounts is also handled using the <command>net</command> command. + </para> + + <para> + The establishment of inter-domain trusts is achieved using the <command>net</command> command also, as + may a plethora of typical administrative duties such as: user management, group management, share and + printer management, file and printer migration, security identifier management, and so on. + </para> + + <para> + The over-all picture should be clear now, the <command>net</command> command plays a central role + on the Samba-3 stage. This role will continue to be developed. The inclusion of this chapter is + evidence of its importance, one that has grown in complexity to the point that it is no longer considered + prudent to cover its use fully in the on-line UNIX man pages. + </para> + + </sect1> + + <sect1> + <title>Administrative Tasks And Methods</title> + + <para> + The basic operations of the <command>net</command> command are documented here. This documentation is not + exhaustive, and thus it is incomplete. Since the primary focus is on migration from Windows servers to + a Samba server the emphasis is on the use of the DCE RPC mode of operation. When used against a server + that is a member of an Active Directory domain it is preferable (and often necessary) to use ADS mode + operations. The <command>net</command> command supports both, but not for every operation. For most + operations, if the mode is not specified <command>net</command> will automatically fall back via + the <constant>ads, rpc, rap</constant> modes. Please refer to the man page for a more comprehensive + overview of the capabilities of this utility. + </para> + + </sect1> + + <sect1> + <title>UNIX and Windows Group Management</title> + + <para> + In repetition of what has been said, the focus in most of this chapter is on use of the <command>net + rpc</command> family of operations that are supported by Samba. Most of them are supported by the + <command>net ads</command> mode when used in connection with MS Active Directory. The <command>net + rap</command> operating mode is also supported for some of these operations. RAP protocols are used + by IBM OS/2 and by several earlier SMB servers. + </para> + + <para> + Sambas' <command>net</command> tool implements sufficient capability to permit all common administrative + tasks to be completed from the command line. In this section each of the essential user and group management + facilities are explored. + </para> + + <para> + Samba-3 recognizes two types of groups: <emphasis>domain groups</emphasis> and <emphasis>local + groups</emphasis>. Domain groups can contain (have as members) only domain user accounts. Local groups + can contain local users, domain users, and domain groups as members. + </para> + + <para> + The purpose of a local group is to permit file permission to be set for a group account that, like the + usual UNIX/Linux group, is persistent across redeployment of a Windows file server. + </para> + + <sect2> + <title>Adding, Renaming, or Deletion of Group Accounts</title> + + <sect3> + <title>Adding or Creating a New Group</title> + + <para> + Before attempting to add a Windows group account the currently available groups can be listed as shown +here: +<screen> +&rootprompt; net rpc group list -Uroot%not24get +Password: +Domain Admins +Domain Users +Domain Guests +Print Operators +Backup Operators +Replicator +Domain Computers +Engineers +</screen> + A Windows group account called <quote>SupportEngrs</quote> can be added by executing the following +command: +<screen> +&rootprompt; net rpc group add "SupportEngrs" -Uroot%not24get +</screen> + The addition will result in immediate availability of the new group account as validated by executing the +this command: +<screen> +&rootprompt; net rpc group list -Uroot%not24get +Password: +Domain Admins +Domain Users +Domain Guests +Print Operators +Backup Operators +Replicator +Domain Computers +Engineers +SupportEngrs +</screen> + </para> + + <para> + The following demonstrates that the POSIX (UNIX/Linux system account) group has been created by calling + the <smbconfoption name="add group script">/opt/IDEALX/sbin/smbldap-groupadd -p "%g"</smbconfoption> interface + script: +<screen> +&rootprompt; getent group +... +Domain Admins:x:512:root +Domain Users:x:513:jht,lct,ajt,met +Domain Guests:x:514: +Print Operators:x:550: +Backup Operators:x:551: +Replicator:x:552: +Domain Computers:x:553: +Engineers:x:1002:jht +SupportEngrs:x:1003: +</screen> + The following demonstrates that the use of the <command>net</command> command to add a group account +results in immediate mapping of the POSIX group that has been created to the Windows group account as shown +here: +<screen> +&rootprompt; net groupmap list +Domain Admins (S-1-5-21-72630-4128915-11681869-512) -> Domain Admins +Domain Users (S-1-5-21-72630-4128915-11681869-513) -> Domain Users +Domain Guests (S-1-5-21-72630-4128915-11681869-514) -> Domain Guests +Print Operators (S-1-5-21-72630-4128915-11681869-550) -> Print Operators +Backup Operators (S-1-5-21-72630-4128915-11681869-551) -> Backup Operators +Replicator (S-1-5-21-72630-4128915-11681869-552) -> Replicator +Domain Computers (S-1-5-21-72630-4128915-11681869-553) -> Domain Computers +Engineers (S-1-5-21-72630-4128915-11681869-3005) -> Engineers +SupportEngrs (S-1-5-21-72630-4128915-11681869-3007) -> SupportEngrs +</screen> + </para> + + </sect3> + + <sect3> + <title>Mapping Windows Groups to UNIX Groups</title> + + <para> + Windows groups must be mapped to UNIX system (POSIX) groups so that file system access controls + can be asserted in a manner that is consistent with the methods appropriate to the operating + system that is hosting the Samba server. + </para> + + <para> + All file system (file and directory) access controls, within the file system of a UNIX/Linux server that is + hosting a Samba server, is implemented using a UID/GID identity tuple. Samba does not in any way over-ride + or replace UNIX file system semantics. Thus it is necessary that all Windows networking operations that + access the file system must provide a mechanism that maps a Windows user to a particular UNIX/Linux group + account. The user account must also map to a locally known UID. + </para> + + <para> + Samba depends on default mappings for the <constant>Domain Admins, Domain Users</constant> and + <constant>Domain Guests</constant> global groups. Additional groups may be added as shown in the + examples just given. There are times when it is necessary to map an existing UNIX group account + to a Windows group. This operation, in effect, creates a Windows group account as a consequence + of creation of the mapping. + </para> + + <para> + The operations that are permitted includes: <constant>add, modify, delete</constant>. An example + of each operation is shown here. + </para> + + <para> + An existing UNIX group may be mapped to an existing Windows group by this example: +<screen> +&rootprompt; net groupmap modify ntgroup="Domain Users" unixgroup=users +</screen> + An existing UNIX group may be mapped to a new Windows group as shown here: +<screen> +&rootprompt; net groupmap add ntgroup="EliteEngrs" unixgroup=Engineers type=d +</screen> + A Windows group may be deleted, and then a new Windows group can be mapped to the UNIX group by + executing these commands: +<screen> +&rootprompt; net groupmap delete ntgroup=Engineers +&rootprompt; net groupmap add ntgroup=EngineDrivers unixgroup=Engineers type=d +</screen> + </para> + + <para> + Two types of Windows groups can be created: <constant>domain (global),</constant> and <constant>local</constant>. + In the above examples the Windows groups created were of type <constant>domain</constant>, or global. The + following command will create a Windows group of type <constant>local</constant>. +<screen> +&rootprompt; net groupmap add ntgroup=Pixies unixgroup=pixies type=l +</screen> + Local groups can be used with Samba to enable multiple nested group support. + </para> + + </sect3> + + <sect3> + <title>Deleting a Group Account</title> + + <para> + A group account may be deleted by executing the following command: +<screen> +&rootprompt; net rpc group delete SupportEngineers -Uroot%not24get +</screen> + </para> + + <para> + Validation of the deletion is advisable. The same commands may be executed as shown above. + </para> + + </sect3> + + <sect3> + <title>Rename Group Accounts</title> + + <note><para> + This command is not documented in the man pages, it is implemented in the source code, but it does not + work. The example given documents (from the source code) how it should work. Watch the release notes + of a future release to see when this may have been be fixed. + </para></note> + + <para> + Sometimes it is necessary to rename a group account. Good administrators know how painful some managers + demands can be if this simple request is ignored. The following command demonstrates how the Windows group + <quote>SupportEngrs</quote> can be renamed to <quote>CustomerSupport</quote>: +<screen> +&rootprompt; net rpc group rename SupportEngrs \ + CustomerSupport -Uroot%not24get +</screen> + </para> + + </sect3> + + </sect2> + + <sect2> + <title>Manipulating Group Memberships</title> + + <para> + Three operations can be performed in respect of group membership. It is possible to (1) add Windows users + to Windows group, to (2) delete Windows users from Windows groups, and to (3) list the Windows users that are + members of a Windows group. + </para> + + <para> + So as to avoid confusion, it makes sense to check group membership before attempting to make and changes. + The <command>getent group</command> will list UNIX/Linux group membership. UNIX/Linux group members are + seen also as members of a Windows group that has been mapped using the <command>net groupmap</command> + command (see <link linkend="groupmapping"/>). The following list of UNIX/Linux group membership shows + that the user <constant>ajt</constant> is a member of the UNIX/Linux group <constant>Engineers</constant>. +<screen> +&rootprompt; getent group +... +Domain Admins:x:512:root +Domain Users:x:513:jht,lct,ajt,met,vlendecke +Domain Guests:x:514: +Print Operators:x:550: +Backup Operators:x:551: +Replicator:x:552: +Domain Computers:x:553: +Engineers:x:1000:jht,ajt +</screen> + The UNIX/Linux groups have been mapped to Windows groups, as is shown here: +<screen> +&rootprompt; net groupmap list +Domain Admins (S-1-5-21-72630-412605-116429-512) -> Domain Admins +Domain Users (S-1-5-21-72630-412605-116429-513) -> Domain Users +Domain Guests (S-1-5-21-72630-412605-116429-514) -> Domain Guests +Print Operators (S-1-5-21-72630-412605-116429-550) -> Print Operators +Backup Operators (S-1-5-21-72630-412605-116429-551) -> Backup Operators +Replicator (S-1-5-21-72630-412605-116429-552) -> Replicator +Domain Computers (S-1-5-21-72630-412605-116429-553) -> Domain Computers +Engineers (S-1-5-21-72630-412605-116429-3001) -> Engineers +</screen> + </para> + + <para> + Given that the user <constant>ajt</constant> is already a member of the UNIX/Linux group, and via the + group mapping, a member of the Windows group, an attempt to add this account again should fail. This is + demonstrated here: +<screen> +&rootprompt; net rpc group addmem "MIDEARTH\Engineers" ajt -Uroot%not24get +Could not add ajt to MIDEARTH\Engineers: NT_STATUS_MEMBER_IN_GROUP +</screen> + This shows that the group mapping between UNIX/Linux groups and Windows groups is effective and + transparent. + </para> + + <para> + To permit the user <constant>ajt</constant> to be added using the <command>net rpc group</command> utility + this account must first be removed. The removal, and confirmation of its effect is shown here: +<screen> +&rootprompt; net rpc group delmem "MIDEARTH\Engineers" ajt -Uroot%not24get +&rootprompt; getent group Engineers +Engineers:x:1000:jht +&rootprompt; net rpc group members Engineers -Uroot%not24get +MIDEARTH\jht +</screen> + In this example both at the UNIX/Linux system level, the group no longer has the <constant>ajt</constant> + as a member. The above also shows this to be the case for Windows group membership. + </para> + + <para> + The account is now added again, using the <command>net rpc group</command> utility: +<screen> +&rootprompt; net rpc group addmem "MIDEARTH\Engineers" ajt -Uroot%not24get +&rootprompt; getent group Engineers +Engineers:x:1000:jht,ajt +&rootprompt; net rpc group members Engineers -Uroot%not24get +MIDEARTH\jht +MIDEARTH\ajt +</screen> + </para> + + <para> + In this example the members of the Windows <constant>Domain Users</constant> account is validated using + the <command>net rpc group</command> utility. Note that this contents of the UNIX/Linux group was shown + 4 paragraphs earlier. The Windows (domain) group membership is shown here: +<screen> +&rootprompt; net rpc group members "Domain Users" -Uroot%not24get +MIDEARTH\jht +MIDEARTH\lct +MIDEARTH\ajt +MIDEARTH\met +MIDEARTH\vlendecke +</screen> + The example shown here is an express example that Windows group names are treated by Samba (as with + MS Windows) in a case insensitive manner: +<screen> +&rootprompt; net rpc group members "DomAiN USerS" -Uroot%not24get +MIDEARTH\jht +MIDEARTH\lct +MIDEARTH\ajt +MIDEARTH\met +MIDEARTH\vlendecke +</screen> + </para> + + <note><para> + An attempt to specify the group name as <constant>MIDEARTH\Domain Users</constant> in place of + just simply <constant>Domain Users</constant> will fail. The default behavior of the net rpc group + is to direct the command at the local machine. The Windows group is treated as being local to the machine. + If it is necessary to query another machine, its name can be specified using the <constant>-S + servername</constant> parameter to the <command>net</command> command. + </para></note> + + </sect2> + + <sect2> + <title>Nested Group Support</title> + + <para> + It is possible in Windows (and now in Samba also) to great a local group that has members (contains) + domain users and domain global groups. Creation of the local group <constant>demo</constant> is + achieved by executing: +<screen> +&rootprompt; net rpc group add demo -L -S MORDON -Uroot%not24get +</screen> + The -L switch means create a local group. Use the -S argument to direct the operation to a particular + server. The parameters to the -U argument should be for a user who has appropriate administrative right + and privileges on the machine. + </para> + + <para> + Addition and removal of group members can be achieved using the <constant>addmem</constant> and + <constant>delmem</constant> subcommands of <command>net rpc group</command> command. For example, + addition of <quote>DOM\Domain Users</quote> to the local group <constant>demo</constant> would be + done by executing: +<screen> +&rootprompt; net rpc group addmem demo "DOM\Domain Users" -Uroot%not24get +</screen> + </para> + + <para> + The members of a nested group can be listed by executing the following: +<screen> +&rootprompt; net rpc group members demo -Uroot%not24get +DOM\Domain Users +DOM\Engineers +DOM\jamesf +DOM\jht +</screen> + </para> + + <para> + Nested group members can be removed (deleted) as shown here: +<screen> +&rootprompt; net rpc group delmem demo "DOM\jht" -Uroot%not24get +</screen> + </para> + + <para> + Windows network administrators often ask on the Samba mailing list how it is possible to grant everyone + administrative rights on their own workstation. This is of course a very bad practice, but commonly done + to avoid user complaints. Here is how it can be done remotely from a Samba PDC or BDC: +<screen> +&rootprompt; net rpc group addmem "Administrators" "Domain Users" \ + -S WINPC032 -Uadministrator%secret +</screen> + </para> + + </sect2> + + </sect1> + + <sect1> + <title>UNIX and Windows User Management</title> + + <para> + Every Windows network user account must be translated to a UNIX/Linux user account. In actual fact, + the only account information the UNIX/Linux Samba server needs is a UID. The UID is available either + from a system (POSIX) account, or from a pool (range) of UID numbers that is set aside for the purpose + of being allocated for use by Windows user accounts. In the case of the UID pool, the UID for a + particular user will be allocated by <command>winbindd</command>. + </para> + + <para> + Although this is not the appropriate place to discuss the <smbconfoption name="username map"/> facility, + this interface is an important method of mapping a Windows user account to a UNIX account that has a + different name. Refer to the man page for the &smb.conf; file for more information regarding this + facility. User name mappings can not be managed using the <command>net</command> utility. + </para> + + <sect2 id="sbeuseraddn"> + <title>Adding User Accounts</title> + + <para> + The syntax for adding a user account via the <command>net</command> (according to the man page) is shown + here: +<screen> +net [<method>] user ADD <name> [-c container] [-F user flags] \ + [misc. options] [targets] +</screen> + The user account password may be set using this syntax: +<screen> +net rpc password <username> [<password>] -Uadmin_username%admin_pass +</screen> + </para> + + <para> + The following demonstrates the addition of an account to the server <constant>FRODO</constant>: +<screen> +&rootprompt; net rpc user add jacko -S FRODO -Uroot%not24get +Added user jacko +</screen> + The account password can be set with the following methods (all show the same operation): +<screen> +&rootprompt; net rpc password jacko f4sth0rse -S FRODO -Uroot%not24get +&rootprompt; net rpc user password jacko f4sth0rse \ + -S FRODO -Uroot%not24get +</screen> + </para> + + </sect2> + + <sect2> + <title>Deletion of User Accounts</title> + + <para> + Deletion of a user account can be done using the following syntax: +<screen> +net [<method>] user DELETE <name> [misc. options] [targets] +</screen> + The following command will delete the user account <constant>jacko</constant>: +<screen> +&rootprompt; net rpc user delete jacko -Uroot%not24get +Deleted user account +</screen> + </para> + + </sect2> + + <sect2> + <title>Managing User Accounts</title> + + <para> + Two basic user account operations are routinely used, change of password and querying which groups a user + is a member of. The change of password operation is shown in <link linkend="sbeuseraddn"/>. + </para> + + <para> + The ability to query Windows group membership can be essential. Here is how a remote server may be + interrogated to find which groups a user is a member of: +<screen> +&rootprompt; net rpc user info jacko -S SAURON -Uroot%not24get +net rpc user info jacko -S SAURON -Uroot%not24get +Domain Users +Domain Admins +Engineers +TorridGroup +BOP Shop +Emergency Services +</screen> + </para> + + </sect2> + + <sect2> + <title>User Mapping</title> + + <para> + In some situations it is unavoidable that a users' Windows logon name will differ from the login ID + that user has on the Samba server. It is possible to create a special file on the Samba server that + will permit the Windows user name to be mapped to a different UNIX/Linux user name. The &smb.conf; + file must also be amended so that the <constant>[global]</constant> stanza contains the parameter: +<screen> +username map = /etc/samba/smbusers +</screen> + The content of the <filename>/etc/samba/smbusers</filename> file is shown here: +<screen> +parsonsw: "William Parsons" +marygee: geeringm +</screen> + In this example the Windows user account <quote>William Parsons</quote> will be mapped to the UNIX user + <constant>parsonsw</constant>, and the Windows user account <quote>geeringm</quote> will be mapped to the + UNIX user <constant>marygee</constant>. + </para> + + </sect2> + + </sect1> + + <sect1> + <title>Administering User Rights and Privileges</title> + + <para> + With all versions of Samba earlier than 3.0.11 the only account on a Samba server that had the ability + to manage users, groups, shares, printers, etc. is the <constant>root</constant> account. This caused + immense problems for some users and was a frequent source of scorn over the necessity to hand out the + credentials for the most security sensitive account on a UNIX/Linux system. + </para> + + <para> + New to Samba version 3.0.11 is the ability to delegate administrative privileges as necessary to either + a normal user, or to groups of users. The significance of the administrative privileges is documented + in <link linkend="rights"/>. Examples of use of the <command>net</command> for user rights and privilege + management is appropriate to this chapter. + </para> + + <note><para> + When user rights and privileges are correctly set there is no longer a need for there to be a Windows + network account for the <constant>root</constant> user (nor for any synonym of it) with a UNIX UID=0. + Initial user rights and privileges can be assigned by any account that is a member of the <constant> + Domain Admins</constant> group. Rights can be assigned to user as well as group accounts. + </para></note> + + <para> + By default, no privileges and rights are assigned. This is demonstrated by executing the command + shown here: +<screen> +&rootprompt; net rpc rights list accounts -U root%not24get +BUILTIN\Print Operators +No privileges assigned + +BUILTIN\Account Operators +No privileges assigned + +BUILTIN\Backup Operators +No privileges assigned + +BUILTIN\Server Operators +No privileges assigned + +BUILTIN\Administrators +No privileges assigned + +Everyone +No privileges assigned +</screen> + </para> + + <para> + The <command>net</command> command can be used to obtain the currently supported capabilities for rights + and privileges using this method: +<screen> +&rootprompt; net rpc rights list -U root%not24get + SeMachineAccountPrivilege Add machines to domain + SePrintOperatorPrivilege Manage printers + SeAddUsersPrivilege Add users and groups to the domain + SeRemoteShutdownPrivilege Force shutdown from a remote system + SeDiskOperatorPrivilege Manage disk shares +</screen> + Machine account privilege is necessary to permit a Windows NT4 or later network client to be added to the + domain. The disk operator privilege is necessary to permit the user to manage share ACLs and file and + directory ACLs for objects not owned by the user. + </para> + + <para> + In this example, all rights are assigned to the <constant>Domain Admins</constant> group. This is a good + idea since members of this group are generally expected to be all-powerful. This assignment makes that + the reality: +<screen> +&rootprompt; net rpc rights grant "MIDEARTH\Domain Admins" \ + SeMachineAccountPrivilege SePrintOperatorPrivilege \ + SeAddUsersPrivilege SeRemoteShutdownPrivilege \ + SeDiskOperatorPrivilege -U root%not24get +Successfully granted rights. +</screen> + Next, the domain user <constant>jht</constant> is given the privileges needed for day to day + administration: +<screen> +&rootprompt; net rpc rights grant "MIDEARTH\jht" \ + SeMachineAccountPrivilege SePrintOperatorPrivilege \ + SeAddUsersPrivilege SeDiskOperatorPrivilege \ + -U root%not24get +Successfully granted rights. +</screen> + </para> + + <para> + The following step permits validation of the changes just made: +<screen> +&rootprompt; net rpc rights list accounts -U root%not24get +MIDEARTH\jht +SeMachineAccountPrivilege +SePrintOperatorPrivilege +SeAddUsersPrivilege +SeDiskOperatorPrivilege + +BUILTIN\Print Operators +No privileges assigned + +BUILTIN\Account Operators +No privileges assigned + +BUILTIN\Backup Operators +No privileges assigned + +BUILTIN\Server Operators +No privileges assigned + +BUILTIN\Administrators +No privileges assigned + +Everyone +No privileges assigned + +MIDEARTH\Domain Admins +SeMachineAccountPrivilege +SePrintOperatorPrivilege +SeAddUsersPrivilege +SeRemoteShutdownPrivilege +SeDiskOperatorPrivilege +</screen> + </para> + + </sect1> + + <sect1> + <title>Managing Trust Relationships</title> + + <para> + There are essentially two types of trust relationships. The first between domain controllers and domain + member machines (network clients), the second trusts between domains (called inter-domain trusts). All + Samba servers that participate in domain security require a domain membership trust account, as do like + Windows NT/2KX/XPP workstations. + </para> + + <sect2> + <title>Machine Trust Accounts</title> + + <para> + A Samba server domain trust account can be validated as shown in this example: +<screen> +&rootprompt; net rpc testjoin +Join to 'MIDEARTH' is OK +</screen> + Where there is no domain membership account, or when the account credentials are not valid the following + results will be observed: +<screen> +net rpc testjoin -S DOLPHIN +Join to domain 'WORLDOCEAN' is not valid +</screen> + </para> + + <para> + The equivalent command for joining a Samba server to a Windows ADS domain is shown here: +<screen> +&rootprompt; net ads testjoin +Using short domain name -- TAKEAWAY +Joined 'LEMONADE' to realm 'TAKEAWAY.BIZ' +</screen> + In the event that the ADS trust was not established, or is broken for one reason or another, the following + error message may be obtained: +<screen> +&rootprompt; net ads testjoin -UAdministrator%secret +Join to domain is not valid +</screen> + </para> + + <para> + The following demonstrates the process of creating a machine trust account in the target domain for the + Samba server from which the command is executed: +<screen> +&rootprompt; net rpc join -S FRODO -Uroot%not24get +Joined domain MIDEARTH. +</screen> + The joining of a Samba server to a Samba domain results in the creation of a machine account. An example + of this is shown here: +<screen> +&rootprompt; pdbedit -Lw merlin\$ +merlin$:1009:9B4489D6B90461FD6A3EC3AB96147E16:\ +176D8C554E99914BDF3407DEA2231D80:[S ]:LCT-42891919: +</screen> + The S in the square brackets means this is a server (PDC/BDC) account. The domain join can be cast to join + purely as a workstation, in which case the S is replaced with a W (indicating a workstation account). The + following command can be used to affect this: +<screen> +&rootprompt; net rpc join member -S FRODO -Uroot%not24get +Joined domain MIDEARTH. +</screen> + Note that the command-line parameter <constant>member</constant> makes this join specific. By default + the type is deduced from the &smb.conf; file configuration. To specifically join as a PDC or BDC the + command-line parameter will be <constant>[PDC | BDC]</constant>. For example: +<screen> +&rootprompt; net rpc join bdc -S FRODO -Uroot%not24get +Joined domain MIDEARTH. +</screen> + It is best to let Samba figure out the domain join type from the settings in the &smb.conf; file. + </para> + + <para> + The command to join a Samba server to a Windows ADS domain is shown here: +<screen> +&rootprompt; net ads join -UAdministrator%not24get +Using short domain name -- GDANSK +Joined 'FRANDIMITZ' to realm 'GDANSK.ABMAS.BIZ' +</screen> + </para> + + <para> + There is no specific option to remove a machine account from ain NT4 domain. When a domain member that is a + Windows machine is withdrawn from the domain the domain membership account is not automatically removed + either. Inactive domain member accounts can be removed using any convenient tool. If necessary, the + machine account can be removed using the following <command>net</command> command: +<screen> +&rootprompt; net rpc user delete HERRING\$ -Uroot%not24get +Deleted user account. +</screen> + The removal is made possible because machine account are just like user accounts with a trailing $ + character. The account management operations treat user and machine accounts in like manner. + </para> + + <para> + A Samba-3 server that is a Windows ADS domain member can execute the following command to detach from the + domain: +<screen> +&rootprompt; net ads leave +</screen> + </para> + + <para> + Detailed information regarding an ADS domain can be obtained by a Samba DMS machine by executing the + following: +<screen> +&rootprompt; net ads status +</screen> + The volume of information is extensive. Please refer to the book <quote>Samba-3 by Example</quote>, +Chapter 7 for more information regarding its use. This book may be obtained either in print, or on line from +the <ulink url="http://www.samba.org/samba/docs/Samba-Guide.pdf">Samba-Guide</ulink>. + </para> + + </sect2> + + <sect2> + <title>Inter-Domain Trusts</title> + + <para> + Inter-domain trust relationships form the primary mechanism by which users from one domain can be granted + access rights and privileges in another domain. + </para> + + <para> + To discover what trust relationships are in effect execute this command: +<screen> +&rootprompt; net rpc trustdom list -Uroot%not24get +Trusted domains list: + +none + +Trusting domains list: + +none +</screen> + There are no inter-domain trusts at this time, the following steps will create them. + </para> + + <para> + It is necessary to create a trust account in the local domain. A domain controller in a second domain can + create a trusted connection with this account. That means that the foreign domain is being trusted + to access resources in the local domain. This command creates the local trust account: +<screen> +&rootprompt; net rpc trustdom add damnation f00db4r -Uroot%not24get +</screen> + The account can be revealed by using the <command>pdbedit</command> as shown here: +<screen> +&rootprompt; pdbedit -Lw damnation\$ +damnation$:1016:9AC1F121DF897688AAD3B435B51404EE: \ +7F845808B91BB9F7FEF44B247D9DC9A6:[I ]:LCT-428934B1: +</screen> + A trust account will always have an I in the field within the square brackets. + </para> + + <para> + If the trusting domain is not capable of being reached the following command will fail +<screen> +&rootprompt; net rpc trustdom list -Uroot%not24get +Trusted domains list: + +none + +Trusting domains list: + +DAMNATION S-1-5-21-1385457007-882775198-1210191635 +</screen> + The above command executed successfully; a failure is indicated when the following response is obtained: +<screen> +net rpc trustdom list -Uroot%not24get +Trusted domains list: + +DAMNATION S-1-5-21-1385457007-882775198-1210191635 + +Trusting domains list: + +DAMNATION domain controller is not responding +</screen> + </para> + + <para> + Where a trust account has been created on a foreign domain, Samba is able to establish the trust (connect with) + the foreign account. In the process it creates a one-way trust to the resources on the remote domain. This + command achieves the objective of enjoining the trust relationship: +<screen> +&rootprompt; net rpc trustdom establish damnation +Password: xxxxxxx == f00db4r +Could not connect to server TRANSGRESSION +Trust to domain DAMNATION established +</screen> + Validation of the two-way trust now established is possible as shown here: +<screen> +&rootprompt; net rpc trustdom list -Uroot%not24get +Trusted domains list: + +DAMNATION S-1-5-21-1385457007-882775198-1210191635 + +Trusting domains list: + +DAMNATION S-1-5-21-1385457007-882775198-1210191635 +</screen> + </para> + + <para> + Sometimes it is necessary to remove the ability for local uses to access a foreign domain. The trusting + connection can be revoked as shown here: +<screen> +&rootprompt; net rpc trustdom revoke damnation -Uroot%not24get +</screen> + At other times it becomes necessary to remove the ability for users from a foreign domain to be able to + access resources in the local domain. The command shown here will do that: +<screen> +&rootprompt; net rpc trustdom del damnation -Uroot%not24get +</screen> + + </para> + + </sect2> + + </sect1> + + <sect1> + <title>Managing Security Identifiers (SIDS)</title> + + <para> + The basic security identifier that is used b y all Windows networking operations is the Windows security + identifier (SID). All Windows network machines (servers and workstations), users, and groups are + identified by their respective SID. All desktop profiles are also encoded with user and group SIDs that + are specific to the SID of the domain to which the user belongs. + </para> + + <para> + It is truly prudent to store the machine and/or domain SID in a file for safe-keeping. Why? Because + a change in hostname or in the domain (workgroup) name may result in a change in the SID. When you + have the SID on hand it is a simple matter to restore it. The alternative is to suffer the pain of + having to recover user desktop profiles and perhaps re-join all member machines to the domain. + </para> + + <para> + First, do not forget to store the local sid in a file. It is a good idea to put this in the directory + in which the &smb.conf; file is also stored. Here is a simple action to achieve this: +<screen> +&rootprompt; net getlocalsid > /etc/samba/my-sid +</screen> + Good, there is now a safe copy of the local machine SID. On a PDC/BDC this is the domain SID also. + </para> + + <para> + The following command reveals what the former one should have placed into the file called + <filename>my-sid</filename>: +<screen> +&rootprompt; net getlocalsid +SID for domain MERLIN is: S-1-5-21-726309263-4128913605-1168186429 +</screen> + </para> + + <para> + If ever it becomes necessary to restore the SID that has been stored in the <filename>my-sid</filename> + file, simply copy the SID (the string of characters that begins with <constant>S-1-5-21</constant>) to + the command-line shown here: +<screen> +&rootprompt; net setlocalsid S-1-5-21-1385457007-882775198-1210191635 +</screen> + Restoration of a machine SID is a simple operation, but the absence of a back-up copy can be very + problematic. + </para> + + <para> + The following operation is useful only for machines that are being configured as a PDC or a BDC. + Domain member servers (DMS) and workstation clients should have their own machine SID to avoid + any potential name-space collision. Here is the way that the BDC SID can be synchronized to that + of the PDC (this is the default NT4 domain practice also): +<screen> +&rootprompt; net rpc getsid -S FRODO -Uroot%not24get +Storing SID S-1-5-21-726309263-4128913605-1168186429 \ + for Domain MIDEARTH in secrets.tdb +</screen> + Usually it is not necessary to specify the target server (-S FRODO) or the administrator account + credentials (-Uroot%not24get). + </para> + + </sect1> + + <sect1> + <title>Share Management</title> + + <para> + Share management is central to all file serving operations. Typical share operations include: + </para> + + <itemizedlist> + <listitem><para>Creation/change/deletion of shares</para></listitem> + <listitem><para>Setting/changing ACLs on shares</para></listitem> + <listitem><para>Moving shares from one server to another</para></listitem> + <listitem><para>Change of permissions of share contents</para></listitem> + </itemizedlist> + + <para> + Each of these are dealt with here in so far as they involve the use of the <command>net</command> + command. Operations outside of this command are covered elsewhere in this document. + </para> + + <sect2> + <title>Creating, Editing, and Removing Shares</title> + + <para> + A share can be added using the <command>net rpc share</command> command capabilities. + The target machine may be local or remote and is specified by the -S option. It must be noted + that the addition and deletion of shares using this tool depends on the availability of a suitable + interface script. The interface scripts Sambas <command>smbd</command> uses are called: + <smbconfoption name="add share script"/> and <smbconfoption name="delete share script"/>. + A set of example scripts are provided in the Samba source code tarball in the directory + <filename>~samba/examples/scripts</filename>. + </para> + + <para> + The following steps demonstrate the use of the share management capabilities of the <command>net</command> + utility. In the first step a share called <constant>Bulge</constant> is added. The share-point within the + file system is the directory <filename>/data</filename>. The command that can be executed to perform the + addition of this share is shown here: +<screen> +&rootprompt; net rpc share add Bulge=/data -S MERLIN -Uroot%not24get +</screen> + Validation is an important process, and by executing the command <command>net rpc share</command> + with no other operators a listing of available shares is shown here: +<screen> +&rootprompt; net rpc share -S MERLIN -Uroot%not24get +profdata +archive +Bulge <--- This one was added +print$ +netlogon +profiles +IPC$ +kyocera +ADMIN$ +</screen> + </para> + + <para> + Often it is desirable also to permit a share to be removed using a command-line tool. + The following step permits the share that was previously added to be removed: +<screen> +&rootprompt; net rpc share delete Bulge -S MERLIN -Uroot%not24get +</screen> + A simple validation shown here demonstrates that the share has been removed: +<screen> +&rootprompt; net rpc share -S MERLIN -Uroot%not24get +profdata +archive +print$ +netlogon +profiles +IPC$ +ADMIN$ +kyocera +</screen> + </para> + + </sect2> + + <sect2> + <title>Creating and Changing Share ACLs</title> + + <para> + At this time the net tool can not be used to manage ACLs on Samba shares. In MS Windows + language this is called: Share Permissions. + </para> + + <para> + It is possible to set ACLs on Samba shares using either the SRVTOOLS NT4 Domain Server Manager, + of using the Computer Management MMC snap-in. Neither will be covered here as this subject is + covered in <link linkend="AccessControls"/>. + </para> + + </sect2> + + <sect2> + <title>Share, Directory and File Migration</title> + + <para> + Shares and files can be migrated in the same manner as user, machine and group accounts. + It is possible to preserve access control settings (ACLs) as well as security settings + throughout the migration process. The <command>net rpc vampire</command> facility is used + to migrate accounts from a Windows NT4 (or later) domain to a Samba server. This process + preserves passwords and account security settings and is a precursor to the migration + of shares and files. + </para> + + <para> + The <command>net rpc share</command> command may be used to migrate shares, directories + files, printers, and all relevant data from a Windows server to a Samba server. + </para> + + <para> + A set of command-line switches permit the creation of almost direct clones of Windows file + servers. For example, when migrating a file-server, file ACLs and DOS file attributes from + the Windows server can be included in the migration process and will reappear, almost identically + on the Samba server when the migration has been completed. + </para> + + <para> + The migration process can be completed only with the Samba server already being fully operational. + This means that the user and group accounts must be migrated before attempting to migrate data + share, files, and printers. The migration of files and printer configurations involves the use + of both SMB and MS DCE RPC services. The benefit of the manner in which the migration process has + been implemented, the possibility now exists to use a Samba server as a man-in-middle migration + service that affects a transfer of data from one server to another. For example, if the Samba + server is called MESSER, the source Windows NT4 server is called PEPPY, and the target Samba + server is called GONZALES, the machine MESSER can be used to affect the migration of all data + (files and shares) from PEPPY to GONZALES. If the target machine is not specified, the local + server is assumed by default. + </para> + + <para> + The success of server migration requires a firm understanding of the structure of the source + server (or domain) as well as the processes on which the migration is critically dependant. + </para> + + <para> + There are two known limitations to the migration process: + </para> + + <orderedlist> + <listitem><para> + The <command>net</command> command requires that the user credentials provided exist both + on the migration source and the migration target. + </para></listitem> + + <listitem><para> + Printer settings may not be fully or incorrectly migrated. This might in particular happen + when migrating a Windows 2003 print server to Samba. + </para></listitem> + </orderedlist> + + <sect3> + <title>Share Migration</title> + + <para> + The <command>net rpc share migrate</command> command operation permits the migration of plain + share stanzas. A stanza contains the parameters within which a file or print share are defined. + The use of this migration method will create share stanzas that have as parameters the file + system directory path, an optional description, and simple security settings that permit write + access to files. One of the first steps necessary following migration is to review the share + stanzas to ensure that the settings are suitable for use. + </para> + + <para> + The shares are created on-the-fly as part of the migration process. The <command>smbd</command> + application does this by calling on the operating system to execute the script specified by the + &smb.conf; parameter <parameter>add share command</parameter>. + </para> + + <para> + There is a suitable example script for the <parameter>add share command</parameter> in the + <filename>$SAMBA_SOURCES/examples/scripts</filename> directory. It should be noted that + the account that is used to drive the migration must, of necessity, have appropriate file system + access privileges and have the right to create shares and to set ACLs on them. Such rights are + conferred by these rights: <parameter>SeAddUsersPrivilege, SeDiskOperatorPrivilege</parameter>. + For more information regarding rights and privileges please refer to <link linkend="rights"/>. + </para> + + <para> + The syntax of the share migration command is shown here: +<screen> +net rpc share MIGRATE SHARES <share-name> -S <source> + [--destination=localhost] [--exclude=share1,share2] [-v] +</screen> + When the parameter <share-name> is omitted, all shares will be migrated. The potentially + large list of available shares on the system that is being migrated can be limited using the + <parameter>--exclude</parameter> switch. For example: +<screen> +&rootprompt; net rpc share migrate shares myshare\ + -S win2k -U administrator%secret" +</screen> + This will migrate the share <constant>myshare</constant> from the server <constant>win2k</constant> + to the Samba Server using the permissions that are tied to the account <constant>administrator</constant> + with the password <constant>secret</constant>. The account that is used must be the same on both the + migration source server, as well as on the target Samba server. The use of the <command>net rpc + vampire</command>, prior to attempting the migration of shares, will ensure that accounts will be + identical on both systems. One precaution worth taking before commencement of migration of shares is + to validate that the migrated accounts (on the Samba server) have the needed rights and privileges. + This can be done as shown here: +<screen> +&rootprompt; net rpc right list accounts -Uroot%not24get +</screen> + The steps taken so far performs only the migration of shares. Directories and directory contents + are not migrated by the steps covered up to this point. + </para> + + </sect3> + + <sect3> + <title>File and Directory Migration</title> + + <para> + Everything covered to this point has been done in preparation for the migration of file and directory + data. For many people preparation is potentially boring and the real excitement only begins when file + data can be used. The next steps demonstrates the techniques that can be used to transfer (migrate) + data files using the <command>net</command> command. + </para> + + <para> + Transfer of files from one server to another has always been a challenge for Microsoft Windows + administrators because Windows NT and 200X servers do not include the tools needed. The + <command>xcopy</command> is not capable of preserving file and directory ACLs. Microsoft do provide a + utility that can copy ACLs (security settings) called <command>scopy</command>, but it is provided only + as part of the Windows NT or 200X Server Resource Kit. + </para> + + <para> + There are several tools, both commercial and freeware, that can be used from Windows server to copy files + and directories with full preservation of security settings. One of the best known of the free tools is + called <command>robocopy</command>. + </para> + + <para> + The <command>net</command> utility can be used to copy files and directories with full preservation of + ACLs as well as DOS file attributes. Note that including ACLs makes sense only where the destination + system will operate within the same security context as the source system. This applies to both a domain + member server (DMS) as well as for domain controllers (DCs) that result from a vampired domain. + Before file and directory migration all shares must already exist. + </para> + + <para> + The syntax for the migration commands is shown here: +<screen> +net rpc share MIGRATE FILES <share-name> -S <source> + [--destination=localhost] [--exclude=share1,share2] + [--acls] [--attrs] [--timestamps] [-v] +</screen> + If the <share-name> parameter is omitted, all shares will be migrated. The potentially large + list of shares on the source system can be restricted using the <parameter>--exclude</parameter> command + switch. + </para> + + <para> + Where it is necessary to preserve all file ACLs, the <parameter>--acls</parameter> switch should be added + to the above command line. Original file time stamps can be preserved by specifying the + <parameter>--timestamps</parameter> switch, and the DOS file attributes (i.e.: hidden, archive, etc.) cab + be preserved by specifying the <parameter>--attrs</parameter> switch. + </para> + + <note><para> + The ability to preserve ACLs depends on appropriate support for ACLs, as well as the general file system + semantics of the host operating system on the target server. A migration from one Windows file server to + another will perfectly preserve all file attributes. Because of the difficulty of mapping Windows ACLs + onto a POSIX ACLs supporting system, there can be no perfect migration of Windows ACLs to a Samba server. + </para></note> + + <para> + The ACLs that result on a Samba server will most probably not match the originating ACLs. Windows support + the possibility of files that are owned only by a group. Group-alone file ownership is not possible under + UNIX/Linux. Errors in migrating group-owned files can be avoided by using the &smb.conf; file + <smbconfoption name="force unknown acl user">yes</smbconfoption> parameter. This facility will + automatically convert group-owned files into correctly user-owned files on the Samba server. + </para> + + <para> + An example for migration of files from a machine called <constant>nt4box</constant> to the Samba server + from which the process will be handled is shown here: +<screen> +&rootprompt; net rpc share migrate files -S nt4box --acls \ + --attrs -U administrator%secret +</screen> + </para> + + <para> + The above command will migrate all files and directories from all file shares on the Windows server called + <constant>nt4box</constant> to the Samba server from which migration is initiated. Files that are group-owned + will be owned by the user account <constant>administrator</constant>. + </para> + + </sect3> + + <sect3> + <title>Simultaneous Share and File Migration</title> + + <para> + This operating mode shown here is just a combination of the two above. It first migrates + share-definitions and then all shared files and directories afterwards: +<screen> +net rpc share MIGRATE ALL <share-name> -S <source> + [--exclude=share1, share2] [--acls] [--attrs] [--timestamps] [-v] +</screen> + </para> + + <para> + An example of simultaneous migration is shown here: +<screen> +&rootprompt; net rpc share migrate all -S w2k3server -U administrator%secret +</screen> + This will generate a complete server clone of the <parameter>w2k3server</parameter> server. + </para> + + </sect3> + + </sect2> + + <sect2> + <title>Printer Migration</title> + + <para> + The installation of a new server, as with the migration to a new network environment, often has similarity + to the building of a house; progress is very rapid from the laying of foundations up to the stage at which + the the house can be locked-up, but the finishing off appears to take longer and longer as building + approaches completion. + </para> + + <para> + Printing needs vary greatly depending on the network environment, and may be very simple or complex. If + the need is very simple the best solution to the implementation of printing support may well be to + re-install everything from a clean slate instead of migrating older configurations. On the other hand, + a complex network that is integrated with many international offices and a multiplexity of local branch + offices, each of which form an inter-twined maze of printing possibilities, the ability to migrate all + printer configurations is decidedly beneficial. To manually re-establish a complex printing network + will take much time and frustration. Often-times it will not be possible to find driver files that are + currently in use thus necessitating the installation of newer drivers. Newer drivers often implement + printing features that will necessitate a change in the printer usage. Additionally, with very complex + printer configurations it becomes almost impossible to re-create the same environment - not matter + how extensively it has been documented. + </para> + + <para> + The migration of an existing printing architecture involves the following: + </para> + + <itemizedlist> + <listitem><para>Establishment of print queues.</para></listitem> + + <listitem><para>Installation of printer drivers (both for the print server and for Windows clients.</para></listitem> + + <listitem><para>Configuration of printing forms.</para></listitem> + + <listitem><para>Implementation of security settings.</para></listitem> + + <listitem><para>Configuration of printer settings.</para></listitem> + </itemizedlist> + + <para> + The Samba <command>net</command> utility permits printer migration from one Windows print server + to another. When this tool is used to migrate printers to a Samba server <command>smbd</command>, + the application the receives the network requests to create the necessary services, must call-out + to the operating system in order to create the underlying printers. The call-out is implemented + by way of an interface script that can be specified by the &smb.conf; file parameter + <smbconfoption id="add printer script"/>. This script is essential to the migration process. + A suitable example script may be obtained from the <filename>$SAMBA_SOURCES/examples/scripts</filename> + directory. Take note that this script must be customized to suit the operating system environment + and may use its tools to create a print queue. + </para> + + <para> + Each of the components listed above can be completed separately, or they can be completed as part of an + automated operation. Many network administrators prefer to deal with migration issues in a manner that + gives them the most control, particularly when things go wrong. The syntax for each operation will now + be briefly described. + </para> + + <para> + Printer migration from a Windows print server (NT4 or 200X) is shown. This instruction causes the + printer share to be created together with the underlying print queue: +<screen> +net rpc printer MIGRATE PRINTERS [printer] [misc. options] [targets] +</screen> + Printer drivers can be migrated from the Windows print server to the Samba server using this + command line instruction: +<screen> +net rpc printer MIGRATE DRIVERS [printer] [misc. options] [targets] +</screen> + Printer forms can be migrated with the following operation: +<screen> +net rpc printer MIGRATE FORMS [printer] [misc. options] [targets] +</screen> + Printer security settings (ACLs) can be migrated from the Windows server to the Samba server using this command: +<screen> +net rpc printer MIGRATE SECURITY [printer] [misc. options] [targets] +</screen> + Printer configuration settings include factors such as paper size, default paper orientation, etc. + These can be migrated from the Windows print server to the Samba server with this command: +<screen> +net rpc printer MIGRATE SETTINGS [printer] [misc. options] [targets] +</screen> + </para> + + <para> + Migration of printers including all the above mentioned sets of information may be completed + with a single command using this syntax: +<screen> +net rpc printer MIGRATE ALL [printer] [misc. options] [targets] +</screen> + </para> + + </sect2> + + </sect1> + + <sect1> + <title>Controlling Open Files</title> + + <para> + The man page documents the <command>net file</command> function suite. These ability is provided to + close open files using either RAP or RPC function calls. Please refer to the man page for specific + usage information. + </para> + + </sect1> + + <sect1> + <title>Session and Connection Management</title> + + <para> + The session management interface of the <command>net session</command> command uses the old RAP + method to obtain the list of connections to the Samba server, as shown here: +<screen> +&rootprompt; net rap session -S MERLIN -Uroot%not24get +Computer User name Client Type Opens Idle time +------------------------------------------------------------------------------ +\\merlin root Unknown Client 0 00:00:00 +\\marvel jht Unknown Client 0 00:00:00 +\\maggot jht Unknown Client 0 00:00:00 +\\marvel jht Unknown Client 0 00:00:00 +</screen> + </para> + + <para> + A session can be closed by executing a command as shown here: +<screen> +&rootprompt; net rap session close marvel -Uroot%not24get +</screen> + </para> + + </sect1> + + <sect1> + <title>Printers and ADS</title> + + <para> + When Samba-3 is used within as MS Windows ADS environment printers shared via Samba will not be browseable + until they have been published to the ADS domain. Information regarding published printers my be obtained + from the ADS server by executing the <command>net ads print info</command> command following this syntax: +<screen> +net ads printer info <printer_name> <server_name> -Uadministrator%secret +</screen> + If the asterisk (*) is used in place of the printer_name argument, a list of all printers will be + returned. + </para> + + <para> + To publish (make available) a printer to ADS execute the following command: +<screen> +net ads printer publish <printer_name> -Uadministrator%secret +</screen> + This publishes a printer from the local Samba server to ADS. + </para> + + <para> + Removal of a Samba printer from ADS is achieved by executing this command: +<screen> +net ads printer remove <printer_name> -Uadministrator%secret +</screen> + </para> + + <para> + A generic search (query) can also be made to locate a printer across the entire ADS domain by executing: +<screen> +net ads printer search <printer_name> -Uadministrator%secret +</screen> + </para> + + </sect1> + + <sect1> + <title>Manipulating the Samba Cache</title> + + <para> + Please refer to the net command man page for information regarding cache management. + </para> + + </sect1> + + <sect1> + <title>Other Miscellaneous Operations</title> + + <para> + The following command is useful for obtaining basic statistics regarding a Samba domain. This command does + not work against current Windows XP Professional clients. +<screen> +&rootprompt; net rpc info +Domain Name: RAPIDFLY +Domain SID: S-1-5-21-399034208-633907489-3292421255 +Sequence number: 1116312355 +Num users: 720 +Num domain groups: 27 +Num local groups: 6 +</screen> + </para> + + <para> + Another useful tool is the <command>net time</command> tool set. This tool may be used to query the + current time on the target server as shown here: +<screen> +&rootprompt; net time -S SAURON +Tue May 17 00:50:43 2005 +</screen> + In the event that it is the intent to pass the time information obtained to the UNIX + <command>/bin/time</command> it is a good idea to obtain the time from the target server in a format + that is ready to be passed through. This may be done by executing: +<screen> +&rootprompt; net time system -S FRODO +051700532005.16 +</screen> + The time can be set on a target server by executing: +<screen> +&rootprompt; net time set -S MAGGOT -U Administrator%not24get +Tue May 17 00:55:30 MDT 2005 +</screen> + It is possible to obtain the time-zone a server is in by executing the following command against it: +<screen> +&rootprompt; net time zone -S SAURON +-0600 +</screen> + </para> + + </sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Unicode.xml b/docs/Samba3-HOWTO/TOSHARG-Unicode.xml new file mode 100644 index 0000000000..a858a38508 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Unicode.xml @@ -0,0 +1,511 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="unicode"> +<chapterinfo> + &author.jelmer; + &author.jht; + <author> + <firstname>TAKAHASHI</firstname><surname>Motonobu</surname> + <affiliation> + <address><email>monyo@home.monyo.com</email></address> + </affiliation> + <contrib>Japanese character support</contrib> + </author> + <pubdate>25 March 2003</pubdate> +</chapterinfo> + +<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 +<ulink url="http://www.openi18n.org/">Openi18n organization</ulink> +is deserving of special mention. +</para> + +<para> +Samba-2.x supported a single locale through a mechanism called +<emphasis>codepages</emphasis>. Samba-3 is destined to become a truly trans-global +file and printer-sharing platform. +</para> + +</sect1> + +<sect1> +<title>What Are Charsets and Unicode?</title> + +<para> +Computers communicate in numbers. In texts, each number will be +translated to a corresponding letter. The meaning that will be assigned +to a certain number depends on the <emphasis>character set (charset) +</emphasis> that is used. +</para> + +<para> +A charset can be seen as a table that is used to translate numbers to +letters. Not all computers use the same charset (there are charsets +with German umlauts, Japanese characters, and so on). The American Standard Code +for Information Interchange (ASCII) encoding system has been the normative character +encoding scheme used by computers to date. This employs a charset that contains +256 characters. Using this mode of encoding each character takes exactly one byte. +</para> + +<para> +There are also charsets that support extended characters, but those need at least +twice as much storage space as does ASCII encoding. Such charsets can contain +<command>256 * 256 = 65536</command> characters, which is more than all possible +characters one could think of. They are called multi-byte charsets because they use +more then one byte to store one character. +</para> + +<para> +One standardized multi-byte charset encoding scheme is known as +<ulink url="http://www.unicode.org/">unicode</ulink>. A big advantage of using a +multi-byte charset is that you only need one. There is no need to make sure two +computers use the same charset when they are communicating. +</para> + +<para>Old Windows clients use single-byte charsets, named +<parameter>codepages</parameter>, by Microsoft. However, there is no support for +negotiating the charset to be used in the SMB/CIFS protocol. Thus, you +have to make sure you are using the same charset when talking to an older client. +Newer clients (Windows NT, 200x, XP) talk unicode over the wire. +</para> +</sect1> + +<sect1> +<title>Samba and Charsets</title> + +<para> +As of Samba-3, Samba can (and will) talk unicode over the wire. Internally, +Samba knows of three kinds of character sets: +</para> + +<variablelist> + <varlistentry> + <term><smbconfoption name="unix charset"/></term> + <listitem><para> + This is the charset used internally by your operating system. + The default is <constant>UTF-8</constant>, which is fine for most + systems, which covers all characters in all languages. The default + in previous Samba releases was to save filenames in the encoding of the + clients, for example cp850 for western european countries. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><smbconfoption name="display charset"/></term> + <listitem><para>This is the charset Samba will use to print messages + on your screen. It should generally be the same as the <parameter>unix charset</parameter>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><smbconfoption name="dos charset"/></term> + <listitem><para>This is the charset Samba uses when communicating with + DOS and Windows 9x/Me clients. It will talk unicode to all newer clients. + The default depends on the charsets you have installed on your system. + Run <command>testparm -v | grep "dos charset"</command> to see + what the default is on your system. + </para></listitem> + </varlistentry> +</variablelist> + +</sect1> + +<sect1> +<title>Conversion from Old Names</title> + +<para>Because previous Samba versions did not do any charset conversion, +characters in filenames are usually not correct in the UNIX charset but only +for the local charset used by the DOS/Windows clients.</para> + +<para>Bjoern Jacke has written a utility named <ulink url="http://j3e.de/linux/convmv/">convmv</ulink> +that can convert whole directory structures to different charsets with one single command. +</para> + +</sect1> + +<sect1> +<title>Japanese Charsets</title> + +<para> +Setting up Japanese charsets is quite difficult. This is mainly because: +</para> + +<itemizedlist> + <listitem><para>The Windows character set is extended from the original legacy Japanese + standard (JIS X 0208) and is not standardized. This means that the strictly + standardized implementation cannot support the full Windows character set. + </para></listitem> + + <listitem><para> Mainly for historical reasons, there are several encoding methods in + Japanese, which are not fully compatible with each other. There are + two major encoding methods. One is the Shift_JIS series, it is used in Windows + and some UNIX's. The other is the EUC-JP series, used in most UNIX's + and Linux. Moreover, Samba previously also offered several unique encoding + methods, named CAP and HEX, to keep interoperability with CAP/NetAtalk and + UNIX's which can't use Japanese filenames. Some implementations of the + EUC-JP series can't support the full Windows character set. + </para></listitem> + + <listitem><para>There are some code conversion tables between Unicode and legacy + Japanese character sets. One is compatible with Windows, another one + is based on the reference of the Unicode consortium and others are + a mixed implementation. The Unicode consortium does not officially + define any conversion tables between Unicode and legacy character + sets so there cannot be standard one. + </para></listitem> + + <listitem><para>The character set and conversion tables available in iconv() depends + on the iconv library that is available. Next to that, the Japanese locale + names may be different on different systems. This means that the value of + the charset parameters depends on the implementation of iconv() you are using. + </para> + + <para>Though 2 byte fixed UCS-2 encoding is used in Windows internally, + Shift_JIS series encoding is usually used in Japanese environments + as ASCII encoding is in English environments. + </para></listitem> +</itemizedlist> + +<sect2><title>Basic Parameter Setting</title> + + <para> + <smbconfoption name="dos charset"/> and + <smbconfoption name="display charset"/> + should be set to the locale compatible with the character set + and encoding method used on Windows. This is usually CP932 + but sometimes has a different name. + </para> + + <para> + <smbconfoption name="unix charset"/> can be either Shift_JIS series, + EUC-JP series and UTF-8. UTF-8 is always available but the availability of other locales + and its name itself depends on the system. + </para> + + <para> + Additionally, you can consider to use the Shift_JIS series as the + value of the <smbconfoption name="unix charset"/> + parameter by using the vfs_cap module, which does the same thing as + setting <quote>coding system = CAP</quote> in the Samba 2.2 series. + </para> + + <para> + Where to set <smbconfoption name="unix charset"/> + to is a difficult question. Here is a list of details, advantages and + disadvantages of using a certain value. + </para> + + <variablelist> + <varlistentry><term>Shift_JIS series</term> + <listitem><para> + Shift_JIS series means a locale which is equivalent to <constant>Shift_JIS</constant>, + used as a standard on Japanese Windows. In the case of <constant>Shift_JIS</constant>, + for example if a Japanese file name consist of 0x8ba4 and 0x974c + (a 4 bytes Japanese character string meaning <quote>share</quote>) and <quote>.txt</quote> + is written from Windows on Samba, the file name on UNIX becomes + 0x8ba4, 0x974c, <quote>.txt</quote> (a 8 bytes BINARY string), same as Windows. + </para> + + <para>Since Shift_JIS series is usually used on some commercial based + UNIX's; hp-ux and AIX as Japanese locale (however, it is also possible + to use the EUC-JP series), To use Shift_JIS series on these platforms, + Japanese file names created from Windows can be referred to also on + UNIX.</para> + + <para> + If your UNIX is already working with Shift_JIS and there is a user + who needs to use Japanese file names written from Windows, the + Shift_JIS series is the best choice. However, broken file names + may be displayed and some commands which cannot handle non-ASCII + filenames may be aborted during parsing filenames. especially there + may be <quote>\ (0x5c)</quote> in file names, which need to be handled carefully. + So you had better not touch file names written from Windows on UNIX. + </para> + + <para> + Note that most Japanized free software actually works with EUC-JP + only. You had better verify if the Japanized free software can work + with Shift_JIS. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>EUC-JP series</term> + <listitem><para> + EUC-JP series means a locale which is equivalent to the industry + standard called EUC-JP, widely used in Japanese UNIX (although EUC + contains specifications for languages other than Japanese, such as + EUC-KR). In the case of EUC-JP series, for example if a Japanese + file name consist of 0x8ba4 and 0x974c and <quote>.txt</quote> is written from + Windows on Samba, the file name on UNIX becomes 0xb6a6, 0xcdad, + <quote>.txt</quote> (a 8 bytes BINARY string). + </para> + + <para> + Since EUC-JP is usually used on Open source UNIX, Linux and FreeBSD, + and on commercial based UNIX, Solaris, IRIX and Tru64 UNIX as + Japanese locale (however, it is also possible on Solaris to use + Shift_JIS and UTF-8, on Tru64 UNIX to use Shift_JIS). To use EUC-JP + series, most Japanese file names created from Windows can be + referred to also on UNIX. Also, most Japanized free software work + mainly with EUC-JP only. + </para> + + <para> + It is recommended to choose EUC-JP series when using Japanese file + names on these UNIX. + </para> + + <para> + Although there is no character which needs to be carefully treated + like <quote>\ (0x5c)</quote>, broken file names may be displayed and some + commands which cannot handle non-ASCII filenames may be aborted + during parsing filenames. + </para> + + <para> + Moreover, if you built Samba using differently installed libiconv, + eucJP-ms locale included in libiconv and EUC-JP series locale + included in OS may not be compatible. In this case, you may need to + avoid using incompatible characters for file names. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>UTF-8</term> + <listitem><para> + UTF-8 means a locale which is equivalent to UTF-8, the international + standard defined by Unicode consortium. In UTF-8, a <parameter>character</parameter> is + expressed using 1-3 bytes. In case of Japanese, most characters + are expressed using 3 bytes. Since on Windows Shift_JIS, where a + character is expressed with 1 or 2 bytes, is used to express + Japanese, basically a byte length of a UTF-8 string grows 1.5 times + the length of a original Shift_JIS string. In the case of UTF-8, + for example if a Japanese file name consist of 0x8ba4 and 0x974c and + <quote>.txt</quote> is written from Windows on Samba, the file name on UNIX + becomes 0xe585, 0xb1e6, 0x9c89, <quote>.txt</quote> (a 10 bytes BINARY string). + </para> + + <para> + For systems where iconv() is not available or where iconv()'s locales + are not compatible with Windows, UTF-8 is the only locale available. + </para> + + <para> + There are no systems that use UTF-8 as default locale for Japanese. + </para> + + <para> + Some broken file names may be displayed and some commands which + cannot handle non-ASCII filenames may be aborted during parsing + filenames. especially there may be <quote>\ (0x5c)</quote> in file names, which + need to be handled carefully. So you had better not touch file names + written from Windows on UNIX. + </para> + + <para> + In addition, although it is not directly concerned with Samba, since + there is a delicate difference between iconv() function, which is + generally used on UNIX and the functions used on other platforms, + such as Windows and Java about the conversion table between + Shift_JIS and Unicode, you should be carefully to handle UTF-8. + </para> + + <para> + Although Mac OS X uses UTF-8 as its encoding method for filenames, + it uses an extended UTF-8 specification that Samba cannot handle so + UTF-8 locale is not available for Mac OS X. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Shift_JIS series + vfs_cap (CAP encoding)</term> + <listitem><para> + CAP encoding means a specification using in CAP and NetAtalk, file + server software for Macintosh. In the case of CAP encoding, for + example if a Japanese file name consist of 0x8ba4 and 0x974c and + <quote>.txt</quote> is written from Windows on Samba, the file name on UNIX + becomes <quote>:8b:a4:97L.txt</quote> (a 14 bytes ASCII string). + </para> + + <para> + For CAP encoding a byte which cannot be expressed as an ASCII + character (0x80 or above) is encoded as <quote>:xx</quote> form. You need to take + care of containing a <quote>\(0x5c)</quote> in a filename but filenames are not + broken in a system which cannot handle non-ASCII filenames. + </para> + + <para> + The greatest merit of CAP encoding is the compatibility of encoding + filenames with CAP or NetAtalk, file server software of Macintosh. + Since they usually write a file name on UNIX with CAP encoding, if a + directory is shared with both Samba and NetAtalk, you need to use + CAP encoding to avoid non-ASCII filenames are broken. + </para> + + <para> + However, recently there are some systems where NetAtalk has been + patched to write filenames with EUC-JP (i.e. Japanese original Vine Linux). + Here you need to choose EUC-JP series instead of CAP encoding. + </para> + + <para> + vfs_cap itself is available for non Shift_JIS series locales for + systems which cannot handle non-ASCII characters or systems which + shares files with NetAtalk. + </para> + + <para> + To use CAP encoding on Samba-3, you should use the unix charset parameter and VFS + as follows: + </para> + +<smbconfexample><title>VFS CAP</title> +<smbconfsection name="[global]"/> +<smbconfcomment>the locale name "CP932" may be different</smbconfcomment> +<smbconfoption name="dos charset">CP932</smbconfoption> +<smbconfoption name="unix charset">CP932</smbconfoption> + +<smbconfsection name="[cap-share]"/> +<smbconfoption name="vfs option">cap</smbconfoption> +</smbconfexample> + + <para> + You should set CP932 if using GNU libiconv for unix charset. Setting this, + filenames in the <quote>cap-share</quote> share are written with CAP encoding. + </para> + </listitem> + </varlistentry> + </variablelist> + +</sect2> + +<sect2><title>Individual Implementations</title> + +<para> +Here is some additional information regarding individual implementations: +</para> + + <variablelist> + <varlistentry><term>GNU libiconv</term> + <listitem><para> + To handle Japanese correctly, you should apply the patch + <ulink url="http://www2d.biglobe.ne.jp/~msyk/software/libiconv-patch.html">libiconv-1.8-cp932-patch.diff.gz</ulink> + to libiconv-1.8. + </para> + + <para> + Using the patched libiconv-1.8, these settings are available: + </para> + + +<!-- FIXME: Convert to diagram ? --> +<programlisting> +dos charset = CP932 +unix charset = CP932 / eucJP-ms / UTF-8 + | | + | +-- EUC-JP series + +-- Shift_JIS series +display charset = CP932 +</programlisting> + + <para> + Other Japanese locales (for example Shift_JIS and EUC-JP) should not + be used for the lack of the compatibility with Windows. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>GNU glibc</term> + <listitem><para> + To handle Japanese correctly, you should apply a <ulink url="http://www2d.biglobe.ne.jp/~msyk/software/glibc/">patch</ulink> + to glibc-2.2.5/2.3.1/2.3.2 or should use the patch-merged versions, glibc-2.3.3 or later. + </para> + + <para> + Using the above glibc, these setting are available: + </para> + +<smbconfblock> +<smbconfoption name="dos charset">CP932</smbconfoption> +<smbconfoption name="unix charset">CP932 / eucJP-ms / UTF-8</smbconfoption> +<smbconfoption name="display charset">CP932</smbconfoption> +</smbconfblock> + + <para> + Other Japanese locales (for example Shift_JIS and EUC-JP) should not + be used for the lack of the compatibility with Windows. + </para> + </listitem> + </varlistentry> + </variablelist> + +</sect2> + +<sect2> + <title>Migration from Samba-2.2 Series</title> + +<para> +Prior to Samba-2.2 series <quote>coding system</quote> parameter is used as +<smbconfoption name="unix charset"/> parameter of the Samba-3 series. +<link linkend="japancharsets">Next table</link> shows the mapping table when migrating from the Samba-2.2 series to Samba-3. +</para> + + <table frame="all" id="japancharsets"> + <title>Japanese Character Sets in Samba-2.2 and Samba-3</title> + + <tgroup cols="2" align="center"> + <colspec align="center"/> + <colspec align="center"/> + <thead> + <row><entry>Samba-2.2 Coding System</entry><entry>Samba-3 unix charset</entry></row> + </thead> + <tbody> + <row><entry>SJIS</entry><entry>Shift_JIS series</entry></row> + <row><entry>EUC</entry><entry>EUC-JP series</entry></row> + <row><entry>EUC3<footnote><para>Only exists in Japanese Samba version</para></footnote></entry><entry>EUC-JP series</entry></row> + <row><entry>CAP</entry><entry>Shift_JIS series + VFS</entry></row> + <row><entry>HEX</entry><entry>currently none</entry></row> + <row><entry>UTF8</entry><entry>UTF-8</entry></row> + <row><entry>UTF8-Mac<footnote><para>Only exists in Japanese Samba version</para></footnote></entry><entry>currently none</entry></row> + <row><entry>others</entry><entry>none</entry></row> + </tbody> + </tgroup> + </table> + +</sect2> + +</sect1> + +<sect1> + <title>Common Errors</title> + + <sect2> + <title>CP850.so Can't Be Found</title> + + <para><quote>Samba is complaining about a missing <filename>CP850.so</filename> file.</quote></para> + + <para><emphasis>Answer:</emphasis> CP850 is the default <smbconfoption name="dos charset"/>. + The <smbconfoption name="dos charset"/> is used to convert data to the codepage used by your dos clients. + If you do not have any dos clients, you can safely ignore this message. </para> + + <para>CP850 should be supported by your local iconv implementation. Make sure you have all the required packages installed. + If you compiled Samba from source, make sure to configure found iconv.</para> + </sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-VFS.xml b/docs/Samba3-HOWTO/TOSHARG-VFS.xml new file mode 100644 index 0000000000..3fdcc0ea81 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-VFS.xml @@ -0,0 +1,631 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="VFS"> +<chapterinfo> + &author.jelmer; + &author.jht; + &author.tpot; + <author><firstname>Simo</firstname><surname>Sorce</surname><contrib>original vfs_skel README</contrib></author> + <author><firstname>Alexander</firstname><surname>Bokovoy</surname><contrib>original vfs_netatalk docs</contrib></author> + <author><firstname>Stefan</firstname><surname>Metzmacher</surname><contrib>Update for multiple modules</contrib></author> + <author><firstname>Ed</firstname><surname>Riddle</surname><contrib>original shadow_copy docs</contrib></author> +</chapterinfo> +<title>Stackable VFS modules</title> + +<sect1> +<title>Features and Benefits</title> + +<para> +Since Samba-3, there is support for stackable VFS (Virtual File System) modules. +Samba passes each request to access the UNIX file system through 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> +If not supplied with your platform distribution binary Samba package you may have problems +compiling 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 <smbconfoption name="vfs objects"/> parameter where +you can list one or more VFS modules by name. For example, to log all access +to files and put deleted files in a recycle bin, see <link linkend="vfsrecyc">next configuration</link>: + +<smbconfexample id="vfsrecyc"> + <title>smb.conf with VFS modules</title> + <smbconfsection name="[audit]"/> +<smbconfoption name="comment">Audited /data directory</smbconfoption> +<smbconfoption name="path">/data</smbconfoption> +<smbconfoption name="vfs objects">audit recycle</smbconfoption> +<smbconfoption name="writeable">yes</smbconfoption> +<smbconfoption name="browseable">yes</smbconfoption> + </smbconfexample> +</para> + +<para> +The modules are used in the order in which they are specified. +Let's say that you want to both have a virus scanner module and a recycle +bin module. It is wise to put the virus scanner module as the first one so +that it is the first that get run an may detect a virus immediately, before +any action is performed on that file. +<smbconfoption name="vfs objects">vscan-clamav recycle</smbconfoption> +</para> + +<para> +Samba will attempt to load modules from the <filename>/lib</filename> directory in the root directory of the +Samba installation (usually <filename>/usr/lib/samba/vfs</filename> or <filename>/usr/local/samba/lib/vfs +</filename>). +</para> + +<para> +Some modules can be used twice for the same share. +This can be done using a configuration similar to the one shown in <link linkend="multimodule">the following example</link>. + +<smbconfexample id="multimodule"> + <title>smb.conf with multiple VFS modules</title> +<smbconfsection name="[test]"/> +<smbconfoption name="comment">VFS TEST</smbconfoption> +<smbconfoption name="path">/data</smbconfoption> +<smbconfoption name="writeable">yes</smbconfoption> +<smbconfoption name="browseable">yes</smbconfoption> +<smbconfoption name="vfs objects">example:example1 example example:test</smbconfoption> +<smbconfoption name="example1: parameter">1</smbconfoption> +<smbconfoption name="example: parameter">5</smbconfoption> +<smbconfoption name="test: parameter">7</smbconfoption> +</smbconfexample> +</para> + +</sect1> + +<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: + <itemizedlist> + <listitem><para>share</para></listitem> + <listitem><para>connect/disconnect</para></listitem> + <listitem><para>directory opens/create/remove</para></listitem> + <listitem><para>file open/close/rename/unlink/chmod</para></listitem> + </itemizedlist> + </para> + + </sect2> + + <sect2> + <title>extd_audit</title> + + <para> + This module is identical with the <command>audit</command> module above except + that it sends audit logs to both syslog as well as the <command>smbd</command> log files. The + <smbconfoption name="log level"/> for this module is set in the &smb.conf; file. + </para> + + <para> + Valid settings and the information that will be recorded are shown in <link linkend="xtdaudit">the next table</link>. + </para> + + <table frame="all" id="xtdaudit"> + <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">Make Directory, Remove Directory, Unlink</entry></row> + <row><entry align="center">1</entry><entry align="left">Open Directory, Rename File, Change Permissions/ACLs</entry></row> + <row><entry align="center">2</entry><entry align="left">Open & Close File</entry></row> + <row><entry align="center">10</entry><entry align="left">Maximum Debug Level</entry></row> + </tbody> + </tgroup> + </table> + + <sect3> + <title>Configuration of Auditing</title> + + <para> + This auditing tool is more felxible than most people readily will recognize. There are a number of ways + by which useful logging information can be recorded. + </para> + + <itemizedlist> + <listitem><para>Syslog can be used to record all transaction. This can be disabled by setting + in the &smb.conf; file <parameter>syslog = 0</parameter>.</para></listitem> + <listitem><para>Logging can take place to the default log file (<filename>log.smbd</filename>) + for all loaded VFS modules just by setting in the &smb.conf; file + <parameter>log level = 0 vfs:x</parameter>, where x is the log level. + This will disable general logging while activating all logging of VFS + module activity at the log level specified.</para></listitem> + <listitem><para>Detailed logging can be obtained per user, per client machine, etc. + This requires the above together with the creative use of the + <parameter>log file</parameter> settings.</para> + <para>An example of detailed per-user and per-machine logging can + be obtained by setting + <smbconfoption name="log file">/var/log/samba/%U.%m.log</smbconfoption>. + </para></listitem> + </itemizedlist> + + <para> + Auditing information often must be preserved for a long time. So that the log files do not get rotated + it is essential that the <smbconfoption name="max log size">0</smbconfoption> be set + in the &smb.conf; file. + </para> + + </sect3> + + </sect2> + + <sect2 id="fakeperms"> + <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, report to the client + that the Profile files and directories are writeable. 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. Where used, unlink calls will be intercepted and files moved + to the recycle directory instead of being deleted. This gives the same effect as the + <guiicon>Recycle Bin</guiicon> on Windows computers. + </para> + + <para> + The <guiicon>Recycle Bin</guiicon> will not appear in <application>Windows Explorer</application> views of the network file system + (share) nor on any mapped drive. Instead, a directory called <filename>.recycle</filename> will be + automatically created when the first file is deleted. Users can recover files from the + <filename>.recycle</filename> directory. If the <parameter>recycle:keeptree</parameter> has been + specified, deleted files will be found in a path identical with that from which the file was deleted. + </para> + + <para>Supported options for the <command>recycle</command> module are as follow: + <variablelist> + <varlistentry> + <term>recycle:repository</term> + <listitem><para> + Relative path of the directory where deleted files should be moved. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:keeptree</term> + <listitem><para> + Specifies whether the directory structure should be kept or if the files in the directory that is being + deleted should be kept separately in the recycle bin. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:versions</term> + <listitem><para> + If this option is set, two files + with the same name that are deleted will both + be kept in the recycle bin. Newer deleted versions + of a file will be called <quote>Copy #x of <replaceable>filename</replaceable></quote>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:touch</term> + <listitem><para> + Specifies whether a file's access date should be touched when the file is moved to the recycle bin. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:maxsize</term> + <listitem><para> + Files that are larger than the number of bytes specified by this parameter will not be put into the recycle bin. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:exclude</term> + <listitem><para> + List of files that should not be put into the recycle bin when deleted, but deleted in the regular way. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:exclude_dir</term> + <listitem><para> + Contains a list of directories. When files from these directories are + deleted, they are not put into the + recycle bin but are deleted in the + regular way. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>recycle:noversions</term> + <listitem><para> + Specifies a list of paths (wildcards such as * and ? are supported) for which no versioning should be used. Only useful when <emphasis>recycle:versions</emphasis> is enabled. + </para></listitem> + </varlistentry> + </variablelist> + </para> + + </sect2> + + <sect2> + <title>netatalk</title> + + <para> + A netatalk module will ease co-existence of Samba and netatalk file sharing services. + </para> + + <para>Advantages compared to the old netatalk module: + <itemizedlist> + <listitem><para>Does not care about creating .AppleDouble forks, just keeps them in sync.</para></listitem> + <listitem><para>If a share in &smb.conf; does not contain .AppleDouble item in hide or veto list, it will be added automatically.</para></listitem> + </itemizedlist> + </para> + + </sect2> + + <sect2> + <title>shadow_copy</title> + <warning> + <para> + <emphasis>THIS IS NOT A BACKUP, ARCHIVAL, OR VERSION CONTROL + SOLUTION!</emphasis></para> + <para> + With Samba or Windows servers, shadow copy is designed to be + an end-user tool only. It does not replace or enhance your + backup and archival solutions and should in no way be + considered as such. Additionally, if you need version + control, implement a version control system. You have been + warned.</para> + </warning> + <para> + The shadow_copy module allows you to setup functionality that + is similar to MS shadow copy services. When setup properly, + this module allows Microsoft shadow copy clients to browse + "shadow copies" on samba shares. You will need to install the + shadow copy client. You can get the MS shadow copy client + <ulink noescape="1" + url="http://www.microsoft.com/windowsserver2003/downloads/shadowcopyclient.mspx">here.</ulink>. + Note the additional requirements for pre-Windows XP clients. + I did not test this functionality with any pre-Windows XP + clients. You should be able to get more information about MS + Shadow Copy <ulink noescape="1" + url="http://www.microsoft.com/windowsserver2003/techinfo/overview/scr.mspx">from + the Microsoft's site</ulink>.</para> + <para> + The shadow_copy VFS module requires some underlying file system + setup with some sort of Logical Volume Manager (LVM) such as + LVM1, LVM2, or EVMS. Setting up LVM is beyond the scope of + this document; however, we will outline the steps we took to + test this functionality for <emphasis>example purposes + only.</emphasis> You need to make sure the LVM implementation + you choose to deploy is ready for production. Make sure you + do plenty of tests.</para> + <para> + Here are some common resources for LVM and EVMS: + <itemizedlist> + <listitem> + <para><ulink noescape="1" + url="http://www.sistina.com/products_lvm_download.htm">Sistina's + LVM1 and LVM2</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://evms.sourceforge.net/">Enterprise + Volume Management System (EVMS)</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://tldp.org/HOWTO/LVM-HOWTO/">The LVM HOWTO</ulink></para> + </listitem> + <listitem> + <para> + See <ulink + url="http://www-106.ibm.com/developerworks/linux/library/l-lvm/">Learning + Linux LVM, Part 1</ulink> and <ulink + url="http://www-106.ibm.com/developerworks/library/l-lvm2.html">Learning + Linux LWM, Part 2</ulink> for Daniel Robbins' well + written a two part tutorial on Linux and LVM using LVM + source code and reiserfs.</para> + </listitem> + </itemizedlist> + </para> + <sect3> + <title>Shadow Copy Setup</title> + <para> + At the time of this writing, not much testing has been done. + I tested the shadow copy VFS module with a specific scenario + which was not deployed in a production environment, but more + as a proof of concept. The scenario involved a Samba 3 file + server on Debian Sarge with an XFS file system and LVM1. I + do NOT recommend you use this as a solution without doing + your own due diligence with regard to all the components + presented here. That said, following is an basic outline of + how I got things going.</para> + <orderedlist> + <listitem> + <formalpara> + <title>Installed Operating System </title> + <para> + In my tests, I used <ulink + url="http://www.debian.org/devel/debian-installer/">Debian + Sarge</ulink> (i.e. testing) on an XFS file system. + Setting up the OS is a bit beyond the scope of this + document. It is assumed that you have a working OS + capable of running Samba.</para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>Install & Configure Samba</title> + <para> + See the <link linkend="introduction">installation + section</link> of this HOWTO for more detail on this. + It doesn't matter if it is a Domain Controller or + Member File Server, but it is assumed that you have a + working Samba 3.0.3 or newer server running.</para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>Install & Configure LVM</title> + <para> + Before you can make shadow copies available to the + client, you have to create the shadow copies. This is + done by taking some sort of file system snapshot. + Snapshots are a typical feature of Logical Volume + Managers such as LVM, so we first need to have that + setup.</para> + </formalpara> + <itemizedlist> + <para> + The following is provided as an example and will be + most helpful for Debian users. Again, this was tested + using the "testing" or "Sarge" distribution.</para> + <listitem> + <para> + Install lvm10 and devfsd packages if you have not + done so already. On Debian systems, you are warned + of the interaction of devfs and lvm1 which requires + the use of devfs filenames. Running + <command>apt-get update && apt-get install + lvm10 devfsd xfsprogs</command> should do the trick + for this example.</para> + </listitem> + <listitem> + <para> + Now you need to create a volume. You will need to + create a partition (or partitions) to add to your + volume. Use your favorite partitioning tool + (e.g. Linux fdisk, cfdisk, etc.). The partition + type should be set to 0x8e for "Linux LVM." In this + example, we will use /dev/hdb1.</para> + <para> + Once you have the Linux LVM partition (type 0x8e), + you can run a series of commands to create the LVM + volume. You can use several disks and or + partitions, but we will use only one in this + example. You may also need to load the kernel + module with something like <command>modprobe lvm-mod + </command> and set your system up to load it on + reboot by adding it to + (<filename>/etc/modules</filename>). </para> + </listitem> + <listitem> + <para> + Create the physical volume with <command>pvcreate + /dev/hdb1</command></para> + </listitem> + <listitem> + <para> + Create the volume group with and add /dev/hda1 to it + with <command>vgcreate shadowvol /dev/hdb1</command> + </para> + <para> + You can use <command>vgdisplay</command> to review + information about the volume group.</para> + </listitem> + <listitem> + <para> + Now you can create the logical volume with something + like <command>lvcreate -L400M -nsh_test + shadowvol</command></para> + <para> + This creates the logical volume of 400MB's named + "sh_test" in the volume group we created called + shadowvol. If everything is working so far, you + should see them in + <filename>/dev/shadowvol</filename>.</para> + </listitem> + <listitem> + <para> + Now we should be ready to format the logical volume + we named sh_test with <command>mkfs.xfs + /dev/shadowvol/sh_test</command></para> + <para> + You can format the logical volume with any file + system you choose, but make sure to use one that + allows you to take advantage of the additional + features of LVM such as freezing, resizing and + growing your file systems.</para> + <para> + Now we have an LVM volume where we can play with the + shadow_copy VFS module.</para> + </listitem> + <listitem> + <para> + Now we need to prepare the directory with something + like <command>mkdir -p /data/shadow_share</command> + or whatever you want to name your shadow copy + enabled Samba share. Make sure you set the + permissions such that you can use it. If in doubt, + use <command>chmod 777 /data/shadow_share</command> + and tighten the permissions once you get things + working.</para> + </listitem> + <listitem> + <para> + Mount the LVM volume using something like + <command>mount /dev/shadowvol/sh_test + /data/shadow_share</command></para> + <para> + You may also want to edit your + <filename>/etc/fstab</filename> so that this + partition mounts during the system boot.</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <formalpara> + <title>Install & Configure the shadow_copy VFS + Module</title> + <para> + Finally we get to the actual shadow_copy VFS module. + The shadow_copy VFS module should be available in + Samba 3.0.3 and higher. The smb.conf configuration is pretty + standard. Here is our example of a share configured + with the shadow_copy VFS module:</para> + </formalpara> + <para> + <smbconfexample id="vfsshadow"> + <title>Share With shadow_copy VFS</title> + <smbconfsection name="[shadow_share]"/> + <smbconfoption name="comment">Shadow Copy Enabled Share</smbconfoption> + <smbconfoption name="path">/data/shadow_share</smbconfoption> + <smbconfoption name="vfs objects">shadow_copy</smbconfoption> + <smbconfoption name="writeable">yes</smbconfoption> + <smbconfoption name="browseable">yes</smbconfoption> + </smbconfexample> + </para> + </listitem> + <listitem> + <formalpara> + <title>Create Snapshots and Make Them Available to shadow_copy.so</title> + <para> + Before you can browse the shadow copies, you must + create them and mount them. This will most likely be + done with a script that runs as a cron job. With this + particular solution, the shadow_copy VFS module is + used to browse LVM snapshots. Those snapshots are not + created by the module. They are not made available by + the module either. This module allows the shadow copy + enabled client to browse the snapshots you take and + make available.</para> + </formalpara> + <para> + Here is a simple script used to create and mount the + snapshots: + <screen> +#!/bin/bash +# This is a test, this is only a test +SNAPNAME=`date +%Y.%m.%d-%H.%M.%S` +xfs_freeze -f /data/shadow_share/ +lvcreate -L10M -s -n $SNAPNAME /dev/shadowvol/sh_test +xfs_freeze -u /data/shadow_share/ +mkdir /data/shadow_share/@GMT-$SNAPNAME +mount /dev/shadowvol/$SNAPNAME /data/shadow_share/@GMT-$SNAPNAME -onouuid,ro + </screen> + Note that the script does not handle other things like + remounting snapshots on reboot. + </para> + </listitem> + <listitem> + <formalpara> + <title>Test From Client</title> + <para> + To test, you will need to install the shadow copy + client which you can obtain from the <ulink + url="http://www.microsoft.com/windowsserver2003/downloads/shadowcopyclient.mspx">Microsoft + web site.</ulink> I only tested this with an XP client + so your results may vary with other pre-XP clients. + Once installed, with your XP client you can + right-click on specific files or in the empty space of + the shadow_share and view the "properties". If + anything has changed, then you will see it on the + "Previous Versions" tab of the properties + window. </para> + </formalpara> + </listitem> + </orderedlist> + </sect3> + </sect2> + +</sect1> + +<sect1> +<title>VFS Modules Available Elsewhere</title> + +<para> +This section contains a listing of various other VFS modules that +have been posted but do not currently reside in the Samba CVS +tree for one reason or another (e.g., it is easy for the maintainer +to have his or her own CVS tree). +</para> + +<para> +No statements about the stability or functionality of any module +should be implied due to its presence here. +</para> + + <sect2> + <title>DatabaseFS</title> + + <para> + URL: <ulink noescape="1" 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> + I have created a VFS module that 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 + <quote>Artists,</quote> <quote>Song Keywords,</quote> and so on. I have since easily + applied it to a student + roster database.) 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, + and so on. If nothing else, hopefully it might prove useful for someone + else who wishes to create a virtual filesystem. + </para> + + </sect2> + + <sect2> + <title>vscan</title> + + <para>URL: <ulink noescape="1" url="http://www.openantivirus.org/projects.php#samba-vscan">http://www.openantivirus.org/projects.php#samba-vscan</ulink></para> + + <para> + samba-vscan is a proof-of-concept module for Samba, which + provides on-access anti-virus support for files shared using + Samba. + samba-vscan supports various virus scanners and is maintained + by Rainer Link. + </para> + + </sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-Winbind.xml b/docs/Samba3-HOWTO/TOSHARG-Winbind.xml new file mode 100644 index 0000000000..eabdcf9a72 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-Winbind.xml @@ -0,0 +1,1302 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="winbind"> + +<chapterinfo> + <author> + <firstname>Tim</firstname><surname>Potter</surname> + <affiliation> + <orgname>Samba Team</orgname> + <address><email>tpot@linuxcare.com.au</email></address> + </affiliation> + </author> + &author.tridge; + <author> + <firstname>Naag</firstname><surname>Mummaneni</surname> + <affiliation> + <address><email>getnag@rediffmail.com</email></address> + </affiliation> + <contrib>Notes for Solaris</contrib> + </author> + <author> + <firstname>John</firstname><surname>Trostel</surname> + <affiliation> + <orgname>SNAP</orgname> + <address><email>jtrostel@snapserver.com</email></address> + </affiliation> + </author> + + &author.jelmer; + &author.jht; + <pubdate>27 June 2002</pubdate> +</chapterinfo> + +<title>Winbind: Use of Domain Accounts</title> + +<sect1> + <title>Features and Benefits</title> + + <para> + Integration of UNIX and Microsoft Windows NT through a unified logon has + been considered a <quote>holy grail</quote> in heterogeneous computing environments for + a long time. + </para> + + <para> + There is one other facility without which UNIX and Microsoft Windows network + interoperability would suffer greatly. It is imperative that there be a + mechanism for sharing files across UNIX systems and to be able to assign + domain user and group ownerships with integrity. + </para> + + <para> + <emphasis>winbind</emphasis> is a component of the Samba suite of programs that + solves the unified logon problem. Winbind uses a UNIX implementation of Microsoft + RPC calls, Pluggable Authentication Modules, and the Name Service Switch to + allow Windows NT domain users to appear and operate as UNIX users on a UNIX + machine. This chapter describes the Winbind system, explaining the functionality + it provides, how it is configured, and how it works internally. + </para> + + <para> + Winbind provides three separate functions: + </para> + + <itemizedlist> + <listitem><para> + Authentication of user credentials (via PAM). This makes it possible to + log onto a UNIX/Linux system using user and group accounts from a Windows + NT4 (including a Samba domain) or an Active Directory domain. + </para></listitem> + + <listitem><para> + Identity resolution (via NSS). This is the default when winbind is not used. + </para></listitem> + + <listitem><para> + Winbind maintains a database called winbind_idmap.tdb in which it stores + mappings between UNIX UIDs / GIDs and NT SIDs. This mapping is used only + for users and groups that do not have a local UID/GID. It stored the UID/GID + allocated from the idmap uid/gid range that it has mapped to the NT SID. + If <parameter>idmap backend</parameter> has been specified as <constant>ldap:ldap://hostname[:389]</constant> + then instead of using a local mapping Winbind will obtain this information + from the LDAP database. + </para></listitem> + </itemizedlist> + + <note><para> + <indexterm><primary>winbindd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm> + If <command>winbindd</command> is not running, smbd (which calls <command>winbindd</command>) will fall back to + using purely local information from <filename>/etc/passwd</filename> and <filename>/etc/group</filename> and no dynamic + mapping will be used. On an operating system that has beeb enabled with the name service switcher (NSS) + the resoltion of user and group information will be accomplished via NSS. + </para></note> + + + <image id="winbind_idmap"> + <imagedescription>Winbind Idmap</imagedescription> + <imagefile scale="50">idmap_winbind_no_loop</imagefile> + </image> + +</sect1> + + +<sect1> + <title>Introduction</title> + + <para>It is well known that UNIX and Microsoft Windows NT have + different models for representing user and group information and + use different technologies for implementing them. This fact has + made it difficult to integrate the two systems in a satisfactory + manner.</para> + + <para>One common solution in use today has been to create + identically named user accounts on both the UNIX and Windows systems + and use the Samba suite of programs to provide file and print services + between the two. This solution is far from perfect, however, as + adding and deleting users on both sets of machines becomes a chore + and two sets of passwords are required &smbmdash; both of which + can lead to synchronization problems between the UNIX and Windows + systems and confusion for users.</para> + + <para>We divide the unified logon problem for UNIX machines into + three smaller problems:</para> + + <itemizedlist> + <listitem><para>Obtaining Windows NT user and group information. + </para></listitem> + + <listitem><para>Authenticating Windows NT users. + </para></listitem> + + <listitem><para>Password changing for Windows NT users. + </para></listitem> + </itemizedlist> + + + <para>Ideally, a prospective solution to the unified logon problem + would satisfy all the above components without duplication of + information on the UNIX machines and without creating additional + tasks for the system administrator when maintaining users and + groups on either system. The Winbind system provides a simple + and elegant solution to all three components of the unified logon + problem.</para> +</sect1> + + +<sect1> + <title>What Winbind Provides</title> + + <para>Winbind unifies UNIX and Windows NT account management by + allowing a UNIX box to become a full member of an NT domain. Once + this is done the UNIX box will see NT users and groups as if + they were <quote>native</quote> UNIX users and groups, allowing the NT domain + to be used in much the same manner that NIS+ is used within + UNIX-only environments.</para> + + <para>The end result is that whenever a + program on the UNIX machine asks the operating system to lookup + a user or group name, the query will be resolved by asking the + NT Domain Controller for the specified domain to do the lookup. + Because Winbind hooks into the operating system at a low level + (via the NSS name resolution modules in the C library), this + redirection to the NT Domain Controller is completely + transparent.</para> + + <para>Users on the UNIX machine can then use NT user and group + names as they would <quote>native</quote> UNIX names. They can chown files + so they are owned by NT domain users or even login to the + UNIX machine and run a UNIX X-Window session as a domain user.</para> + + <para>The only obvious indication that Winbind is being used is + that user and group names take the form <constant>DOMAIN\user</constant> and + <constant>DOMAIN\group</constant>. This is necessary as it allows Winbind to determine + that redirection to a Domain Controller is wanted for a particular + lookup and which trusted domain is being referenced.</para> + + <para>Additionally, Winbind provides an authentication service + that hooks into the Pluggable Authentication Modules (PAM) system + to provide authentication via an NT domain to any PAM-enabled + applications. This capability solves the problem of synchronizing + passwords between systems since all passwords are stored in a single + location (on the Domain Controller).</para> + + <sect2> + <title>Target Uses</title> + + <para>Winbind is targeted at organizations that have an + existing NT-based domain infrastructure into which they wish + to put UNIX workstations or servers. Winbind will allow these + organizations to deploy UNIX workstations without having to + maintain a separate account infrastructure. This greatly + simplifies the administrative overhead of deploying UNIX + workstations into an NT-based organization.</para> + + <para>Another interesting way in which we expect Winbind to + be used is as a central part of UNIX-based appliances. Appliances + that provide file and print services to Microsoft-based networks + will be able to use Winbind to provide seamless integration of + the appliance into the domain.</para> + </sect2> + + <sect2> + <title>Handling of Foreign SIDs</title> + + <para> + The term <emphasis>foreign SID</emphasis> is often met with the reaction that it + is not relevant to a particular environment. The following documents an interchange + that took place on the Samba mailing list. It is a good example of the confusion + often expressed regarding the use of winbind. + </para> + + <para> + Fact: Winbind is needed to handle users who use workstations that are NOT part + of the local domain. + </para> + + <para> + Response: <quote>Why? I've used samba with workstations that are not part of my domains + lots of times without using winbind. I though winbind was for using samba as a memberserver + in a domain controlled by another samba/windows PDC.</quote> + </para> + + <para> + If the Samba server will be accessed from a domain other than the local Samba domain, or + if there will be access from machines that are not local domain members, winbind will + permit the allocation of UIDs and GIDs from the assigned pool that will keep the identity + of the foreign user separate from users that are members of the Samba domain. + </para> + + <para> + Which means that that winbind is eminently useful in cases where one just has a single + Samba PDC on a local network combined of both domain member and non-domain member workstations. + If winbind is not used, the user george on an windows workstation that is not a domain + member will be able to access the files of a user called george in the account database + of the Samba server that is acting as a PDC. When winbind is used, the default condition + is that the local user george will be treated as the account DOMAIN\george and the + foreign (non-member of the domain) account will be treated as MACHINE\george because + each has a different SID. + </para> + + </sect2> +</sect1> + + + +<sect1> + <title>How Winbind Works</title> + + <para>The Winbind system is designed around a client/server + architecture. A long running <command>winbindd</command> daemon + listens on a UNIX domain socket waiting for requests + to arrive. These requests are generated by the NSS and PAM + clients and is processed sequentially.</para> + + <para>The technologies used to implement Winbind are described + in detail below.</para> + + <sect2> + <title>Microsoft Remote Procedure Calls</title> + + <para>Over the last few years, efforts have been underway + by various Samba Team members to decode various aspects of + the Microsoft Remote Procedure Call (MSRPC) system. This + system is used for most network-related operations between + Windows NT machines including remote management, user authentication + and print spooling. Although initially this work was done + to aid the implementation of Primary Domain Controller (PDC) + functionality in Samba, it has also yielded a body of code that + can be used for other purposes.</para> + + <para>Winbind uses various MSRPC calls to enumerate domain users + and groups and to obtain detailed information about individual + users or groups. Other MSRPC calls can be used to authenticate + NT domain users and to change user passwords. By directly querying + a Windows PDC for user and group information, Winbind maps the + NT account information onto UNIX user and group names.</para> + </sect2> + + <sect2> + <title>Microsoft Active Directory Services</title> + + <para> + Since late 2001, Samba has gained the ability to + interact with Microsoft Windows 2000 using its <quote>Native + Mode</quote> protocols, rather than the NT4 RPC services. + Using LDAP and Kerberos, a Domain Member running + Winbind can enumerate users and groups in exactly the + same way as a Windows 200x client would, and in so doing + provide a much more efficient and effective Winbind implementation. + </para> + </sect2> + + <sect2> + <title>Name Service Switch</title> + + <para>The Name Service Switch, or NSS, is a feature that is + present in many UNIX operating systems. It allows system + information such as hostnames, mail aliases and user information + to be resolved from different sources. For example, a standalone + UNIX workstation may resolve system information from a series of + flat files stored on the local filesystem. A networked workstation + may first attempt to resolve system information from local files, + and then consult an NIS database for user information or a DNS server + for hostname information.</para> + + <para>The NSS application programming interface allows Winbind + to present itself as a source of system information when + resolving UNIX usernames and groups. Winbind uses this interface, + and information obtained from a Windows NT server using MSRPC + calls to provide a new source of account enumeration. Using standard + UNIX library calls, one can enumerate the users and groups on + a UNIX machine running Winbind and see all users and groups in + a NT domain plus any trusted domain as though they were local + users and groups.</para> + + <para>The primary control file for NSS is + <filename>/etc/nsswitch.conf</filename>. + When a UNIX application makes a request to do a lookup, + the C library looks in <filename>/etc/nsswitch.conf</filename> + for a line that matches the service type being requested, for + example the <quote>passwd</quote> service type is used when user or group names + are looked up. This config line specifies which implementations + of that service should be tried and in what order. If the passwd + config line is:</para> + + <para><screen> + passwd: files example + </screen></para> + + <para>then the C library will first load a module called + <filename>/lib/libnss_files.so</filename> followed by + the module <filename>/lib/libnss_example.so</filename>. The + C library will dynamically load each of these modules in turn + and call resolver functions within the modules to try to resolve + the request. Once the request is resolved, the C library returns the + result to the application.</para> + + <para>This NSS interface provides an easy way for Winbind + to hook into the operating system. All that needs to be done + is to put <filename>libnss_winbind.so</filename> in <filename>/lib/</filename> + then add <quote>winbind</quote> into <filename>/etc/nsswitch.conf</filename> at + the appropriate place. The C library will then call Winbind to + resolve user and group names.</para> + </sect2> + + <sect2> + <title>Pluggable Authentication Modules</title> + + <para>Pluggable Authentication Modules, also known as PAM, + is a system for abstracting authentication and authorization + technologies. With a PAM module it is possible to specify different + authentication methods for different system applications without + having to recompile these applications. PAM is also useful + for implementing a particular policy for authorization. For example, + a system administrator may only allow console logins from users + stored in the local password file but only allow users resolved from + a NIS database to log in over the network.</para> + + <para>Winbind uses the authentication management and password + management PAM interface to integrate Windows NT users into a + UNIX system. This allows Windows NT users to log in to a UNIX + machine and be authenticated against a suitable Primary Domain + Controller. These users can also change their passwords and have + this change take effect directly on the Primary Domain Controller. + </para> + + <para>PAM is configured by providing control files in the directory + <filename>/etc/pam.d/</filename> for each of the services that + require authentication. When an authentication request is made + by an application, the PAM code in the C library looks up this + control file to determine what modules to load to do the + authentication check and in what order. This interface makes adding + a new authentication service for Winbind very easy. All that needs + to be done is that the <filename>pam_winbind.so</filename> module + is copied to <filename>/lib/security/</filename> and the PAM + control files for relevant services are updated to allow + authentication via Winbind. See the PAM documentation + in <link linkend="pam">PAM-Based Distributed Authentication</link> for more information.</para> + </sect2> + + + <sect2> + <title>User and Group ID Allocation</title> + + <para>When a user or group is created under Windows NT/200x + it is allocated a numerical relative identifier (RID). This is + slightly different from UNIX which has a range of numbers that are + used to identify users, and the same range in which to identify + groups. It is Winbind's job to convert RIDs to UNIX ID numbers and + vice versa. When Winbind is configured, it is given part of the UNIX + user ID space and a part of the UNIX group ID space in which to + store Windows NT users and groups. If a Windows NT user is + resolved for the first time, it is allocated the next UNIX ID from + the range. The same process applies for Windows NT groups. Over + time, Winbind will have mapped all Windows NT users and groups + to UNIX user IDs and group IDs.</para> + + <para>The results of this mapping are stored persistently in + an ID mapping database held in a tdb database). This ensures that + RIDs are mapped to UNIX IDs in a consistent way.</para> + </sect2> + + + <sect2> + <title>Result Caching</title> + + <para> +<indexterm><primary>SAM</primary></indexterm> + An active system can generate a lot of user and group + name lookups. To reduce the network cost of these lookups, Winbind + uses a caching scheme based on the SAM sequence number supplied + by NT Domain Controllers. User or group information returned + by a PDC is cached by Winbind along with a sequence number also + returned by the PDC. This sequence number is incremented by + Windows NT whenever any user or group information is modified. If + a cached entry has expired, the sequence number is requested from + the PDC and compared against the sequence number of the cached entry. + If the sequence numbers do not match, then the cached information + is discarded and up-to-date information is requested directly + from the PDC.</para> + </sect2> +</sect1> + + +<sect1> + <title>Installation and Configuration</title> + +<sect2> +<title>Introduction</title> + +<para> +This section describes the procedures used to get Winbind up and +running. Winbind is capable of providing access +and authentication control for Windows Domain users through an NT +or Windows 200x PDC for regular services, such as telnet and ftp, as +well for Samba services. +</para> + +<itemizedlist> +<listitem> + <para> + <emphasis>Why should I do this?</emphasis> + </para> + + <para>This allows the Samba administrator to rely on the + authentication mechanisms on the Windows NT/200x PDC for the authentication + of Domain Members. Windows NT/200x users no longer need to have separate + accounts on the Samba server. + </para> +</listitem> + +<listitem> + <para> + <emphasis>Who should be reading this document?</emphasis> + </para> + + <para> + This document is designed for system administrators. If you are + implementing Samba on a file server and wish to (fairly easily) + integrate existing Windows NT/200x users from your PDC onto the + Samba server, this document is for you. + </para> +</listitem> +</itemizedlist> +</sect2> + + +<sect2> +<title>Requirements</title> + +<para> +If you have a Samba configuration file that you are currently using, <emphasis>BACK IT UP!</emphasis> +If your system already uses PAM, <emphasis>back up the <filename>/etc/pam.d</filename> directory +contents!</emphasis> If you haven't already made a boot disk, <emphasis>MAKE ONE NOW!</emphasis> +</para> + +<para> +Messing with the PAM configuration files can make it nearly impossible to log in to your machine. That's +why you want to be able to boot back into your machine in single user mode and restore your +<filename>/etc/pam.d</filename> back to the original state they were in if you get frustrated with the +way things are going. +</para> + +<para> +The latest version of Samba-3 includes a functioning winbindd daemon. Please refer to the <ulink +url="http://samba.org/">main Samba Web page</ulink> or, better yet, your closest Samba mirror site for +instructions on downloading the source code. +</para> + +<para> +To allow domain users the ability to access Samba shares and files, as well as potentially other services +provided by your Samba machine, PAM must be set up properly on your +machine. In order to compile the Winbind modules, you should have at least the PAM development libraries installed +on your system. Please refer the PAM web site <ulink url="http://www.kernel.org/pub/linux/libs/pam/"/>. +</para> +</sect2> + +<sect2> +<title>Testing Things Out</title> + +<para> +Before starting, it is probably best to kill off all the Samba-related daemons running on your server. +Kill off all &smbd;, &nmbd;, and &winbindd; processes that may be running. To use PAM, +make sure that you have the standard PAM package that supplies the <filename>/etc/pam.d</filename> +directory structure, including the PAM modules that 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 is also installed. This package includes the header files +needed to compile PAM-aware applications. +</para> + +<sect3> +<title>Configure <filename>nsswitch.conf</filename> and the Winbind Libraries on Linux and Solaris</title> + +<para> +PAM is a standard component of most current generation UNIX/Linux systems. Unfortunately, few systems install +the <filename>pam-devel</filename> libraries that are needed to build PAM-enabled Samba. Additionally, Samba-3 +may auto-install the Winbind files into their correct locations on your system, so before you get too far down +the track be sure to check if the following configuration is really +necessary. You may only need to configure +<filename>/etc/nsswitch.conf</filename>. +</para> + +<para> +The libraries needed to run the &winbindd; daemon through nsswitch need to be copied to their proper locations: +</para> + +<para> +<screen> +&rootprompt;<userinput>cp ../samba/source/nsswitch/libnss_winbind.so /lib</userinput> +</screen> +</para> + +<para> +I also found it necessary to make the following symbolic link: +ZZ</para> + +<para> +&rootprompt; <userinput>ln -s /lib/libnss_winbind.so /lib/libnss_winbind.so.2</userinput> +</para> + +<para>And, in the case of Sun Solaris:</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 &winbindd; +daemon. My <filename>/etc/nsswitch.conf</filename> file look like +this after editing: +</para> + +<para><programlisting> + passwd: files winbind + shadow: files + group: files winbind +</programlisting></para> + +<para> +The libraries needed by the <command>winbindd</command> daemon will be automatically +entered into the <command>ldconfig</command> cache the next time +your system reboots, but it is faster (and you do not need to reboot) if you do it manually: +</para> + +<para> +&rootprompt;<userinput>/sbin/ldconfig -v | grep winbind</userinput> +</para> + +<para> +This makes <filename>libnss_winbind</filename> available to winbindd +and echos back a check to you. +</para> + +</sect3> + +<sect3> +<title>NSS Winbind on AIX</title> + +<para>(This section is only for those running AIX.)</para> + +<para> +The Winbind AIX identification module gets built as <filename>libnss_winbind.so</filename> in the +nsswitch directory of the Samba source. This file can be copied to <filename>/usr/lib/security</filename>, +and the AIX naming convention would indicate that it should be named WINBIND. A stanza like the following: +</para> + +<para><programlisting> +WINBIND: + program = /usr/lib/security/WINBIND + options = authonly +</programlisting></para> + +<para> +can then be added to <filename>/usr/lib/security/methods.cfg</filename>. This module only supports +identification, but there have been success reports using the standard Winbind PAM module for +authentication. Use caution configuring loadable authentication +modules since you can make +it impossible to logon to the system. More information about the AIX authentication module API can +be found at <quote>Kernel Extensions and Device Support Programming Concepts for AIX</quote><ulink +url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/kernextc/sec_load_mod.htm"> +in Chapter 18(John, there is no section like this in 18). Loadable Authentication Module Programming +Interface</ulink> and more information on administering the modules +can be found at <ulink +url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/baseadmn/iandaadmin.htm"> <quote>System +Management Guide: Operating System and Devices.</quote></ulink> +</para> +</sect3> + +<sect3> +<title>Configure smb.conf</title> + +<para> +Several parameters are needed in the &smb.conf; file to control the behavior of &winbindd;. These +are described in more detail in the <citerefentry><refentrytitle>winbindd</refentrytitle> +<manvolnum>8</manvolnum></citerefentry> man page. My &smb.conf; file, as shown in <link +linkend="winbindcfg">the next example</link>, was modified to include the necessary entries in the [global] section. +</para> + +<para> +<smbconfexample id="winbindcfg" fragment="1"> + <title>smb.conf for Winbind set-up</title> +<smbconfsection name="[global]"/> +<smbconfcomment> separate domain and username with '\', like DOMAIN\username</smbconfcomment> +<smbconfoption name="winbind separator">\</smbconfoption> +<smbconfcomment> use uids from 10000 to 20000 for domain users</smbconfcomment> +<smbconfoption name="idmap uid">10000-20000</smbconfoption> +<smbconfcomment> use gids from 10000 to 20000 for domain groups</smbconfcomment> +<smbconfoption name="idmap gid">10000-20000</smbconfoption> +<smbconfcomment> allow enumeration of winbind users and groups</smbconfcomment> +<smbconfoption name="winbind enum users">yes</smbconfoption> +<smbconfoption name="winbind enum groups">yes</smbconfoption> +<smbconfcomment> give winbind users a real shell (only needed if they have telnet access)</smbconfcomment> +<smbconfoption name="template homedir">/home/winnt/%D/%U</smbconfoption> +<smbconfoption name="template shell">/bin/bash</smbconfoption> +</smbconfexample></para> + +</sect3> + + +<sect3> +<title>Join the Samba Server to the PDC Domain</title> + +<para> +All machines that will participate in domain security should be members of +the domain. This applies also to the PDC and all BDCs. +</para> + +<para> +The process of joining a domain requires the use of the <command>net rpc join</command> +command. This process communicates with the domain controller it will register with +(usually the PDC) via MS DCE RPC. This means, of course, that the <command>smbd</command> +process must be running on the target DC. This means that it is necessary to temporarily +start Samba on a PDC so that it can join its own domain. +</para> + +<para> +Enter the following command to make the Samba server join the +domain, where <replaceable>PDC</replaceable> is the name of +your PDC and <replaceable>Administrator</replaceable> is +a domain user who has administrative privileges in the domain. +</para> + +<note><para> +Before attempting to join a machine to the domain verify that Samba is running +on the target DC (usually PDC) and that it is capable of being reached via ports +137/udp, 135/tcp, 139/tcp, and 445/tcp (if Samba or Windows Server 2Kx. +</para></note> + +<para> +&rootprompt;<userinput>/usr/local/samba/bin/net rpc join -S PDC -U Administrator</userinput> +</para> + +<para> +The proper response to the command should be: <quote>Joined the domain +<replaceable>DOMAIN</replaceable></quote> where <replaceable>DOMAIN</replaceable> +is your DOMAIN name. +</para> + +</sect3> + +<sect3> +<title>Starting and Testing the <command>winbindd</command> Daemon</title> + +<para> +Eventually, you will want to modify your Samba startup script to +automatically invoke the winbindd daemon when the other parts of +Samba start, but it is possible to test out just the Winbind +portion first. To start up Winbind services, enter the following +command as root: +</para> + +<para> +&rootprompt;<userinput>/usr/local/samba/sbin/winbindd</userinput> +</para> + +<note><para> +The above assumes that Samba has been installed in the <filename>/usr/local/samba</filename> +directory tree. You may need to search for the location of Samba files if this is not the +location of <command>winbindd</command> on your system. +</para></note> + +<para> +Winbindd can now also run in <quote>dual daemon mode</quote>. This will make it +run as two 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. +The advantage of this is that responses stay accurate and are faster. +You can enable dual daemon mode by adding <option>-B</option> to the command-line: +</para> + +<para> +&rootprompt;<userinput>/usr/local/samba/sbin/winbindd -B</userinput> +</para> + +<para> +I'm always paranoid and like to make sure the daemon is really running. +</para> + +<para> +&rootprompt;<userinput>ps -ae | grep winbindd</userinput> +</para> +<para> +This command should produce output like this, if the daemon is running you would expect +to see a report something like this: +</para> +<screen> +3025 ? 00:00:00 winbindd +</screen> + +<para> +Now, for the real test, try to get some information about the users on your PDC: +</para> + +<para> +&rootprompt;<userinput>/usr/local/samba/bin/wbinfo -u</userinput> +</para> + +<para> +This should echo back a list of users on your Windows users on +your PDC. For example, I get the following response: +</para> + +<para><screen> + CEO\Administrator + CEO\burdell + CEO\Guest + CEO\jt-ad + CEO\krbtgt + CEO\TsInternetUser +</screen></para> + +<para> +Obviously, I have named my domain <quote>CEO</quote> and my <smbconfoption name="winbind separator"/> is <quote>\</quote>. +</para> + +<para> +You can do the same sort of thing to get group information from the PDC: +</para> + +<para><screen> +&rootprompt;<userinput>/usr/local/samba/bin/wbinfo -g</userinput> + CEO\Domain Admins + CEO\Domain Users + CEO\Domain Guests + CEO\Domain Computers + CEO\Domain Controllers + CEO\Cert Publishers + CEO\Schema Admins + CEO\Enterprise Admins + CEO\Group Policy Creator Owners +</screen></para> + +<para> +The function <command>getent</command> can now be used to get unified +lists of both local and PDC users and groups. Try the following command: +</para> + +<para> +&rootprompt;<userinput>getent passwd</userinput> +</para> + +<para> +You should get a list that looks like your <filename>/etc/passwd</filename> +list followed by the domain users with their new UIDs, GIDs, home +directories and default shells. +</para> + +<para> +The same thing can be done for groups with the command: +</para> + +<para> +&rootprompt;<userinput>getent group</userinput> +</para> + +</sect3> + + +<sect3> +<title>Fix the init.d Startup Scripts</title> + +<sect4> +<title>Linux</title> + +<para> +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 Red Hat Linux and they are located in +<filename>/etc/init.d/samba</filename> in Debian Linux. Edit your +script to add commands to invoke this daemon in the proper sequence. My +startup script starts up &smbd;, &nmbd;, and &winbindd; from the +<filename>/usr/local/samba/bin</filename> directory directly. The <command>start</command> +function in the script looks like this: +</para> + +<para><programlisting> +start() { + KIND="SMB" + echo -n $"Starting $KIND services: " + daemon /usr/local/samba/bin/smbd $SMBDOPTIONS + RETVAL=$? + echo + KIND="NMB" + echo -n $"Starting $KIND services: " + daemon /usr/local/samba/bin/nmbd $NMBDOPTIONS + RETVAL2=$? + echo + KIND="Winbind" + echo -n $"Starting $KIND services: " + daemon /usr/local/samba/sbin/winbindd + RETVAL3=$? + echo + [ $RETVAL -eq 0 -a $RETVAL2 -eq 0 -a $RETVAL3 -eq 0 ] && \ + touch /var/lock/subsys/smb || RETVAL=1 + return $RETVAL +} +</programlisting></para> + +<para>If you would like to run winbindd in dual daemon mode, replace +the line : +<programlisting> + daemon /usr/local/samba/sbin/winbindd +</programlisting> + +in the example above with: + +<programlisting> + daemon /usr/local/samba/sbin/winbindd -B +</programlisting>. +</para> + +<para> +The <command>stop</command> function has a corresponding entry to shut down the +services and looks like this: +</para> + +<para><programlisting> +stop() { + KIND="SMB" + echo -n $"Shutting down $KIND services: " + killproc smbd + RETVAL=$? + echo + KIND="NMB" + echo -n $"Shutting down $KIND services: " + killproc nmbd + RETVAL2=$? + echo + KIND="Winbind" + echo -n $"Shutting down $KIND services: " + killproc winbindd + RETVAL3=$? + [ $RETVAL -eq 0 -a $RETVAL2 -eq 0 -a $RETVAL3 -eq 0 ] && \ + rm -f /var/lock/subsys/smb + echo "" + return $RETVAL +} +</programlisting></para> +</sect4> + +<sect4> +<title>Solaris</title> + +<para> +Winbind does not work on Solaris 9, see <link linkend="winbind-solaris9">Winbind on Solaris 9</link> section for details. +</para> + +<para> +On Solaris, you need to modify the <filename>/etc/init.d/samba.server</filename> startup script. It +usually only starts smbd and nmbd but should now start winbindd, too. If you have Samba installed in +<filename>/usr/local/samba/bin</filename>, the file could contains something like this: +</para> + +<para> + <smbfile name="samba.server.sh"> + <programlisting> + ## + ## samba.server + ## + + if [ ! -d /usr/bin ] + then # /usr not mounted + exit + fi + + killproc() { # kill the named process(es) + pid=`/usr/bin/ps -e | + /usr/bin/grep -w $1 | + /usr/bin/sed -e 's/^ *//' -e 's/ .*//'` + [ "$pid" != "" ] && kill $pid + } + + # Start/stop processes required for Samba server + + case "$1" in + + 'start') + # + # Edit these lines to suit your installation (paths, workgroup, host) + # + echo Starting SMBD + /usr/local/samba/bin/smbd -D -s \ + /usr/local/samba/smb.conf + + echo Starting NMBD + /usr/local/samba/bin/nmbd -D -l \ + /usr/local/samba/var/log -s /usr/local/samba/smb.conf + + echo Starting Winbind Daemon + /usr/local/samba/sbin/winbindd + ;; + + 'stop') + killproc nmbd + killproc smbd + killproc winbindd + ;; + + *) + echo "Usage: /etc/init.d/samba.server { start | stop }" + ;; + esac +</programlisting></smbfile></para> + +<para> +Again, if you would like to run Samba in dual daemon mode, replace: +<programlisting> + /usr/local/samba/sbin/winbindd +</programlisting> +in the script above with: +<programlisting> + /usr/local/samba/sbin/winbindd -B +</programlisting> +</para> + +</sect4> + +<sect4> +<title>Restarting</title> +<para> +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> +</sect4> +</sect3> + +<sect3> +<title>Configure Winbind and PAM</title> + +<para> +If you have made it this far, you know that <command>winbindd</command> and Samba are working +together. If you want to use Winbind to provide authentication for other +services, keep reading. The PAM configuration files need to be altered in +this step. (Did you remember to make backups of your original +<filename>/etc/pam.d</filename> files? If not, do it now.) +</para> + +<para> +You will need a PAM module to use winbindd with these other services. This +module will be compiled in the <filename>../source/nsswitch</filename> directory +by invoking the command: +</para> + +<para> +&rootprompt;<userinput>make nsswitch/pam_winbind.so</userinput> +</para> + +<para> +from the <filename>../source</filename> directory. The +<filename>pam_winbind.so</filename> file should be copied to the location of +your other PAM security modules. On my Red Hat system, this was the +<filename>/lib/security</filename> directory. On Solaris, the PAM security +modules reside in <filename>/usr/lib/security</filename>. +</para> + +<para> +&rootprompt;<userinput>cp ../samba/source/nsswitch/pam_winbind.so /lib/security</userinput> +</para> + +<sect4> +<title>Linux/FreeBSD-specific PAM configuration</title> + +<para> +The <filename>/etc/pam.d/samba</filename> file does not need to be changed. I +just left this file as it was: +</para> + + +<para><programlisting> + auth required /lib/security/pam_stack.so service=system-auth + account required /lib/security/pam_stack.so service=system-auth +</programlisting></para> + +<para> +The other services that I modified to allow the use of Winbind +as an authentication service were the normal login on the console (or a terminal +session), telnet logins, and ftp service. In order to enable these +services, you may first need to change the entries in +<filename>/etc/xinetd.d</filename> (or <filename>/etc/inetd.conf</filename>). +Red Hat Linux 7.1 and later uses the new xinetd.d structure, in this case you need +to change the lines in <filename>/etc/xinetd.d/telnet</filename> +and <filename>/etc/xinetd.d/wu-ftp</filename> from +</para> + +<para><programlisting> + enable = no +</programlisting> +to: +<programlisting> + enable = yes +</programlisting></para> + +<para> +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 &smb.conf; global entry +<smbconfoption name="template homedir"/>. +</para> + +<note> + <para>The directory in <smbconfoption name="template homedir"/> is not created automatically! Use pam_mkhomedir or pre-create + the directories of users to make sure users can log in on UNIX with + their own home directory. + </para> +</note> + +<para> +The <filename>/etc/pam.d/ftp</filename> file can be changed +to allow Winbind ftp access in a manner similar to the +samba file. My <filename>/etc/pam.d/ftp</filename> file was +changed to look like this: +</para> + +<para><smbfile name="pam.ftp.winbind"><programlisting> +auth required /lib/security/pam_listfile.so item=user sense=deny \ + file=/etc/ftpusers onerr=succeed +auth sufficient /lib/security/pam_winbind.so +auth required /lib/security/pam_stack.so service=system-auth +auth required /lib/security/pam_shells.so +account sufficient /lib/security/pam_winbind.so +account required /lib/security/pam_stack.so service=system-auth +session required /lib/security/pam_stack.so service=system-auth +</programlisting></smbfile></para> + +<para> +The <filename>/etc/pam.d/login</filename> file can be changed nearly the +same way. It now looks like this: +</para> + +<para><smbfile name="pam.login.winbind"><programlisting> +auth required /lib/security/pam_securetty.so +auth sufficient /lib/security/pam_winbind.so +auth sufficient /lib/security/pam_unix.so use_first_pass +auth required /lib/security/pam_stack.so service=system-auth +auth required /lib/security/pam_nologin.so +account sufficient /lib/security/pam_winbind.so +account required /lib/security/pam_stack.so service=system-auth +password required /lib/security/pam_stack.so service=system-auth +session required /lib/security/pam_stack.so service=system-auth +session optional /lib/security/pam_console.so +</programlisting></smbfile></para> + +<para> +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 +<programlisting>sufficient /lib/security/pam_unix.so use_first_pass</programlisting> +line after the <command>winbind.so</command> line to get rid of annoying +double prompts for passwords. +</para> + +</sect4> + +<sect4> +<title>Solaris-specific configuration</title> + +<para> +The <filename>/etc/pam.conf</filename> needs to be changed. I changed this file so my Domain +users can logon both locally as well as telnet. The following are the changes +that I made. You can customize the <filename>pam.conf</filename> file as per your requirements, but +be sure of those changes because in the worst case it will leave your system +nearly impossible to boot. +</para> + +<para><programlisting> +# +#ident "@(#)pam.conf 1.14 99/09/16 SMI" +# +# Copyright (c) 1996-1999, Sun Microsystems, Inc. +# All Rights Reserved. +# +# PAM configuration +# +# Authentication management +# +login auth required /usr/lib/security/pam_winbind.so +login auth required /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass +login auth required /usr/lib/security/$ISA/pam_dial_auth.so.1 try_first_pass +# +rlogin auth sufficient /usr/lib/security/pam_winbind.so +rlogin auth sufficient /usr/lib/security/$ISA/pam_rhosts_auth.so.1 +rlogin auth required /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass +# +dtlogin auth sufficient /usr/lib/security/pam_winbind.so +dtlogin auth required /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass +# +rsh auth required /usr/lib/security/$ISA/pam_rhosts_auth.so.1 +other auth sufficient /usr/lib/security/pam_winbind.so +other auth required /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass +# +# Account management +# +login account sufficient /usr/lib/security/pam_winbind.so +login account requisite /usr/lib/security/$ISA/pam_roles.so.1 +login account required /usr/lib/security/$ISA/pam_unix.so.1 +# +dtlogin account sufficient /usr/lib/security/pam_winbind.so +dtlogin account requisite /usr/lib/security/$ISA/pam_roles.so.1 +dtlogin account required /usr/lib/security/$ISA/pam_unix.so.1 +# +other account sufficient /usr/lib/security/pam_winbind.so +other account requisite /usr/lib/security/$ISA/pam_roles.so.1 +other account required /usr/lib/security/$ISA/pam_unix.so.1 +# +# Session management +# +other session required /usr/lib/security/$ISA/pam_unix.so.1 +# +# Password management +# +#other password sufficient /usr/lib/security/pam_winbind.so +other password required /usr/lib/security/$ISA/pam_unix.so.1 +dtsession auth required /usr/lib/security/$ISA/pam_unix.so.1 +# +# Support for Kerberos V5 authentication (uncomment to use Kerberos) +# +#rlogin auth optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass +#login auth optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass +#dtlogin auth optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass +#other auth optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass +#dtlogin account optional /usr/lib/security/$ISA/pam_krb5.so.1 +#other account optional /usr/lib/security/$ISA/pam_krb5.so.1 +#other session optional /usr/lib/security/$ISA/pam_krb5.so.1 +#other password optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass +</programlisting></para> + +<para> +I also added a <parameter>try_first_pass</parameter> line after the <filename>winbind.so</filename> +line to get rid of annoying double prompts for passwords. +</para> + +<para> +Now restart your Samba and try connecting through your application that you +configured in the pam.conf. +</para> + +</sect4> + +</sect3> + +</sect2> + +</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> + +<sect1> +<title>Common Errors</title> + + <para>Winbind has a number of limitations in its current + released version that we hope to overcome in future + releases:</para> + + <itemizedlist> + <listitem><para>Winbind is currently only available for + the Linux, Solaris, AIX, and IRIX operating systems, although ports to other operating + systems are certainly possible. For such ports to be feasible, + we require the C library of the target operating system to + support the Name Service Switch and Pluggable Authentication + Modules systems. This is becoming more common as NSS and + PAM gain support among UNIX vendors.</para></listitem> + + <listitem><para>The mappings of Windows NT RIDs to UNIX IDs + is not made algorithmically and depends on the order in which + unmapped users or groups are seen by Winbind. It may be difficult + to recover the mappings of RID to UNIX ID mapping if the file + containing this information is corrupted or destroyed.</para> + </listitem> + + <listitem><para>Currently the Winbind PAM module does not take + into account possible workstation and logon time restrictions + that may be set for Windows NT users, this is + instead up to the PDC to enforce.</para></listitem> + </itemizedlist> + + <sect2> + <title>NSCD Problem Warning</title> + + <?latex \nopagebreak ?> + + <warning><para> + Do not under any circumstances run <command>nscd</command> on any system + on which <command>winbindd</command> is running. + </para></warning> + + <para> + If <command>nscd</command> is running on the UNIX/Linux system, then + even though NSSWITCH is correctly configured it will not be possible to resolve + domain users and groups for file and directory controls. + </para> + + </sect2> + + <sect2> + <title>Winbind Is Not Resolving Users and Groups</title> + + <para><quote> + My &smb.conf; file is correctly configured. I have specified + <smbconfoption name="idmap uid">12000</smbconfoption>, + and <smbconfoption name="idmap gid">3000-3500</smbconfoption> + and <command>winbind</command> is running. When I do the following it all works fine. + </quote></para> + +<para><screen> +&rootprompt;<userinput>wbinfo -u</userinput> +MIDEARTH\maryo +MIDEARTH\jackb +MIDEARTH\ameds +... +MIDEARTH\root + +&rootprompt;<userinput>wbinfo -g</userinput> +MIDEARTH\Domain Users +MIDEARTH\Domain Admins +MIDEARTH\Domain Guests +... +MIDEARTH\Accounts + +&rootprompt;<userinput>getent passwd</userinput> +root:x:0:0:root:/root:/bin/bash +bin:x:1:1:bin:/bin:/bin/bash +... +maryo:x:15000:15003:Mary Orville:/home/MIDEARTH/maryo:/bin/false +</screen></para> + +<para><quote> +But the following command just fails: +</quote> +<screen> +&rootprompt;<userinput>chown maryo a_file</userinput> +chown: `maryo': invalid user +</screen> +<quote> +This is driving me nuts! What can be wrong? +</quote></para> + +<para> +Same problem as the one above. +Your system is likely running <command>nscd</command>, the name service +caching daemon. Shut it down, do not restart it! You will find your problem resolved. +</para> + +</sect2> +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml b/docs/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml new file mode 100644 index 0000000000..be080638f6 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml @@ -0,0 +1,472 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="ClientConfig"> +<chapterinfo> + &author.jht; +</chapterinfo> + +<title>MS Windows Network Configuration Guide</title> + +<sect1> +<title>Features and Benefits</title> + +<para> +Occasionally network administrators will report difficulty getting Microsoft Windows clients to interoperate +correctly with Samba servers. It would appear that some folks just can not accept the fact that the right way +to configure MS Windows network client is precisely as one would do when using Microsoft Windows NT4 or 200x +servers. Yet there is repetitious need to provide detailed Windows client configuration instructions. +</para> + +<para> +The purpose of this chapter is to graphically illustrate MS Windows client configuration for the most common +critical aspects of such configuration. An experienced network administrator will not be interested in the +details of this chapter. +</para> + +</sect1> + +<sect1> +<title>Technical Details</title> + +<para> +This chapter discusses TCP/IP protocol configuration as well as network membership for the platforms +that are in common use today. These are: +</para> + +<itemizedlist> + <listitem><para> + Microsoft Windows XP Professional. + </para></listitem> + <listitem><para> + Windows 2000 Professional. + </para></listitem> + <listitem><para> + Windows Millennium edition (Me). + </para></listitem> +</itemizedlist> + + <sect2> + <title>TCP/IP Configuration</title> + + <para> + The builder of a house must ensure that all construction takes place on a firm foundation. + The same is true of TCP/IP-based networking. Fundamental network configuration problems + will plague all network users until they are resolved. + </para> + + <para> + Microsoft Windows workstations and servers can be configured either with fixed + IP addresses or via DHCP. The examples that follow demonstrate the use of DHCP + and make only passing reference to those situations where fixed IP configuration + settings can be effected. + </para> + + <para> + It is possible to use shortcuts or abbreviated keystrokes to arrive at a + particular configuration screen. The decision was made to base all examples in this + chapter on use of the <guibutton>Start</guibutton> button. + </para> + + <sect3> + <title>MS Windows XP Professional</title> + + <para> + There are two paths to the Windows XP TCP/IP configuration panel. Choose the access method that you prefer: + </para> + + <para> + Click <guimenu>Start -> Control Panel -> Network Connections</guimenu> + </para> + + <para> + <emphasis>Alternately,</emphasis> click <guimenu>Start -></guimenu>, and right click <guimenu>My Network Places</guimenu> + then select <guimenuitem>Properties</guimenuitem> + </para> + + <para> + The following procedure steps through the Windows XP Professional TCP/IP configuration process: + </para> + + <procedure> + <step><para> + On some installations the interface will be called <guimenu>Local Area Connection</guimenu> and + on others it will be called <guimenu>Network Bridge</guimenu>. On our system it is called <guimenu>Network Bridge</guimenu>. + Right click on <guimenu>Network Bridge -> Properties</guimenu>. See <link linkend="WXPP002"/>. + <image id="WXPP002"><imagedescription>Network Bridge Configuration.</imagedescription><imagefile>WXPP002</imagefile></image> + </para> + </step> + + <step><para> + The Network Bridge Configuration, or Local Area Connection, panel is used to set TCP/IP protocol settings. + In <guimenuitem>This connection uses the following items:</guimenuitem> box, + click on <guimenu>Internet Protocol (TCP/IP)</guimenu>, then click the on <guibutton>Properties</guibutton>. + </para> + + <para> + The default setting is DHCP enabled operation. + (i.e., <quote>Obtain an IP address automatically</quote>). See <link linkend="WXPP003"/>. + <image id="WXPP003"> + <imagedescription>Internet Protocol (TCP/IP) Properties.</imagedescription> + <imagefile>WXPP003</imagefile> + </image> + </para> + + <para> + Many network administrators will want to use DHCP to configure all client TCP/IP + protocol stack settings. (For information on how to configure the ISC DHCP server + for Microsoft Windows client support see, <link linkend="DHCP"></link>. + </para> + + <para> + If it is necessary to provide a fixed IP address, click on <quote>Use the following IP address</quote> and proceed to enter the + IP Address, the subnet mask, and the default gateway address in the boxes provided. + </para></step> + + <step><para> + Click the <guibutton>Advanced</guibutton> button to proceed with TCP/IP configuration. + This opens a panel in which it is possible to create additional IP Addresses for this interface. + The technical name for the additional addresses is <emphasis>IP Aliases</emphasis>, and additionally this + panel permits the setting of more default gateways (routers). In most cases where DHCP is used, it will not be + necessary to create additional settings. See <link linkend="WXPP005"></link> to see the appearance of this panel. + <image id="WXPP005"><imagedescription>Advanced Network Settings</imagedescription><imagefile>WXPP005</imagefile></image> + </para> + + <para> + Fixed settings may be required for DNS and WINS if these settings are not provided automatically via DHCP. + </para></step> + + <step><para> + Click the <guimenu>DNS</guimenu> tab to add DNS server settings. + The example system uses manually configured DNS settings. When finished making changes, click the <guibutton>OK</guibutton> to commit + the settings. See <link linkend="WXPP014"/>. + <image id="WXPP014"><imagedescription>DNS Configuration.</imagedescription><imagefile>WXPP014</imagefile></image> + </para></step> + + <step><para> + Click the <guibutton>WINS</guibutton> tab to add manual WINS server entries. + This step demonstrates an example system that uses manually configured WINS settings. + When finished making, changes click the <guibutton>OK</guibutton> to commit + the settings. See <link linkend="WXPP009"></link>. + <image id="WXPP009"><imagedescription>WINS Configuration</imagedescription><imagefile>WXPP009</imagefile></image> + </para></step> + </procedure> + + </sect3> + + <sect3> + <title>MS Windows 2000</title> + + <para> + There are two paths to the Windows 2000 Professional TCP/IP configuration panel. Choose the access method that you prefer: + </para> + + <para> + Click <guimenu>Start -> Control Panel -> Network and Dial-up Connections</guimenu> + </para> + + <para> + <emphasis>Alternately,</emphasis> click on <guimenu>Start</guimenu>, then right click <guimenu>My Network Places</guimenu> and + select <guimenuitem>Properties</guimenuitem>. + </para> + + <para> + The following procedure steps through the Windows XP Professional TCP/IP configuration process: + </para> + + <procedure> + <step><para> + Right click on <guimenu>Local Area Connection</guimenu>, now click the + <guimenuitem>Properties</guimenuitem>. See <link linkend="w2kp001"></link>. + <image id="w2kp001"><imagedescription>Local Area Connection Properties.</imagedescription><imagefile>w2kp001</imagefile></image> + </para></step> + + <step><para> + The Local Area Connection Properties is used to set TCP/IP protocol settings. Click on <guimenu>Internet Protocol (TCP/IP)</guimenu> in the + <guimenuitem>Components checked are used by this connection:</guimenuitem> box, then click the <guibutton>Properties</guibutton> button. + </para></step> + + <step><para> + The default setting is DHCP enabled operation. + (i.e., <quote>Obtain an IP address automatically</quote>). See <link linkend="w2kp002"/>. + <image id="w2kp002"><imagedescription>Internet Protocol (TCP/IP) Properties.</imagedescription><imagefile>w2kp002</imagefile></image> + </para> + + <para> + Many network administrators will want to use DHCP to configure all client TCP/IP + protocol stack settings. (For information on how to configure the ISC DHCP server + for Microsoft Windows client support, see <link linkend="DHCP"></link>. + </para> + + <para> + If it is necessary to provide a fixed IP address, click on <quote>Use the following IP address</quote> and proceed to enter the + IP Address, the subnet mask, and the default gateway address in the boxes provided. + For this example we are assuming that all network clients will be configured using DHCP. + </para></step> + + <step><para> + Click the <guimenu>Advanced</guimenu> button to proceed with TCP/IP configuration. + Refer to <link linkend="w2kp003"></link>. + <image id="w2kp003"><imagedescription>Advanced Network Settings.</imagedescription><imagefile>w2kp003</imagefile></image> + </para> + + <para> + Fixed settings may be required for DNS and WINS if these settings are not provided automatically via DHCP. + </para></step> + + <step><para> + Click the <guimenu>DNS</guimenu> tab to add DNS server settings. + The example system uses manually configured DNS settings. When finished making changes, + click on <guibutton>OK</guibutton> to commit the settings. See <link linkend="w2kp004"></link>. + <image id="w2kp004"><imagedescription>DNS Configuration.</imagedescription><imagefile>w2kp004</imagefile></image> + </para></step> + + <step><para> + Click the <guibutton>WINS</guibutton> tab to add manual WINS server entries. + This step demonstrates an example system that uses manually configured WINS settings. + When finished making changes, click on <guibutton>OK</guibutton> to commit the settings. + See <link linkend="w2kp005"></link>. + <image id="w2kp005"><imagedescription>WINS Configuration.</imagedescription><imagefile>w2kp005</imagefile></image> + </para></step> + + </procedure> + + </sect3> + + <sect3> + <title>MS Windows Me</title> + + <para> + There are two paths to the Windows Millennium edition (Me) TCP/IP configuration panel. Choose the access method that you prefer: + </para> + + <para> + Click <guimenu>Start -> Control Panel -> Network Connections</guimenu> + </para> + + <para> + <emphasis>Alternately,</emphasis> click on <guimenu>Start -></guimenu>, and right click on <guimenu>My Network Places</guimenu> + then select <guimenuitem>Properties</guimenuitem>. + </para> + + <para> + The following procedure steps through the Windows Me TCP/IP configuration process: + </para> + + <procedure> + <step><para> + In the box labeled <guimenuitem>The following network components are installed:</guimenuitem>, + click on <guimenu>Internet Protocol TCP/IP</guimenu>, now click on the <guibutton>Properties</guibutton> button. See <link linkend="WME001"></link>. + <image id="WME001"><imagedescription>The Windows Me Network Configuration Panel.</imagedescription><imagefile>WME001</imagefile></image> + </para></step> + + <step><para> + Many network administrators will want to use DHCP to configure all client TCP/IP + protocol stack settings. (For information on how to configure the ISC DHCP server + for Microsoft Windows client support see, <link linkend="DHCP"></link>. + The default setting on Microsoft Windows Me workstations is for DHCP enabled operation, + i.e., <guimenu>Obtain IP address automatically</guimenu> is enabled. See <link linkend="WME002"></link>. + <image id="WME002"><imagedescription>IP Address.</imagedescription><imagefile>WME002</imagefile></image> + </para> + + <para> + If it is necessary to provide a fixed IP address, click on <guimenuitem>Specify an IP address</guimenuitem> and proceed to enter the + IP Address and the subnet mask in the boxes provided. For this example we are assuming that all network clients will be configured using DHCP. + </para></step> + + <step><para> + Fixed settings may be required for DNS and WINS if these settings are not provided automatically via DHCP. + </para></step> + + <step><para> + If necessary, click the <guimenu>DNS Configuration</guimenu> tab to add DNS server settings. + Click the <guibutton>WINS Configuration</guibutton> tab to add WINS server settings. + The <guimenu>Gateway</guimenu> tab allows additional gateways (router addresses) to be added to the network + interface settings. In most cases where DHCP is used, it will not be necessary to + create these manual settings. + </para></step> + + <step><para> + The following example uses manually configured WINS settings. See <link linkend="WME005"></link>. + When finished making changes, click on <guibutton>OK</guibutton> to commit the settings. + <image id="WME005"><imagedescription>DNS Configuration.</imagedescription><imagefile>WME005</imagefile></image> + </para> + + <para> + This is an example of a system that uses manually configured WINS settings. One situation where + this might apply is on a network that has a single DHCP server that provides settings for multiple + Windows workgroups or domains. See <link linkend="WME003"></link>. + <image id="WME003"><imagedescription>WINS Configuration.</imagedescription><imagefile>WME003</imagefile></image> + </para></step> + </procedure> + + + </sect3> + + </sect2> + + <sect2> + <title>Joining a Domain: Windows 2000/XP Professional</title> + + <para> + Microsoft Windows NT/200x/XP Professional platforms can participate in Domain Security. + This section steps through the process for making a Windows 200x/XP Professional machine a + member of a Domain Security environment. It should be noted that this process is identical + when joining a domain that is controlled by Windows NT4/200x as well as a Samba PDC. + </para> + + <procedure> + <step><para> + Click <guimenu>Start</guimenu>. + </para></step> + + <step><para> + Right click <guimenu>My Computer</guimenu>, then select <guimenuitem>Properties</guimenuitem>. + </para></step> + + <step><para> + The opening panel is the same one that can be reached by clicking <guimenu>System</guimenu> on the Control Panel. + See <link linkend="wxpp001"></link>. + <image id="wxpp001"><imagedescription>The General Panel.</imagedescription><imagefile>wxpp001</imagefile></image> + </para></step> + + <step><para> + Click the <guimenu>Computer Name</guimenu> tab. + This panel shows the <guimenuitem>Computer Description</guimenuitem>, the <guimenuitem>Full computer name</guimenuitem>, + and the <guimenuitem>Workgroup</guimenuitem> or <guimenuitem>Domain name</guimenuitem>. + </para> + + <para> + Clicking the <guimenu>Network ID</guimenu> button will launch the configuration wizard. Do not use this with + Samba-3. If you wish to change the computer name, join or leave the domain, click the <guimenu>Change</guimenu> button. + See <link linkend="wxpp004"></link>. + <image id="wxpp004"><imagedescription>The Computer Name Panel.</imagedescription><imagefile>wxpp004</imagefile></image> + </para></step> + + <step><para> + Click on <guimenu>Change</guimenu>. This panel shows that our example machine (TEMPTATION) is in a workgroup called WORKGROUP. + We will join the domain called MIDEARTH. See <link linkend="wxpp006"></link>. + <image id="wxpp006"><imagedescription>The Computer Name Changes Panel.</imagedescription><imagefile>wxpp006</imagefile></image> + </para></step> + + <step><para> + Enter the name <guimenu>MIDEARTH</guimenu> in the field below the Domain radio button. + </para> + + <para> + This panel shows that our example machine (TEMPTATION) is set to join the domain called MIDEARTH. See <link linkend="wxpp007"></link>. + <image id="wxpp007"><imagedescription>The Computer Name Changes Panel &smbmdash; Domain MIDEARTH.</imagedescription><imagefile>wxpp007</imagefile></image> + </para></step> + + <step><para> + Now click the <guimenu>OK</guimenu> button. A dialog box should appear to allow you to provide the credentials (username and password) + of a Domain administrative account that has the rights to add machines to the Domain. + </para> + + <para> + Enter the name <quote>root</quote> and the root password from your Samba-3 server. See <link linkend="wxpp008"></link>. + <image id="wxpp008"><imagedescription>Computer Name Changes &smbmdash; User name and Password Panel.</imagedescription><imagefile>wxpp008</imagefile></image> + </para></step> + + <step><para> + Click on <guimenu>OK</guimenu>. + </para> + + <para> + The <quote>Welcome to the MIDEARTH domain.</quote> dialog box should appear. At this point the machine must be rebooted. + Joining the domain is now complete. + </para></step> + + </procedure> + + </sect2> + + <sect2> + <title>Domain Logon Configuration: Windows 9x/Me</title> + + <para> + We follow the convention used by most in saying that Windows 9x/Me machines can participate in Domain logons. The truth is + that these platforms can use only the LanManager network logon protocols. + </para> + + <note><para> + Windows XP Home edition cannot participate in Domain or LanManager network logons. + </para></note> + + <procedure> + <step><para> + Right click on the <guimenu>Network Neighborhood</guimenu> icon. + </para></step> + + <step><para> + The Network Configuration Panel allows all common network settings to be changed. + See <link linkend="WME009"></link>. + <image id="WME009"><imagedescription>The Network Panel.</imagedescription><imagefile>WME009</imagefile></image> + </para> + + <para> + Make sure that the <guimenu>Client for Microsoft Networks</guimenu> driver is installed as shown. + Click on the <guimenu>Client for Microsoft Networks</guimenu> entry in <guimenu>The following network + components are installed:</guimenu> box. Then click the <guibutton>Properties</guibutton> button. + </para></step> + + <step><para> + The Client for Microsoft Networks Properties panel is the correct location to configure network logon + settings. See <link linkend="WME010"></link>. + <image id="WME010"><imagedescription>Client for Microsoft Networks Properties Panel.</imagedescription><imagefile>WME010</imagefile></image> + </para> + + <para> + Enter the Windows NT domain name, check the <guimenu>Log on to Windows NT domain</guimenu> box, + click <guimenu>OK</guimenu>. + </para></step> + + <step><para> + Click on the <guimenu>Identification</guimenu> button. This is the location at which the workgroup + (domain) name and the machine name (computer name) need to be set. See <link linkend="WME013"></link>. + <image id="WME013"><imagedescription>Identification Panel.</imagedescription><imagefile>WME013</imagefile></image> + </para></step> + + <step><para> + Now click the <guimenu>Access Control</guimenu> button. If you want to be able to assign share access + permissions using domain user and group accounts, it is necessary to enable + <guimenu>User-level access control</guimenu> as shown in this panel. See <link linkend="WME014"></link>. + <image id="WME014"><imagedescription>Identification Panel.</imagedescription><imagefile>WME014</imagefile></image> + </para></step> + + </procedure> + + </sect2> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +The most common errors that can afflict Windows networking systems include: +</para> + +<itemizedlist> + <listitem><para>Incorrect IP address.</para></listitem> + <listitem><para>Incorrect or inconsistent netmasks.</para></listitem> + <listitem><para>Incorrect router address.</para></listitem> + <listitem><para>Incorrect DNS server address.</para></listitem> + <listitem><para>Incorrect WINS server address.</para></listitem> + <listitem><para>Use of a Network Scope setting &smbmdash; watch out for this one!</para></listitem> +</itemizedlist> + +<para> +The most common reasons for which a Windows NT/200x/XP Professional client cannot join the Samba controlled domain are: +</para> + +<itemizedlist> + <listitem><para>&smb.conf; does not have correct <smbconfoption name="add machine script"/> settings.</para></listitem> + <listitem><para><quote>root</quote> account is not in password backend database.</para></listitem> + <listitem><para>Attempt to use a user account instead of the <quote>root</quote> account to join a machine to the domain.</para></listitem> + <listitem><para>Open connections from the workstation to the server.</para></listitem> + <listitem><para>Firewall or filter configurations in place on either the client or on the Samba server.</para></listitem> +</itemizedlist> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-foreword-tridge.xml b/docs/Samba3-HOWTO/TOSHARG-foreword-tridge.xml new file mode 100644 index 0000000000..34bc37314d --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-foreword-tridge.xml @@ -0,0 +1,48 @@ +<?xml version='1.0'?> +<!DOCTYPE preface PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<preface> +<title>Foreword</title> + +<para> +Over the last few years, the Samba project has undergone a major +transformation. From a small project used only by people who dream in +machine code, Samba has grown to be an integral part of the IT +infrastructure of many businesses. Along with the growth in the +popularity of Samba there has been a corresponding growth in the ways +that it can be used, and a similar growth in the number of +configuration options and the interactions between them. +</para> + +<para> +To address this increasing complexity a wealth of documentation has +been written on Samba, including numerous HOWTOs, diagnostic tips, +manual pages, and explanations of important pieces of technology that +Samba relies on. While it has been gratifying to see so much +documentation being written, the sheer volume of different types of +documentation has proved difficult to navigate, thus reducing its +value to system administrators trying to cope with the complexity. +</para> + +<para> +This book gathers together that wealth of information into a much more +accessible form, to allow system administrators to quickly find what +they need. The breadth of technical information provided ensures that +even the most demanding administrators will find something helpful. +</para> + +<para> +I am delighted that the Samba documentation has now developed to the +extent that it can be presented usefully as a book, and I am grateful +for the efforts of the many people who have contributed so much +toward this result. Enjoy! +</para> + +<para> +<simplelist> + <member>Andrew Tridgell</member> + <member><emphasis>President, Samba Team</emphasis></member> + <member><emphasis>July 2003</emphasis></member> +</simplelist> +</para> + +</preface> diff --git a/docs/Samba3-HOWTO/TOSHARG-glossary.xml b/docs/Samba3-HOWTO/TOSHARG-glossary.xml new file mode 100644 index 0000000000..c83ba05675 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-glossary.xml @@ -0,0 +1,236 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE glossary PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<glossary> + <title>Glossary</title> + + <glossentry> + <glossterm>Access Control List</glossterm> + <acronym>ACL</acronym> + <glossdef><para> + A detailed list of permissions granted to users or groups with respect to file and network resource access. + See <link linkend="AccessControls"/>, + for details.</para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Active Directory Service</glossterm> + <acronym>ADS</acronym> + <glossdef><para> + A service unique to Microsoft Windows 200x servers that provides a centrally managed + directory for management of user identities, and computer objects, as well as the permissions + each user or computer may be granted to access + distributed network resources. ADS uses Kerberos-based + authentication and LDAP over Kerberos for directory access. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Common Internet File System</glossterm> + <acronym>CIFS</acronym> + <glossdef><para>The new name for SMB. Microsoft renamed the + SMB protocol to CIFS during the Internet hype in the nineties. + At about the time that the SMB protocol was renamed to CIFS, an + additional dialect of the SMB protocol was in development. + The need for the deployment of the NetBIOS layer was also + removed, thus paving the way for use of the SMB protocol natively + over TCP/IP (known as NetBIOS-less SMB or <quote>naked</quote> TCP transport). + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Common UNIX Printing System</glossterm> + <acronym>CUPS</acronym> + <glossdef><para> + A recent implementation of a high capability printing system for UNIX developed by + <ulink url="http://www.easysw.com/">.</ulink> The design objective of CUPS was to provide + a rich print processing system that has built-in intelligence that is capable of correctly rendering (processing) + a file that is submitted for printing even if it was formatted for an entirely different printer. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Domain Master Browser</glossterm> + <acronym>DMB</acronym> + <glossdef><para>The Domain Master Browser maintains a list of all the servers that + have announced their services within a given workgroup or NT domain. See <link linkend="DMB"/> for details. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Domain Name Service</glossterm> + <acronym>DNS</acronym> + <glossdef><para> + A protocol by which computer host names may be resolved to the matching IP address/es. DNS is implemented + by the Berkeley Internet Name Daemon. There exists a recent version of DNS that allows dynamic name registration + by network clients or by a DHCP server. This recent protocol is known as Dynamic DNS (DDNS). + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Dynamic Host Configuration Protocol</glossterm> + <acronym>DHCP</acronym> + <glossdef><para> + A protocol that was based on the BOOTP protocol that may be used to dynamically assign an IP address, + from a reserved pool of addresses, to a network client or device. Additionally, DHCP may assign all + network configuration settings and may be used to register a computer name and its address with a + Dynamic DNS server. + </para></glossdef> + </glossentry> + <glossentry> + <glossterm>Extended Meta-file Format</glossterm> + <acronym>EMF</acronym> + <glossdef> + <para> + An intermediate file format used by Microsoft <?latex \linebreak ?>Windows-based servers and clients. EMF files may be + rendered into a page description language by a print processor. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Graphical Device Interface</glossterm> + <acronym>GDI</acronym> + <glossdef><para> + Device Independent format for printing used by Microsoft Windows. + It is quite similar to what PostScript is for UNIX. Printing jobs are first generated in GDI and + then converted to a device-specific format. See <link linkend="gdipost"/> for details. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Group IDentifier</glossterm> + <acronym>GID</acronym> + <glossdef><para> + The UNIX system Group Identifier; on older systems a 32-bit unsigned integer and on newer systems + an unsigned 64-bit integer. The GID is used in UNIX-like operating systems for all group level access + control. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Internet Print Protocol</glossterm> + <acronym>IPP</acronym> + <glossdef><para>An IETF standard for network printing. CUPS + implements IPP.</para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Key Distribution Center</glossterm> + <acronym>KDC</acronym> + <glossdef><para>The Kerberos authentication protocol makes use of security keys (also called a ticket) + by which access to network resources is controlled. The issuing of Kerberos tickets is effected by + a KDC.</para></glossdef> + </glossentry> + + <glossentry> + <glossterm>NetBIOS Extended User Interface</glossterm> + <acronym>NetBEUI</acronym> + <glossdef><para> + Very simple network protocol invented by IBM and Microsoft. It is used + to do NetBIOS over ethernet with low overhead. NetBEUI is a non-routable + protocol. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Network Basic Input/Output System</glossterm> + <acronym>NetBIOS</acronym> + <glossdef><para> + NetBIOS is a simple application programming interface (API) invented in the eighties + that allows programs to send data to certain network names. + NetBIOS is always run over another network protocol such + as IPX/SPX, TCP/IP, or Logical Link Control (LLC). NetBIOS run over LLC + is best known as NetBEUI (The NetBIOS Extended User Interface &smbmdash; a complete misnomer!). + </para></glossdef> + </glossentry> + + + <glossentry> + <glossterm>NetBT</glossterm> + <acronym>NBT</acronym> + <glossdef><para>Protocol for transporting NetBIOS frames over TCP/IP. Uses ports 137, 138 and 139. + NetBT is a fully routable protocol. + </para></glossdef> + </glossentry> + + <?latex \newpage ?> + + <glossentry> + <glossterm>Local Master Browser</glossterm> + <acronym>LMB</acronym> + <glossdef><para>The Local Master Browser maintains a list + of all servers that have announced themselves within a given workgroup or NT domain on a particular + broadcast isolated subnet. See <link linkend="DMB"/> for details. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Printer Command Language</glossterm> + <acronym>PCL</acronym> + <glossdef><para> + A printer page description language that was developed by Hewlett Packard + and is in common use today. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Portable Document Format</glossterm> + <acronym>PDF</acronym> + <glossdef> + <para> + A highly compressed document format, based on postscript, used as a document distribution format + that is supported by Web browsers as well as many applications. Adobe also distribute an application + called <quote>acrobat</quote> which is a PDF reader. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Page Description Language</glossterm> + <acronym>PDL</acronym> + <glossdef><para>A language for describing the layout and contents of a printed page. + The best-known PDLs are Adobe PostScript and Hewlett-Packard PCL (Printer Control Language), + both of which are used to control laser printers.</para></glossdef> + </glossentry> + + <glossentry> + <glossterm>PostScript Printer Description</glossterm> + <acronym>PPD</acronym> + <glossdef><para> + PPD's specify and control options supported by postscript printers, such as duplexing, stapling, + DPI, ... See also <link linkend="post-and-ghost"/>. PPD files can be read by printing applications + to enable correct postscript page layout for a particular postscript printer. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Server Message Block</glossterm> + <acronym>SMB</acronym> + <glossdef><para> + SMB was the original name of the protocol `spoken' by + Samba. It was invented in the eighties by IBM and adopted + and extended further by Microsoft. Microsoft + renamed the protocol to CIFS during the Internet hype in the + nineties. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>User IDentifier</glossterm> + <acronym>UID</acronym> + <glossdef><para> + The UNIX system User Identifier; on older systems a 32-bit unsigned integer and on newer systems + an unsigned 64-bit integer. The UID is used in UNIX-like operating systems for all user level access + control. + </para></glossdef> + </glossentry> + + <glossentry> + <glossterm>Universal Naming Convention</glossterm> + <acronym>UNC</acronym> + <glossdef><para>A syntax for specifying the location of network resources (such as file shares). + The UNC syntax was developed in the early days of MS DOS 3.x and is used internally by the SMB protocol. + </para></glossdef> + </glossentry> +</glossary> diff --git a/docs/Samba3-HOWTO/TOSHARG-locking.xml b/docs/Samba3-HOWTO/TOSHARG-locking.xml new file mode 100644 index 0000000000..2aa6b622a2 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-locking.xml @@ -0,0 +1,1067 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="locking"> +<chapterinfo> + &author.jeremy; + &author.jelmer; + &author.jht; + &author.eroseme; +</chapterinfo> +<title>File and Record Locking</title> + +<para> +One area that causes trouble for many network administrators is locking. +The extent of the problem is readily evident from searches over the Internet. +</para> + +<sect1> +<title>Features and Benefits</title> + +<para> +Samba provides all the same locking semantics that MS Windows clients expect +and that MS Windows NT4/200x servers also provide. +</para> + +<para> +The term <emphasis>locking</emphasis> has exceptionally broad meaning and covers +a range of functions that are all categorized under this one term. +</para> + +<para> +Opportunistic locking is a desirable feature when it can enhance the +perceived performance of applications on a networked client. However, the +opportunistic locking protocol is not robust and, therefore, can +encounter problems when invoked beyond a simplistic configuration or +on extended slow or faulty networks. In these cases, operating +system management of opportunistic locking and/or recovering from +repetitive errors can offset the perceived performance advantage that +it is intended to provide. +</para> + +<para> +The MS Windows network administrator needs to be aware that file and record +locking semantics (behavior) can be controlled either in Samba or by way of registry +settings on the MS Windows client. +</para> + +<note> +<para> +Sometimes it is necessary to disable locking control settings on both the Samba +server as well as on each MS Windows client! +</para> +</note> + +</sect1> + +<sect1> +<title>Discussion</title> + +<para> +There are two types of locking that need to be performed by an SMB server. +The first is <emphasis>record locking</emphasis> that allows a client to lock +a range of bytes in a open file. The second is the <emphasis>deny modes</emphasis> +that are specified when a file is open. +</para> + +<para> +Record locking semantics under UNIX are very different from record locking under +Windows. Versions of Samba before 2.2 have tried to use the native fcntl() UNIX +system call to implement proper record locking between different Samba clients. +This cannot be fully correct for several reasons. The simplest is the fact +that a Windows client is allowed to lock a byte range up to 2^32 or 2^64, +depending on the client OS. The UNIX locking only supports byte ranges up to 2^31. +So it is not possible to correctly satisfy a lock request above 2^31. There are +many more differences, too many to be listed here. +</para> + +<para> +Samba 2.2 and above implements record locking completely independent of the +underlying UNIX system. If a byte range lock that the client requests happens +to fall into the range of 0-2^31, Samba hands this request down to the UNIX system. +All other locks cannot be seen by UNIX, anyway. +</para> + +<para> +Strictly speaking, an 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 <command>rpc.lockd</command>. This is almost always unnecessary as clients are supposed to +independently make locking calls before reads and writes if locking is +important to them. By default, Samba only makes locking calls when explicitly asked +to by a client, but if you set <smbconfoption name="strict locking">yes</smbconfoption>, it +will make lock checking calls on <emphasis>every</emphasis> read and write call. +</para> + +<para> +You can also disable byte range locking completely by using +<smbconfoption name="locking">no</smbconfoption>. +This is useful for those shares that do not support locking or do not need it +(such as CDROMs). In this case, Samba fakes the return codes of locking calls to +tell clients that everything is okay. +</para> + +<para> +The second class of locking is the <emphasis>deny modes</emphasis>. 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 +<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 +(as opposed to an API) via registry entries (on the server and the client) +for the purpose of enhancing network performance when accessing a file +residing on a server. Performance is enhanced by caching the file +locally on the client that allows: +</para> + +<variablelist> + <varlistentry><term>Read-ahead:</term> + <listitem><para> + The client reads the local copy of the file, eliminating network latency. + </para></listitem> + </varlistentry> + + <varlistentry><term>Write caching:</term> + <listitem><para> + The client writes to the local copy of the file, eliminating network latency. + </para></listitem> + </varlistentry> + + <varlistentry><term>Lock caching:</term> + <listitem><para> + The client caches application locks locally, eliminating network latency. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +The performance enhancement of oplocks is due to the opportunity of +exclusive access to the file &smbmdash; even if it is opened with deny-none &smbmdash; +because Windows monitors the file's status for concurrent access from +other processes. +</para> + +<variablelist> +<title>Windows defines 4 kinds of Oplocks:</title> + + <varlistentry><term>Level1 Oplock</term> + <listitem><para> + The redirector sees that the file was opened with deny + none (allowing concurrent access), verifies that no + other process is accessing the file, checks that + oplocks are enabled, then grants deny-all/read-write/exclusive + access to the file. The client now performs + operations on the cached local file. + </para> + + <para> + If a second process attempts to open the file, the open + is deferred while the redirector <quote>breaks</quote> the original + oplock. The oplock break signals the caching client to + write the local file back to the server, flush the + local locks and discard read-ahead data. The break is + then complete, the deferred open is granted, and the + multiple processes can enjoy concurrent file access as + dictated by mandatory or byte-range locking options. + However, if the original opening process opened the + file with a share mode other than deny-none, then the + second process is granted limited or no access, despite + the oplock break. + </para></listitem> + </varlistentry> + + <varlistentry><term>Level2 Oplock</term> + <listitem><para> + Performs like a Level1 oplock, except caching is only + operative for reads. All other operations are performed + on the server disk copy of the file. + </para></listitem> + </varlistentry> + + <varlistentry><term>Filter Oplock</term> + <listitem><para> + Does not allow write or delete file access. + </para></listitem> + </varlistentry> + + <varlistentry><term>Batch Oplock</term> + <listitem><para> + Manipulates file openings and closings and allows caching + of file attributes. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +An important detail is that oplocks are invoked by the file system, not +an application API. Therefore, an application can close an oplocked +file, but the file system does not relinquish the oplock. When the +oplock break is issued, the file system then simply closes the file in +preparation for the subsequent open by the second process. +</para> + +<para> +<emphasis>Opportunistic locking</emphasis> is actually an improper name for this feature. +The true benefit of this feature is client-side data caching, and +oplocks is merely a notification mechanism for writing data back to the +networked storage disk. The limitation of opportunistic locking is the +reliability of the mechanism to process an oplock break (notification) +between the server and the caching client. If this exchange is faulty +(usually due to timing out for any number of reasons), then the +client-side caching benefit is negated. +</para> + +<para> +The actual decision that a user or administrator should consider is +whether it is sensible to share among multiple users data that will +be cached locally on a client. In many cases the answer is no. +Deciding when to cache or not cache data is the real question, and thus +<quote>opportunistic locking</quote> should be treated as a toggle for client-side +caching. Turn it <quote>on</quote> when client-side caching is desirable and +reliable. Turn it <quote>off</quote> when client-side caching is redundant, +unreliable or counter-productive. +</para> + +<para> +Opportunistic locking is by default set to <quote>on</quote> by Samba on all +configured shares, so careful attention should be given to each case to +determine if the potential benefit is worth the potential for delays. +The following recommendations will help to characterize the environment +where opportunistic locking may be effectively configured. +</para> + +<para> +Windows opportunistic locking is a lightweight performance-enhancing +feature. It is not a robust and reliable protocol. Every +implementation of opportunistic locking should be evaluated as a +tradeoff between perceived performance and reliability. Reliability +decreases as each successive rule above is not enforced. Consider a +share with oplocks enabled, over a wide area network, to a client on a +South Pacific atoll, on a high-availability server, serving a +mission-critical multi-user corporate database during a tropical +storm. This configuration will likely encounter problems with oplocks. +</para> + +<para> +Oplocks can be beneficial to perceived client performance when treated +as a configuration toggle for client-side data caching. If the data +caching is likely to be interrupted, then oplock usage should be +reviewed. Samba enables opportunistic locking by default on all +shares. Careful attention should be given to the client usage of +shared data on the server, the server network reliability and the +opportunistic locking configuration of each share. +In mission critical high availability environments, data integrity is +often a priority. Complex and expensive configurations are implemented +to ensure that if a client loses connectivity with a file server, a +fail-over replacement will be available immediately to provide +continuous data availability. +</para> + +<para> +Windows client fail-over behavior is more at risk of application +interruption than other platforms because it is dependent upon an +established TCP transport connection. If the connection is interrupted +&smbmdash; as in a file server fail-over &smbmdash; a new session must be established. +It is rare for Windows client applications to be coded to recover +correctly from a transport connection loss, therefore, most applications +will experience some sort of interruption &smbmdash; at worst, abort and +require restarting. +</para> + +<para> +If a client session has been caching writes and reads locally due to +opportunistic locking, it is likely that the data will be lost when the +application restarts or recovers from the TCP interrupt. When the TCP +connection drops, the client state is lost. When the file server +recovers, an oplock break is not sent to the client. In this case, the +work from the prior session is lost. Observing this scenario with +oplocks disabled and with the client writing data to the file server +real-time, the fail-over will provide the data on disk as it +existed at the time of the disconnect. +</para> + +<para> +In mission-critical high-availability environments, careful attention +should be given to opportunistic locking. Ideally, comprehensive +testing should be done with all affected applications with oplocks +enabled and disabled. +</para> + +<sect3> +<title>Exclusively Accessed Shares</title> + +<para> +Opportunistic locking is most effective when it is confined to shares +that are exclusively accessed by a single user, or by only one user at +a time. Because the true value of opportunistic locking is the local +client caching of data, any operation that interrupts the caching +mechanism will cause a delay. +</para> + +<para> +Home directories are the most obvious examples of where the performance +benefit of opportunistic locking can be safely realized. +</para> + +</sect3> + +<sect3> +<title>Multiple-Accessed Shares or Files</title> + +<para> +As each additional user accesses a file in a share with opportunistic +locking enabled, the potential for delays and resulting perceived poor +performance increases. When multiple users are accessing a file on a +share that has oplocks enabled, the management impact of sending and +receiving oplock breaks and the resulting latency while other clients +wait for the caching client to flush data offset the performance gains +of the caching user. +</para> + +<para> +As each additional client attempts to access a file with oplocks set, +the potential performance improvement is negated and eventually results +in a performance bottleneck. +</para> + +</sect3> + +<sect3> +<title>UNIX or NFS Client-Accessed Files</title> + +<para> +Local UNIX and NFS clients access files without a mandatory +file-locking mechanism. Thus, these client platforms are incapable of +initiating an oplock break request from the server to a Windows client +that has a file cached. Local UNIX or NFS file access can therefore +write to a file that has been cached by a Windows client, which +exposes the file to likely data corruption. +</para> + +<para> +If files are shared between Windows clients, and either local UNIX +or NFS users, turn opportunistic locking off. +</para> + +</sect3> + +<sect3> +<title>Slow and/or Unreliable Networks</title> + +<para> +The biggest potential performance improvement for opportunistic locking +occurs when the client-side caching of reads and writes delivers the +most differential over sending those reads and writes over the wire. +This is most likely to occur when the network is extremely slow, +congested, or distributed (as in a WAN). However, network latency also +has a high impact on the reliability of the oplock break +mechanism, and thus increases the likelihood of encountering oplock +problems that more than offset the potential perceived performance +gain. Of course, if an oplock break never has to be sent, then this is +the most advantageous scenario to utilize opportunistic locking. +</para> + +<para> +If the network is slow, unreliable, or a WAN, then do not configure +opportunistic locking if there is any chance of multiple users +regularly opening the same file. +</para> + +</sect3> + +<sect3> +<title>Multi-User Databases</title> + +<para> +Multi-user databases clearly pose a risk due to their very nature &smbmdash; +they are typically heavily accessed by numerous users at random +intervals. Placing a multi-user database on a share with opportunistic +locking enabled will likely result in a locking management bottleneck +on the Samba server. Whether the database application is developed +in-house or a commercially available product, ensure that the share +has opportunistic locking disabled. +</para> + +</sect3> + +<sect3> +<title>PDM Data Shares</title> + +<para> +Process Data Management (PDM) applications such as IMAN, Enovia and +Clearcase are increasing in usage with Windows client platforms, and +therefore SMB data-stores. PDM applications manage multi-user +environments for critical data security and access. The typical PDM +environment is usually associated with sophisticated client design +applications that will load data locally as demanded. In addition, the +PDM application will usually monitor the data-state of each client. +In this case, client-side data caching is best left to the local +application and PDM server to negotiate and maintain. It is +appropriate to eliminate the client OS from any caching tasks, and the +server from any oplock management, by disabling opportunistic locking on +the share. +</para> + +</sect3> + +<sect3> +<title>Beware of Force User</title> + +<para> +Samba includes an &smb.conf; parameter called +<smbconfoption name="force user"/> that changes +the user accessing a share from the incoming user to whatever user is +defined by the smb.conf variable. If opportunistic locking is enabled +on a share, the change in user access causes an oplock break to be sent +to the client, even if the user has not explicitly loaded a file. In +cases where the network is slow or unreliable, an oplock break can +become lost without the user even accessing a file. This can cause +apparent performance degradation as the client continually reconnects +to overcome the lost oplock break. +</para> + +<para> +Avoid the combination of the following: +</para> + +<itemizedlist> + <listitem><para> + <smbconfoption name="force user"/> in the &smb.conf; share configuration. + </para></listitem> + + <listitem><para> + Slow or unreliable networks + </para></listitem> + + <listitem><para> + Opportunistic locking enabled + </para></listitem> +</itemizedlist> + +</sect3> + +<sect3> +<title>Advanced Samba Opportunistic Locking Parameters</title> + +<para> +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: +<smbconfoption name="oplock break wait time"/>, +<smbconfoption name="oplock contention limit"/>. +</para> + +<para> +For most users, administrators and environments, if these parameters +are required, then the better option is to simply turn oplocks off. +The Samba SWAT help text for both parameters reads: <quote>Do not change +this parameter unless you have read and understood the Samba oplock code.</quote> +This is good advice. +</para> + +</sect3> + +<sect3> +<title>Mission-Critical High-Availability</title> + +<para> +In mission-critical high-availability environments, data integrity is +often a priority. Complex and expensive configurations are implemented +to ensure that if a client loses connectivity with a file server, a +fail-over replacement will be available immediately to provide +continuous data availability. +</para> + +<para> +Windows client fail-over behavior is more at risk of application +interruption than other platforms because it is dependant upon an +established TCP transport connection. If the connection is interrupted +&smbmdash; as in a file server fail-over &smbmdash; a new session must be established. +It is rare for Windows client applications to be coded to recover +correctly from a transport connection loss, therefore, most applications +will experience some sort of interruption &smbmdash; at worst, abort and +require restarting. +</para> + +<para> +If a client session has been caching writes and reads locally due to +opportunistic locking, it is likely that the data will be lost when the +application restarts, or recovers from the TCP interrupt. When the TCP +connection drops, the client state is lost. When the file server +recovers, an oplock break is not sent to the client. In this case, the +work from the prior session is lost. Observing this scenario with +oplocks disabled, and the client was writing data to the file server +real-time, then the fail-over will provide the data on disk as it +existed at the time of the disconnect. +</para> + +<para> +In mission-critical high-availability environments, careful attention +should be given to opportunistic locking. Ideally, comprehensive +testing should be done with all effected applications with oplocks +enabled and disabled. +</para> + +</sect3> +</sect2> +</sect1> + +<sect1> +<title>Samba Opportunistic Locking Control</title> + +<para> +Opportunistic locking is a unique Windows file locking feature. It is +not really file locking, but is included in most discussions of Windows +file locking, so is considered a de facto locking feature. +Opportunistic locking is actually part of the Windows client file +caching mechanism. It is not a particularly robust or reliable feature +when implemented on the variety of customized networks that exist in +enterprise computing. +</para> + +<para> +Like Windows, Samba implements opportunistic locking as a server-side +component of the client caching mechanism. Because of the lightweight +nature of the Windows feature design, effective configuration of +opportunistic locking requires a good understanding of its limitations, +and then applying that understanding when configuring data access for +each particular customized network and client usage state. +</para> + +<para> +Opportunistic locking essentially means that the client is allowed to download and cache +a file on their hard drive while making changes; if a second client wants to access the +file, the first client receives a break and must synchronize the file back to the server. +This can give significant performance gains in some cases; some programs insist on +synchronizing the contents of the entire file back to the server for a single change. +</para> + +<para> +Level1 Oplocks (also known as just plain <quote>oplocks</quote>) is another term for opportunistic locking. +</para> + +<para> +Level2 Oplocks provides opportunistic locking for a file that will be treated as +<emphasis>read only</emphasis>. Typically this is used on files that are read-only or +on files that the client has no initial intention to write to at time of opening the file. +</para> + +<para> +Kernel Oplocks are essentially a method that allows the Linux kernel to co-exist with +Samba's oplocked files, although this has provided better integration of MS Windows network +file locking with the underlying OS, SGI IRIX and Linux are the only two OSs that are +oplock-aware at this time. +</para> + +<para> +Unless your system supports kernel oplocks, you should disable oplocks if you are +accessing the same files from both UNIX/Linux and SMB clients. Regardless, oplocks should +always be disabled if you are sharing a database file (e.g., Microsoft Access) between +multiple clients, as any break the first client receives will affect synchronization of +the entire file (not just the single record), which will result in a noticeable performance +impairment and, more likely, problems accessing the database in the first place. Notably, +Microsoft Outlook's personal folders (*.pst) react quite badly to oplocks. If in doubt, +disable oplocks and tune your system from that point. +</para> + +<para> +If client-side caching is desirable and reliable on your network, you will benefit from +turning on oplocks. If your network is slow and/or unreliable, or you are sharing your +files among other file sharing mechanisms (e.g., NFS) or across a WAN, or multiple people +will be accessing the same files frequently, you probably will not benefit from the overhead +of your client sending oplock breaks and will instead want to disable oplocks for the share. +</para> + +<para> +Another factor to consider is the perceived performance of file access. If oplocks provide no +measurable speed benefit on your network, it might not be worth the hassle of dealing with them. +</para> + +<sect2> +<title>Example Configuration</title> + +<para> +In the following section we examine two distinct aspects of Samba locking controls. +</para> + +<sect3> +<title>Disabling Oplocks</title> + +<para> +You can disable oplocks on a per-share basis with the following: +</para> + +<para> +<smbconfblock> +<smbconfsection name="[acctdata]"/> +<smbconfoption name="oplocks">False</smbconfoption> +<smbconfoption name="level2 oplocks">False</smbconfoption> +</smbconfblock> +</para> + +<para> +The default oplock type is Level1. Level2 oplocks are enabled on a per-share basis +in the &smb.conf; file. +</para> + +<para> +Alternately, you could disable oplocks on a per-file basis within the share: +</para> + +<para> + <smbconfblock> +<smbconfoption name="veto oplock files">/*.mdb/*.MDB/*.dbf/*.DBF/</smbconfoption> +</smbconfblock> +</para> + +<para> +If you are experiencing problems with oplocks as apparent from Samba's log entries, +you may want to play it safe and disable oplocks and Level2 oplocks. +</para> + +</sect3> + +<sect3> +<title>Disabling Kernel Oplocks</title> + +<para> +Kernel oplocks is an &smb.conf; parameter that notifies Samba (if +the UNIX kernel has the capability to send a Windows client an oplock +break) when a UNIX process is attempting to open the file that is +cached. This parameter addresses sharing files between UNIX and +Windows with oplocks enabled on the Samba server: the UNIX process +can open the file that is Oplocked (cached) by the Windows client and +the smbd process will not send an oplock break, which exposes the file +to the risk of data corruption. If the UNIX kernel has the ability to +send an oplock break, then the kernel oplocks parameter enables Samba +to send the oplock break. Kernel oplocks are enabled on a per-server +basis in the &smb.conf; file. +</para> + +<para> +<smbconfblock> +<smbconfoption name="kernel oplocks">yes</smbconfoption> +</smbconfblock> +The default is no. +</para> + +<para> +Veto opLocks is an &smb.conf; parameter that identifies specific files for +which oplocks are disabled. When a Windows client opens a file that +has been configured for veto oplocks, the client will not be granted +the oplock, and all operations will be executed on the original file on +disk instead of a client-cached file copy. By explicitly identifying +files that are shared with UNIX processes and disabling oplocks for +those files, the server-wide Oplock configuration can be enabled to +allow Windows clients to utilize the performance benefit of file +caching without the risk of data corruption. Veto Oplocks can be +enabled on a per-share basis, or globally for the entire server, in the +&smb.conf; file as shown in <link linkend="far1"/>. +</para> + +<para> +<smbconfexample id="far1"> +<title>Share with some files oplocked</title> +<smbconfsection name="[global]"/> +<smbconfoption name="veto oplock files">/filename.htm/*.txt/</smbconfoption> + +<smbconfsection name="[share_name]"/> +<smbconfoption name="veto oplock files">/*.exe/filename.ext/</smbconfoption> +</smbconfexample> +</para> + +<para> +<smbconfoption name="oplock break wait time"/> is an &smb.conf; parameter +that adjusts the time interval for Samba to reply to an oplock break request. Samba recommends: +<quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote> +Oplock break Wait Time can only be configured globally in the &smb.conf; file as shown below. +</para> + +<para> + <smbconfblock> +<smbconfoption name="oplock break wait time"> 0 (default)</smbconfoption> +</smbconfblock> +</para> + +<para> +<emphasis>Oplock break contention limit</emphasis> is an &smb.conf; parameter that limits the +response of the Samba server to grant an oplock if the configured +number of contending clients reaches the limit specified by the parameter. Samba recommends +<quote>Do not change this parameter unless you have read and understood the Samba oplock code.</quote> +Oplock break Contention Limit can be enable on a per-share basis, or globally for +the entire server, in the &smb.conf; file as shown in <link linkend="far3"/>. +</para> + +<para> +<smbconfexample id="far3"> + <title>Configuration with oplock break contention limit</title> +<smbconfsection name="[global]"/> +<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption> + +<smbconfsection name="[share_name]"/> +<smbconfoption name="oplock break contention limit"> 2 (default)</smbconfoption> +</smbconfexample> +</para> + +</sect3> +</sect2> + +</sect1> + +<sect1> +<title>MS Windows Opportunistic Locking and Caching Controls</title> + +<para> +There is a known issue when running applications (like Norton Anti-Virus) on a Windows 2000/ XP +workstation computer that can affect any application attempting to access shared database files +across a network. This is a result of a default setting configured in the Windows 2000/XP +operating system known as <emphasis>opportunistic locking</emphasis>. When a workstation +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 <quote>Access Denied</quote> + error message being displayed during network operations. +</para> + +<para> +All Windows operating systems in the NT family that act as database servers for data files +(meaning that data files are stored there and accessed by other Windows PCs) may need to +have opportunistic locking disabled in order to minimize the risk of data file corruption. +This includes Windows 9x/Me, Windows NT, Windows 200x, and Windows XP. +<footnote><para>Microsoft has documented this in Knowledge Base article 300216.</para></footnote> +</para> + +<para> +If you are using a Windows NT family workstation in place of a server, you must also +disable opportunistic locking (oplocks) on that workstation. For example, if you use a +PC with the Windows NT Workstation operating system instead of Windows NT Server, and you +have data files located on it that are accessed from other Windows PCs, you may need to +disable oplocks on that system. +</para> + +<para> +The major difference is the location in the Windows registry where the values for disabling +oplocks are entered. Instead of the LanManServer location, the LanManWorkstation location +may be used. +</para> + +<para> +You can verify (change or add, if necessary) this registry value using the Windows +Registry Editor. When you change this registry value, you will have to reboot the PC +to ensure that the new setting goes into effect. +</para> + +<para> +The location of the client registry entry for opportunistic locking has changed in +Windows 2000 from the earlier location in Microsoft Windows NT. +</para> + +<note><para> +Windows 2000 will still respect the EnableOplocks registry value used to disable oplocks +in earlier versions of Windows. +</para></note> + +<para> +You can also deny the granting of opportunistic locks by changing the following registry entries: +</para> + +<para> +<programlisting> + HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\MRXSmb\Parameters\ + + OplocksDisabled REG_DWORD 0 or 1 + Default: 0 (not disabled) +</programlisting> +</para> + +<note><para> +The OplocksDisabled registry value configures Windows clients to either request or not +request opportunistic locks on a remote file. To disable oplocks, the value of + OplocksDisabled must be set to 1. +</para></note> + +<para> +<programlisting> + HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\LanmanServer\Parameters + + EnableOplocks REG_DWORD 0 or 1 + Default: 1 (Enabled by Default) + + EnableOpLockForceClose REG_DWORD 0 or 1 + Default: 0 (Disabled by Default) +</programlisting> +</para> + +<note><para> +The EnableOplocks value configures Windows-based servers (including Workstations sharing +files) to allow or deny opportunistic locks on local files. +</para></note> + +<para> +To force closure of open oplocks on close or program exit, EnableOpLockForceClose must be set to 1. +</para> + +<para> +An illustration of how Level2 oplocks work: +</para> + +<itemizedlist> + <listitem><para> + Station 1 opens the file requesting oplock. + </para></listitem> + <listitem><para> + Since no other station has the file open, the server grants station 1 exclusive oplock. + </para></listitem> + <listitem><para> + Station 2 opens the file requesting oplock. + </para></listitem> + <listitem><para> + Since station 1 has not yet written to the file, the server asks station 1 to break + to Level2 oplock. + </para></listitem> + <listitem><para> + Station 1 complies by flushing locally buffered lock information to the server. + </para></listitem> + <listitem><para> + Station 1 informs the server that it has Broken to Level2 Oplock (alternately, + station 1 could have closed the file). + </para></listitem> + <listitem><para> + The server responds to station 2's open request, granting it Level2 oplock. + Other stations can likewise open the file and obtain Level2 oplock. + </para></listitem> + <listitem><para> + Station 2 (or any station that has the file open) sends a write request SMB. + The server returns the write response. + </para></listitem> + <listitem><para> + The server asks all stations that have the file open to break to none, meaning no + station holds any oplock on the file. Because the workstations can have no cached + writes or locks at this point, they need not respond to the break-to-none advisory; + all they need do is invalidate locally cashed read-ahead data. + </para></listitem> +</itemizedlist> + +<sect2> +<title>Workstation Service Entries</title> + +<para><programlisting> + \HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\LanmanWorkstation\Parameters + + UseOpportunisticLocking REG_DWORD 0 or 1 + Default: 1 (true) +</programlisting></para> + +<para> +This indicates whether the redirector should use opportunistic-locking (oplock) performance +enhancement. This parameter should be disabled only to isolate problems. +</para> + +</sect2> +<sect2> +<title>Server Service Entries</title> + +<para><programlisting> + \HKEY_LOCAL_MACHINE\System\ + CurrentControlSet\Services\LanmanServer\Parameters + + EnableOplocks REG_DWORD 0 or 1 + Default: 1 (true) +</programlisting></para> + +<para> +This specifies whether the server allows clients to use oplocks on files. Oplocks are a +significant performance enhancement, but have the potential to cause lost cached +data on some networks, particularly wide area networks. +</para> + +<para><programlisting> + MinLinkThroughput REG_DWORD 0 to infinite bytes per second + Default: 0 +</programlisting></para> + +<para> +This specifies the minimum link throughput allowed by the server before it disables +raw and opportunistic locks for this connection. +</para> + +<para><programlisting> + MaxLinkDelay REG_DWORD 0 to 100,000 seconds + Default: 60 +</programlisting></para> + +<para> +This specifies the maximum time allowed for a link delay. If delays exceed this number, +the server disables raw I/O and opportunistic locking for this connection. +</para> + +<para><programlisting> + OplockBreakWait REG_DWORD 10 to 180 seconds + Default: 35 +</programlisting></para> + +<para> +This specifies the time that the server waits for a client to respond to an oplock break +request. Smaller values can allow detection of crashed clients more quickly but can +potentially cause loss of cached data. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Persistent Data Corruption</title> + +<para> +If you have applied all of the settings discussed in this chapter but data corruption problems +and other symptoms persist, here are some additional things to check out. +</para> + +<para> +We have credible reports from developers that faulty network hardware, such as a single +faulty network card, can cause symptoms similar to read caching and data corruption. +If you see persistent data corruption even after repeated re-indexing, you may have to +rebuild the data files in question. This involves creating a new data file with the +same definition as the file to be rebuilt and transferring the data from the old file +to the new one. There are several known methods for doing this that can be found in +our Knowledge Base. +</para> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +In some sites, locking problems surface as soon as a server is installed; in other sites +locking problems may not surface for a long time. Almost without exception, when a locking +problem does surface it will cause embarrassment and potential data corruption. +</para> + +<para> +Over the past few years there have been a number of complaints on the Samba mailing lists +that have claimed that Samba caused data corruption. Three causes have been identified +so far: +</para> + +<itemizedlist> + <listitem><para> + Incorrect configuration of opportunistic locking (incompatible with the application + being used. This is a common problem even where MS Windows NT4 or MS Windows + 200x-based servers were in use. It is imperative that the software application vendors' + instructions for configuration of file locking should be followed. If in doubt, + disable oplocks on both the server and the client. Disabling of all forms of file + caching on the MS Windows client may be necessary also. + </para></listitem> + + <listitem><para> + Defective network cards, cables, or HUBs/Switched. This is generally a more + prevalent factor with low cost networking hardware, although occasionally there + have also been problems with incompatibilities in more up-market hardware. + </para></listitem> + + <listitem><para> + There have been some random reports of Samba log files being written over data + files. This has been reported by very few sites (about five in the past three years) + and all attempts to reproduce the problem have failed. The Samba Team has been + unable to catch this happening and thus has not been able to isolate any particular + cause. Considering the millions of systems that use Samba, for the sites that have + been affected by this as well as for the Samba Team this is a frustrating and + a vexing challenge. If you see this type of thing happening, please create a bug + report on Samba <ulink url="https://bugzilla.samba.org">Bugzilla</ulink> without delay. + Make sure that you give as much information as you possibly can help isolate the + cause and to allow replication of the problem (an essential step in problem isolation and correction). + </para></listitem> +</itemizedlist> + + <sect2> + <title>locking.tdb Error Messages</title> + + <para> + <quote> + We are seeing lots of errors in the Samba logs, like: + </quote> +<programlisting> +tdb(/usr/local/samba_2.2.7/var/locks/locking.tdb): rec_read bad magic + 0x4d6f4b61 at offset=36116 +</programlisting> + + <quote> + What do these mean? + </quote> + </para> + + <para> + This error indicated a corrupted tdb. Stop all instances of smbd, delete locking.tdb, and restart smbd. + </para> + + </sect2> + + <sect2> + <title>Problems Saving Files in MS Office on Windows XP</title> + + <para>This is a bug in Windows XP. More information can be + found in <ulink url="http://support.microsoft.com/?id=812937">Microsoft Knowledge Base article 812937.</ulink></para> + + </sect2> + + <sect2> + + <title>Long Delays Deleting Files Over Network with XP SP1</title> + + <para><quote>It sometimes takes approximately 35 seconds to delete files over the network after XP SP1 has been applied.</quote></para> + + <para>This is a bug in Windows XP. More information can be found in <ulink url="http://support.microsoft.com/?id=811492"> + Microsoft Knowledge Base article 811492.</ulink></para> + </sect2> + +</sect1> + +<sect1> +<title>Additional Reading</title> + +<para> +You may want to check for an updated version of this white paper on our Web site from +time to time. Many of our white papers are updated as information changes. For those papers, +the last edited date is always at the top of the paper. +</para> + +<para> +Section of the Microsoft MSDN Library on opportunistic locking: +</para> + +<para> +Opportunistic Locks, Microsoft Developer Network (MSDN), Windows Development > +Windows Base Services > Files and I/O > SDK Documentation > File Storage > File Systems +> About File Systems > Opportunistic Locks, Microsoft Corporation. +<ulink noescape="1" url="http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp">http://msdn.microsoft.com/library/en-us/fileio/storage_5yk3.asp</ulink> +</para> + +<para> + Microsoft Knowledge Base Article Q224992 <?latex \linebreak ?><quote>Maintaining Transactional Integrity +with OPLOCKS</quote>, +Microsoft Corporation, April 1999, <ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q224992</ulink>. +</para> + +<para> +Microsoft Knowledge Base Article Q296264 <quote>Configuring Opportunistic Locking in Windows 2000</quote>, +Microsoft Corporation, April 2001, <ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q296264</ulink>. +</para> + +<para> +Microsoft Knowledge Base Article Q129202 <quote>PC Ext: Explanation of Opportunistic Locking on Windows NT</quote>, +Microsoft Corporation, April 1995, <ulink noescape="1" url="http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202">http://support.microsoft.com/default.aspx?scid=kb;en-us;Q129202</ulink>. +</para> + +</sect1> +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-msdfs.xml b/docs/Samba3-HOWTO/TOSHARG-msdfs.xml new file mode 100644 index 0000000000..126edd0eb6 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-msdfs.xml @@ -0,0 +1,161 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="msdfs"> + +<chapterinfo> + <author> + <firstname>Shirish</firstname><surname>Kalele</surname> + <affiliation> + <orgname>Samba Team & Veritas Software</orgname> + <address> + <email>samba@samba.org</email> + </address> + </affiliation> + </author> + &author.jht; + + <pubdate>12 Jul 2000</pubdate> +</chapterinfo> + +<title>Hosting a Microsoft Distributed File System Tree</title> + +<sect1> +<title>Features and Benefits</title> + + <para> + The Distributed File System (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, and so on. + </para> + + <para> + For information about DFS, refer to the +<ulink url="http://www.microsoft.com/NTServer/nts/downloads/winfeatures/NTSDistrFile/AdminGuide.asp">Microsoft documentation</ulink>. + This document explains how to host a DFS tree on a UNIX machine (for DFS-aware + clients to browse) using Samba. + </para> + + <para> + A Samba server can be made a DFS server by setting the global + Boolean <smbconfoption name="host msdfs"/> + parameter in the &smb.conf; file. You designate a share as a DFS + root using the Share Level Boolean <smbconfoption name="msdfs root"/> 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, <parameter>\\storage1\share1</parameter>). + </para> + + <para> + DFS trees on Samba work with all DFS-aware clients ranging from Windows 95 to 200x. + <link linkend="dfscfg">Following sample configuration</link> shows how to setup a DFS tree on a Samba server. + In the <filename>/export/dfsroot</filename> directory, you set up your DFS links to + other servers on the network. +<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> + +<para> +<smbconfexample id="dfscfg"> +<title>smb.conf with DFS configured</title> +<smbconfsection name="[global]"/> +<smbconfoption name="netbios name">&example.server.samba;</smbconfoption> +<smbconfoption name="host msdfs ">yes</smbconfoption> + +<smbconfsection name="[dfs]"/> +<smbconfoption name="path">/export/dfsroot</smbconfoption> +<smbconfoption name="msdfs root">yes</smbconfoption> +</smbconfexample> +</para> + + <para>You should set up the permissions and ownership of + the directory acting as the DFS root so 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 + 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> +</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 only designated users can + modify the symbolic links in the directory.</para> + </listitem> + </itemizedlist> + + <sect2> + <title>MSDFS UNIX Path Is Case-Critical</title> + + <para> + A network administrator sent advice to the Samba mailing list + after a long sessions trying to determine why DFS was not working. + His advice is worth noting. + </para> + + <para><quote> + I spent some time trying to figure out why my particular + dfs root wasn't working. I noted in the documentation that + the symlink should be in all lowercase. It should be + amended that the entire path to the symlink should all be + in lowercase as well. + </quote></para> + + <para> + For example, I had a share defined as such: + + <screen> + [pub] + path = /export/home/Shares/public_share + msdfs root = yes + </screen> + + and I could not make my Windows 9x/Me (with the dfs client installed) + follow this symlink: + + <screen> + damage1 -> msdfs:damage\test-share + </screen> + </para> + + <para> + Running a debug level of 10 reveals: + + <programlisting> + [2003/08/20 11:40:33, 5] msdfs/msdfs.c:is_msdfs_link(176) + is_msdfs_link: /export/home/shares/public_share/* does not exist. + </programlisting> + + Curious. So I changed the directory name from .../Shares/... to + .../shares/... (along with my service definition) and it worked! + </para> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/TOSHARG-preface.xml b/docs/Samba3-HOWTO/TOSHARG-preface.xml new file mode 100644 index 0000000000..43df53e523 --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-preface.xml @@ -0,0 +1,61 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE book PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> + +<preface id="TOSHpreface"> +<title>Preface</title> + +<para> +The editors wish to thank you for your decision to purchase this book. +The Official Samba-3 HOWTO and Reference Guide is the result of many years +of accumulation of information, feedback, tips, hints, and happy solutions. +</para> + +<para> +Please note that this book is a living document, the contents of which are +constantly being updated. We encourage you to contribute your tips, techniques, +helpful hints, and your special insight into the Windows networking world to +help make the next generation of this book even more valuable to Samba users. +</para> + +<para> +We have made a concerted effort to document more comprehensively than has been +done previously the information that may help you to better deploy Samba and to +gain more contented network users. +</para> + +<para> +This book provides example configurations, it documents key aspects of Microsoft +Windows networking, provides in-depth insight into the important configuration of +Samba-3, and helps to put all of these into a useful framework. +</para> + +<para> +The most recent electronic versions of this document can be found at +<ulink noescape="1" url="http://www.samba.org/">http://www.samba.org/</ulink> +on the <quote>Documentation</quote> page. +</para> + +<para> +Updates, patches and corrections are most welcome. Please email your contributions +to any one of the following: +</para> + +<para> +<simplelist> +<member><ulink noescape="1" url="mailto:jelmer@samba.org">Jelmer Vernooij (jelmer@samba.org)</ulink></member> +<member><ulink noescape="1" url="mailto:jht@samba.org">John H. Terpstra (jht@samba.org)</ulink></member> +<member><ulink noescape="1" url="mailto:jerry@samba.org">Gerald (Jerry) Carter (jerry@samba.org)</ulink></member> +</simplelist> +</para> + +<para> +We wish to advise that only original and unencumbered material can be published. Please do not submit +content that is not your own work unless proof of consent from the copyright holder accompanies your +submission. +</para> + + <!-- the conventions used in this book --> + <xi:include href="conventions.xml" xmlns:xi="http://www.w3.org/2003/XInclude" /> + + +</preface> diff --git a/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml b/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml new file mode 100644 index 0000000000..6f3853fd6f --- /dev/null +++ b/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml @@ -0,0 +1,610 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<chapter id="upgrading-to-3.0"> +<chapterinfo> + &author.jelmer; + &author.jht; + &author.jerry; + <pubdate>June 30, 2003</pubdate> +</chapterinfo> + +<title>Upgrading from Samba-2.x to Samba-3.0.20</title> + +<para> +This chapter deals exclusively with the differences between Samba-3.0.20 and Samba-2.2.8a. +It points out where configuration parameters have changed, and provides a simple guide for +the move from 2.2.x to 3.0.20. +</para> + +<sect1> +<title>Quick Migration Guide</title> + +<para> +Samba-3.0.20 default behavior should be approximately the same as Samba-2.2.x. +The default behavior when the new parameter <smbconfoption name="passdb backend"/> +is not defined in the &smb.conf; file provides the same default behavior as Samba-2.2.x +with <smbconfoption name="encrypt passwords">Yes</smbconfoption>, and +will use the <filename>smbpasswd</filename> database. +</para> + +<para> +So why say that <emphasis>behavior should be approximately the same as Samba-2.2.x?</emphasis> Because +Samba-3.0.20 can negotiate new protocols, such as support for native Unicode, that may result in +differing protocol code paths being taken. The new behavior under such circumstances is not +exactly the same as the old one. The good news is that the domain and machine SIDs will be +preserved across the upgrade. +</para> + +<para> +If the Samba-2.2.x system was using an LDAP backend, and there is no time to update the LDAP +database, then make sure that <smbconfoption name="passdb backend">ldapsam_compat</smbconfoption> +is specified in the &smb.conf; file. For the rest, behavior should remain more or less the same. +At a later date, when there is time to implement a new Samba-3 compatible LDAP backend, it is possible +to migrate the old LDAP database to the new one through use of the <command>pdbedit</command>. +See <link linkend="pdbeditthing">The <emphasis>pdbedit</emphasis> Command</link>. +</para> + +</sect1> + +<sect1> +<title>New Features in Samba-3</title> + +<para> +The major new features are: +</para> + +<orderedlist numeration="arabic"> + <listitem><para> + Active Directory support. This release is able to join an ADS realm + as a member server and authenticate users using LDAP/Kerberos. + </para></listitem> + + <listitem><para> + Unicode support. Samba will now negotiate Unicode on the wire and + internally there is a much better infrastructure for multi-byte + and Unicode character sets. + </para></listitem> + + <listitem><para> + New authentication system. The internal authentication system has + been almost completely rewritten. Most of the changes are internal, + but the new authoring system is also very configurable. + </para></listitem> + + <listitem><para> + New filename mangling system. The filename mangling system has been + completely rewritten. An internal database now stores mangling maps + persistently. + </para></listitem> + + <listitem><para> + New <quote>net</quote> command. A new <quote>net</quote> command has been added. It is + somewhat similar to the <quote>net</quote> command in Windows. Eventually, we + plan to replace a bunch of other utilities (such as smbpasswd) + with subcommands in <quote>net</quote>. + </para></listitem> + + <listitem><para> + Samba now negotiates NT-style status32 codes on the wire. This + considerably improves error handling. + </para></listitem> + + <listitem><para> + Better Windows 200x/XP printing support including publishing + printer attributes in Active Directory. + </para></listitem> + + <listitem><para> + New loadable RPC modules for passdb backends and character sets. + </para></listitem> + + <listitem><para> + New default dual-daemon winbindd support for better performance. + </para></listitem> + + <listitem><para> + Support for migrating from a Windows NT 4.0 domain to a Samba + domain and maintaining user, group and domain SIDs. + </para></listitem> + + <listitem><para> + Support for establishing trust relationships with Windows NT 4.0 + Domain Controllers. + </para></listitem> + + <listitem><para> + Initial support for a distributed Winbind architecture using + an LDAP directory for storing SID to UID/GID mappings. + </para></listitem> + + <listitem><para> + Major updates to the Samba documentation tree. + </para></listitem> + + <listitem><para> + Full support for client and server SMB signing to ensure + compatibility with default Windows 2003 security settings. + </para></listitem> +</orderedlist> + +<para> +Plus lots of other improvements! +</para> + +</sect1> + +<sect1> +<title>Configuration Parameter Changes</title> + +<para> +This section contains a brief listing of changes to &smb.conf; options +in the 3.0.20 release. Please refer to the smb.conf(5) man page for +complete descriptions of new or modified parameters. +</para> + +<sect2> +<title>Removed Parameters</title> + +<para>(Ordered Alphabetically):</para> + +<itemizedlist> + <listitem><para>admin log </para></listitem> + <listitem><para>alternate permissions </para></listitem> + <listitem><para>character set </para></listitem> + <listitem><para>client codepage </para></listitem> + <listitem><para>code page directory </para></listitem> + <listitem><para>coding system </para></listitem> + <listitem><para>domain admin group </para></listitem> + <listitem><para>domain guest group </para></listitem> + <listitem><para>force unknown acl user </para></listitem> + <listitem><para>nt smb support </para></listitem> + <listitem><para>post script </para></listitem> + <listitem><para>printer driver </para></listitem> + <listitem><para>printer driver file </para></listitem> + <listitem><para>printer driver location </para></listitem> + <listitem><para>status </para></listitem> + <listitem><para>strip dot </para></listitem> + <listitem><para>total print jobs </para></listitem> + <listitem><para>use rhosts </para></listitem> + <listitem><para>valid chars </para></listitem> + <listitem><para>vfs options </para></listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>New Parameters</title> + +<para>(New parameters have been grouped by function):</para> + +<para>Remote Management</para> + +<itemizedlist> + <listitem><para>abort shutdown script </para></listitem> + <listitem><para>shutdown script </para></listitem> +</itemizedlist> + +<para>User and Group Account Management:</para> + +<itemizedlist> + <listitem><para>add group script </para></listitem> + <listitem><para>add machine script </para></listitem> + <listitem><para>add user to group script </para></listitem> + <listitem><para>algorithmic rid base </para></listitem> + <listitem><para>delete group script </para></listitem> + <listitem><para>delete user from group script </para></listitem> + <listitem><para>passdb backend </para></listitem> + <listitem><para>set primary group script </para></listitem> +</itemizedlist> + +<para>Authentication:</para> + +<itemizedlist> + <listitem><para>auth methods </para></listitem> + <listitem><para>realm </para></listitem> +</itemizedlist> + +<para>Protocol Options:</para> + +<itemizedlist> + <listitem><para>client lanman auth </para></listitem> + <listitem><para>client NTLMv2 auth </para></listitem> + <listitem><para>client schannel </para></listitem> + <listitem><para>client signing </para></listitem> + <listitem><para>client use spnego </para></listitem> + <listitem><para>disable netbios </para></listitem> + <listitem><para>ntlm auth </para></listitem> + <listitem><para>paranoid server security </para></listitem> + <listitem><para>server schannel </para></listitem> + <listitem><para>server signing </para></listitem> + <listitem><para>smb ports </para></listitem> + <listitem><para>use spnego </para></listitem> +</itemizedlist> + +<para>File Service:</para> + +<itemizedlist> + <listitem><para>get quota command </para></listitem> + <listitem><para>hide special files </para></listitem> + <listitem><para>hide unwriteable files </para></listitem> + <listitem><para>hostname lookups </para></listitem> + <listitem><para>kernel change notify </para></listitem> + <listitem><para>mangle prefix </para></listitem> + <listitem><para>map acl inherit </para></listitem> + <listitem><para>msdfs proxy </para></listitem> + <listitem><para>set quota command </para></listitem> + <listitem><para>use sendfile </para></listitem> + <listitem><para>vfs objects </para></listitem> +</itemizedlist> + +<para>Printing:</para> + +<itemizedlist> + <listitem><para>max reported print jobs </para></listitem> +</itemizedlist> + + +<para>Unicode and Character Sets:</para> + +<itemizedlist> + <listitem><para>display charset </para></listitem> + <listitem><para>dos charset </para></listitem> + <listitem><para>unicode </para></listitem> + <listitem><para>UNIX charset </para></listitem> +</itemizedlist> + +<para>SID to UID/GID Mappings:</para> + +<itemizedlist> + <listitem><para>idmap backend </para></listitem> + <listitem><para>idmap gid </para></listitem> + <listitem><para>idmap uid </para></listitem> + <listitem><para>winbind enable local accounts </para></listitem> + <listitem><para>winbind trusted domains only </para></listitem> + <listitem><para>template primary group </para></listitem> + <listitem><para>enable rid algorithm </para></listitem> +</itemizedlist> + +<para>LDAP:</para> + +<itemizedlist> + <listitem><para>ldap delete dn </para></listitem> + <listitem><para>ldap group suffix </para></listitem> + <listitem><para>ldap idmap suffix </para></listitem> + <listitem><para>ldap machine suffix </para></listitem> + <listitem><para>ldap passwd sync </para></listitem> + <listitem><para>ldap user suffix </para></listitem> +</itemizedlist> + +<para>General Configuration:</para> + +<itemizedlist> + <listitem><para>preload modules </para></listitem> + <listitem><para>privatedir </para></listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Modified Parameters (Changes in Behavior):</title> + +<itemizedlist> + <listitem><para>encrypt passwords (enabled by default) </para></listitem> + <listitem><para>mangling method (set to hash2 by default) </para></listitem> + <listitem><para>passwd chat </para></listitem> + <listitem><para>passwd program </para></listitem> + <listitem><para>password server </para></listitem> + <listitem><para>restrict anonymous (integer value) </para></listitem> + <listitem><para>security (new ads value) </para></listitem> + <listitem><para>strict locking (enabled by default) </para></listitem> + <listitem><para>winbind cache time (increased to 5 minutes) </para></listitem> + <listitem><para>winbind uid (deprecated in favor of idmap uid) </para></listitem> + <listitem><para>winbind gid (deprecated in favor of idmap gid) </para></listitem> +</itemizedlist> + +</sect2> + +</sect1> + +<sect1> +<title>New Functionality</title> + + <sect2> + <title>Databases</title> + + <para> + This section contains brief descriptions of any new databases + introduced in Samba-3. Please remember to backup your existing + ${lock directory}/*tdb before upgrading to Samba-3. Samba will + upgrade databases as they are opened (if necessary), but downgrading + from 3.0 to 2.2 is an unsupported path. + </para> + + <para> + The new tdb files are described in <link linkend="tdbfiledesc">the next table</link>. + </para> + + + <table frame='all' id="tdbfiledesc"><title>TDB File Descriptions</title> + <tgroup cols='3'> + <colspec align="left"/> + <colspec align="justify" colwidth="1*"/> + <colspec align="left"/> + <thead> + <row> + <entry align="left">Name</entry> + <entry align="justify">Description</entry> + <entry align="center">Backup?</entry> + </row> + </thead> + <tbody> + <row> + <entry>account_policy</entry> + <entry>User policy settings</entry> + <entry>yes</entry> + </row> + <row> + <entry>gencache</entry> + <entry>Generic caching db</entry> + <entry>no</entry> + </row> + <row> + <entry>group_mapping</entry> + <entry><para>Mapping table from Windows groups/SID to UNIX groups</para></entry> + <entry>yes</entry> + </row> + <row> + <entry>idmap</entry> + <entry><para>new ID map table from SIDS to UNIX UIDs/GIDs</para></entry> + <entry>yes</entry> + </row> + <row> + <entry>namecache</entry> + <entry>Name resolution cache entries</entry> + <entry>no</entry> + </row> + <row> + <entry>netlogon_unigrp</entry> + <entry><para>Cache of universal group membership obtained when operating + as a member of a Windows domain</para></entry> + <entry>no</entry> + </row> + <row> + <entry>printing/*.tdb</entry> + <entry><para>Cached output from `lpq command' created on a per print + service basis</para></entry> + <entry>no</entry> + </row> + <row> + + <entry>registry</entry> + <entry><para>Read-only Samba registry skeleton that provides support for + exporting various db tables via the winreg RPCs</para></entry> + <entry>no</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>Changes in Behavior</title> + + <para> + The following issues are known changes in behavior between Samba-2.2 and + Samba-3 that may affect certain installations of Samba. + </para> + + <orderedlist> + <listitem><para> + When operating as a member of a Windows domain, Samba-2.2 would + map any users authenticated by the remote DC to the <quote>guest account</quote> + if a uid could not be obtained via the getpwnam() call. Samba-3 + rejects the connection as <?latex \linebreak ?>NT_STATUS_LOGON_FAILURE. There is no + current work around to re-establish the Samba-2.2 behavior. + </para></listitem> + + <listitem><para> + When adding machines to a Samba-2.2 controlled domain, the + <quote>add user script</quote> was used to create the UNIX identity of the + Machine Trust Account. Samba-3 introduces a new <quote>add machine + script</quote> that must be specified for this purpose. Samba-3 will + not fall back to using the <quote>add user script</quote> in the absence of + an <quote>add machine script</quote>. + </para></listitem> + </orderedlist> + + </sect2> + + <sect2> + <title>Passdb Backends and Authentication</title> + + <para> + There have been a few new changes that Samba administrators should be + aware of when moving to Samba-3. + </para> + + <orderedlist> + <listitem><para> + Encrypted passwords have been enabled by default in order to + interoperate better with out-of-the-box Windows client + installations. This does mean that either (a) a Samba account + must be created for each user, or (b) <quote>encrypt passwords = no</quote> + must be explicitly defined in &smb.conf;. + </para></listitem> + + <listitem><para> + Inclusion of new <smbconfoption name="security">ads</smbconfoption> option for integration + with an Active Directory domain using the native Windows Kerberos 5 and LDAP protocols. + </para></listitem> + </orderedlist> + + <para> + Samba-3 also includes the possibility of setting up chains + of authentication methods + (<smbconfoption name="auth methods"/>) and account + storage backends + (<smbconfoption name="passdb backend"/>). + Please refer to the &smb.conf; + man page and <link linkend="passdb">Account Information Databases</link>, for details. While both parameters assume sane default + values, it is likely that you will need to understand what the + values actually mean in order to ensure Samba operates correctly. + </para> + + <para> +<indexterm><primary>pdbedit</primary></indexterm> + Certain functions of the <command>smbpasswd</command> tool have been split between the + new <command>smbpasswd</command> utility, the <command>net</command> tool and the new <command>pdbedit</command> + utility. See the respective man pages for details. + </para> + + </sect2> + + <sect2> + <title>LDAP</title> + + <para> + This section outlines the new features effecting Samba/LDAP integration. + </para> + + <sect3> + <title>New Schema</title> + + <para> + A new object class (sambaSamAccount) has been introduced to replace + the old sambaAccount. This change aids us in the renaming of attributes + to prevent clashes with attributes from other vendors. There is a + conversion script (examples/LDAP/convertSambaAccount) to modify an LDIF + file to the new schema. + </para> + + <para> + Example: + </para> + <para><screen> + &prompt;ldapsearch .... -LLL -b "ou=people,dc=..." > old.ldif + &prompt;convertSambaAccount --sid <DOM SID> --input old.ldif --output new.ldif + </screen></para> + + <para> + The <DOM SID> can be obtained by running +<screen> +&prompt;<userinput>net getlocalsid <DOMAINNAME></userinput> +</screen> + on the Samba PDC as root. + </para> + + <para> + Under Samba-2.x the Domain SID can be obtained by executing: +<screen> +&prompt;<userinput>smbpasswd -S <DOMAINNAME></userinput> +</screen> + </para> + + <para> + The old sambaAccount schema may still be used by specifying the + <parameter>ldapsam_compat</parameter> passdb backend. However, the sambaAccount and + associated attributes have been moved to the historical section of + the schema file and must be uncommented before use if needed. + The Samba-2.2 object class declaration for a sambaAccount has not changed + in the Samba-3 samba.schema file. + </para> + + <para> + Other new object classes and their uses include: + </para> + + <itemizedlist> + <listitem><para> + sambaDomain &smbmdash; domain information used to allocate RIDs + for users and groups as necessary. The attributes are added + in <quote>ldap suffix</quote> directory entry automatically if + an idmap UID/GID range has been set and the <quote>ldapsam</quote> + passdb backend has been selected. + </para></listitem> + + <listitem><para> + sambaGroupMapping &smbmdash; an object representing the + relationship between a posixGroup and a Windows + group/SID. These entries are stored in the <quote>ldap + group suffix</quote> and managed by the <quote>net groupmap</quote> command. + </para></listitem> + + <listitem><para> + sambaUNIXIdPool &smbmdash; created in the <quote>ldap idmap suffix</quote> entry + automatically and contains the next available <quote>idmap UID</quote> and + <quote>idmap GID</quote>. + </para></listitem> + + <listitem><para> + sambaIdmapEntry &smbmdash; object storing a mapping between a + SID and a UNIX UID/GID. These objects are created by the + idmap_ldap module as needed. + </para></listitem> + </itemizedlist> + + </sect3> + + <sect3> + <title>New Suffix for Searching</title> + + <para> + The following new smb.conf parameters have been added to aid in directing + certain LDAP queries when <parameter>passdb backend = ldapsam://...</parameter> has been + specified. + </para> + + <itemizedlist> + <listitem><para>ldap suffix &smbmdash; used to search for user and computer accounts.</para></listitem> + <listitem><para>ldap user suffix &smbmdash; used to store user accounts.</para></listitem> + <listitem><para>ldap machine suffix &smbmdash; used to store Machine Trust Accounts.</para></listitem> + <listitem><para>ldap group suffix &smbmdash; location of posixGroup/sambaGroupMapping entries.</para></listitem> + <listitem><para>ldap idmap suffix &smbmdash; location of sambaIdmapEntry objects.</para></listitem> + </itemizedlist> + + <para> + If an <parameter>ldap suffix</parameter> is defined, it will be appended to all of the + remaining sub-suffix parameters. In this case, the order of the suffix + listings in smb.conf is important. Always place the <parameter>ldap suffix</parameter> first + in the list. + </para> + + <para> + Due to a limitation in Samba's &smb.conf; parsing, you should not surround + the DNs with quotation marks. + </para> + + </sect3> + + <sect3> + <title>IdMap LDAP Support</title> + + <para> + Samba-3 supports an ldap backend for the idmap subsystem. The + following options inform Samba that the idmap table should be + stored on the directory server onterose in the "ou=idmap,dc=quenya,dc=org" partition. + </para> + + <smbconfblock> + <smbconfsection name="[global]"/> + <member>...</member> + <smbconfoption name="idmap backend">ldap:ldap://onterose/</smbconfoption> + <smbconfoption name="ldap idmap suffix">ou=idmap,dc=quenya,dc=org</smbconfoption> + <smbconfoption name="idmap uid">40000-50000</smbconfoption> + <smbconfoption name="idmap gid">40000-50000</smbconfoption> + </smbconfblock> + + <para> + This configuration allows Winbind installations on multiple servers to + share a UID/GID number space, thus avoiding the interoperability problems + with NFS that were present in Samba-2.2. + </para> + + </sect3> + + </sect2> + +</sect1> + +</chapter> diff --git a/docs/Samba3-HOWTO/conventions.xml b/docs/Samba3-HOWTO/conventions.xml new file mode 100644 index 0000000000..d4bbde8f85 --- /dev/null +++ b/docs/Samba3-HOWTO/conventions.xml @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE sect1 PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> + + <sect1> + <title>Conventions Used</title> + + <para> + The following notation conventions are used throughout this book: + </para> + + <itemizedlist> + <listitem> + <para> + TOSHARG is used as an abbreviation for the book, <quote>The Official Samba-3 + HOWTO and Reference Guide,</quote> Editors: John H. Terpstra and Jelmer R. Vernooij, + Publisher: Prentice Hall, ISBN: 0131453556. + </para> + </listitem> + + <listitem> + <para> + Directories and filenames appear in mono-font. For example, + <filename>/etc/pam.conf</filename>. + </para> + </listitem> + + <listitem> + <para> + Executable names are bolded. For example, <command>smbd</command>. + </para> + </listitem> + + <listitem> + <para> + Menu items and buttons appear in bold. For example, click <guibutton>Next</guibutton>. + </para> + </listitem> + + <listitem> + <para> + Selecting a menu item is indicated as: + <menuchoice> + <guimenu>Start</guimenu> + <guimenuitem>Control Panel</guimenuitem> + <guimenuitem>Administrative Tools</guimenuitem> + <guimenuitem>Active Directory Users and Computers</guimenuitem> + </menuchoice> + </para> + </listitem> + </itemizedlist> + + </sect1> + diff --git a/docs/Samba3-HOWTO/hitlist-content b/docs/Samba3-HOWTO/hitlist-content new file mode 100644 index 0000000000..66f3b1a603 --- /dev/null +++ b/docs/Samba3-HOWTO/hitlist-content @@ -0,0 +1,14 @@ +- Broadcast messaging +- Profile Recovery +- smbfs/cifsfs +- Anti-Virus +- Krb5 TGT usage +- Static WINS entries +- Disabling Roaming Profiles +- BAD SID issues +- VPN +- incorporation in apache and squid (ntlm_auth) +- smbldap-tools +- kinit issues (you need to have kerberos updated in order to run win2k3, etc) +- pam_smb and why not to use it +- quotas diff --git a/docs/Samba3-HOWTO/images/.cvsignore b/docs/Samba3-HOWTO/images/.cvsignore new file mode 100644 index 0000000000..f7b5423899 --- /dev/null +++ b/docs/Samba3-HOWTO/images/.cvsignore @@ -0,0 +1 @@ +*.eps diff --git a/docs/Samba3-HOWTO/images/10small.png b/docs/Samba3-HOWTO/images/10small.png Binary files differnew file mode 100644 index 0000000000..56a9b0cd67 --- /dev/null +++ b/docs/Samba3-HOWTO/images/10small.png diff --git a/docs/Samba3-HOWTO/images/11small.png b/docs/Samba3-HOWTO/images/11small.png Binary files differnew file mode 100644 index 0000000000..18f5d9e4dd --- /dev/null +++ b/docs/Samba3-HOWTO/images/11small.png diff --git a/docs/Samba3-HOWTO/images/12small.png b/docs/Samba3-HOWTO/images/12small.png Binary files differnew file mode 100644 index 0000000000..5bdf809c1b --- /dev/null +++ b/docs/Samba3-HOWTO/images/12small.png diff --git a/docs/Samba3-HOWTO/images/13small.png b/docs/Samba3-HOWTO/images/13small.png Binary files differnew file mode 100644 index 0000000000..536b2fc2c2 --- /dev/null +++ b/docs/Samba3-HOWTO/images/13small.png diff --git a/docs/Samba3-HOWTO/images/14small.png b/docs/Samba3-HOWTO/images/14small.png Binary files differnew file mode 100644 index 0000000000..89054249c0 --- /dev/null +++ b/docs/Samba3-HOWTO/images/14small.png diff --git a/docs/Samba3-HOWTO/images/1small.png b/docs/Samba3-HOWTO/images/1small.png Binary files differnew file mode 100644 index 0000000000..c4905163c9 --- /dev/null +++ b/docs/Samba3-HOWTO/images/1small.png diff --git a/docs/Samba3-HOWTO/images/2small.png b/docs/Samba3-HOWTO/images/2small.png Binary files differnew file mode 100644 index 0000000000..5fd9071349 --- /dev/null +++ b/docs/Samba3-HOWTO/images/2small.png diff --git a/docs/Samba3-HOWTO/images/3small.png b/docs/Samba3-HOWTO/images/3small.png Binary files differnew file mode 100644 index 0000000000..22a39bae52 --- /dev/null +++ b/docs/Samba3-HOWTO/images/3small.png diff --git a/docs/Samba3-HOWTO/images/4small.png b/docs/Samba3-HOWTO/images/4small.png Binary files differnew file mode 100644 index 0000000000..6b7f1b1fd4 --- /dev/null +++ b/docs/Samba3-HOWTO/images/4small.png diff --git a/docs/Samba3-HOWTO/images/5small.png b/docs/Samba3-HOWTO/images/5small.png Binary files differnew file mode 100644 index 0000000000..b23e1fc2c7 --- /dev/null +++ b/docs/Samba3-HOWTO/images/5small.png diff --git a/docs/Samba3-HOWTO/images/6small.png b/docs/Samba3-HOWTO/images/6small.png Binary files differnew file mode 100644 index 0000000000..35a646d826 --- /dev/null +++ b/docs/Samba3-HOWTO/images/6small.png diff --git a/docs/Samba3-HOWTO/images/7small.png b/docs/Samba3-HOWTO/images/7small.png Binary files differnew file mode 100644 index 0000000000..d182677510 --- /dev/null +++ b/docs/Samba3-HOWTO/images/7small.png diff --git a/docs/Samba3-HOWTO/images/8small.png b/docs/Samba3-HOWTO/images/8small.png Binary files differnew file mode 100644 index 0000000000..08aca66386 --- /dev/null +++ b/docs/Samba3-HOWTO/images/8small.png diff --git a/docs/Samba3-HOWTO/images/9small.png b/docs/Samba3-HOWTO/images/9small.png Binary files differnew file mode 100644 index 0000000000..90c2cde327 --- /dev/null +++ b/docs/Samba3-HOWTO/images/9small.png diff --git a/docs/Samba3-HOWTO/images/WME001.png b/docs/Samba3-HOWTO/images/WME001.png Binary files differnew file mode 100644 index 0000000000..c5db7570bc --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME001.png diff --git a/docs/Samba3-HOWTO/images/WME002.png b/docs/Samba3-HOWTO/images/WME002.png Binary files differnew file mode 100644 index 0000000000..641f2179a0 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME002.png diff --git a/docs/Samba3-HOWTO/images/WME003.png b/docs/Samba3-HOWTO/images/WME003.png Binary files differnew file mode 100644 index 0000000000..073c58eddd --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME003.png diff --git a/docs/Samba3-HOWTO/images/WME004.png b/docs/Samba3-HOWTO/images/WME004.png Binary files differnew file mode 100644 index 0000000000..5053adeeec --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME004.png diff --git a/docs/Samba3-HOWTO/images/WME005.png b/docs/Samba3-HOWTO/images/WME005.png Binary files differnew file mode 100644 index 0000000000..5e4e72e498 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME005.png diff --git a/docs/Samba3-HOWTO/images/WME006.png b/docs/Samba3-HOWTO/images/WME006.png Binary files differnew file mode 100644 index 0000000000..cbd3183696 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME006.png diff --git a/docs/Samba3-HOWTO/images/WME007.png b/docs/Samba3-HOWTO/images/WME007.png Binary files differnew file mode 100644 index 0000000000..e0a113b080 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME007.png diff --git a/docs/Samba3-HOWTO/images/WME008.png b/docs/Samba3-HOWTO/images/WME008.png Binary files differnew file mode 100644 index 0000000000..b03a7853b4 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME008.png diff --git a/docs/Samba3-HOWTO/images/WME009.png b/docs/Samba3-HOWTO/images/WME009.png Binary files differnew file mode 100644 index 0000000000..f851876cee --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME009.png diff --git a/docs/Samba3-HOWTO/images/WME010.png b/docs/Samba3-HOWTO/images/WME010.png Binary files differnew file mode 100644 index 0000000000..589be02b22 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME010.png diff --git a/docs/Samba3-HOWTO/images/WME011.png b/docs/Samba3-HOWTO/images/WME011.png Binary files differnew file mode 100644 index 0000000000..f15399b4a2 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME011.png diff --git a/docs/Samba3-HOWTO/images/WME012.png b/docs/Samba3-HOWTO/images/WME012.png Binary files differnew file mode 100644 index 0000000000..d2e46212f6 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME012.png diff --git a/docs/Samba3-HOWTO/images/WME013.png b/docs/Samba3-HOWTO/images/WME013.png Binary files differnew file mode 100644 index 0000000000..0f0a70d062 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME013.png diff --git a/docs/Samba3-HOWTO/images/WME014.png b/docs/Samba3-HOWTO/images/WME014.png Binary files differnew file mode 100644 index 0000000000..73f1dde37c --- /dev/null +++ b/docs/Samba3-HOWTO/images/WME014.png diff --git a/docs/Samba3-HOWTO/images/WXPP002.png b/docs/Samba3-HOWTO/images/WXPP002.png Binary files differnew file mode 100644 index 0000000000..b87001bca4 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WXPP002.png diff --git a/docs/Samba3-HOWTO/images/WXPP003.png b/docs/Samba3-HOWTO/images/WXPP003.png Binary files differnew file mode 100644 index 0000000000..a60d6c413a --- /dev/null +++ b/docs/Samba3-HOWTO/images/WXPP003.png diff --git a/docs/Samba3-HOWTO/images/WXPP005.png b/docs/Samba3-HOWTO/images/WXPP005.png Binary files differnew file mode 100644 index 0000000000..4aa091767b --- /dev/null +++ b/docs/Samba3-HOWTO/images/WXPP005.png diff --git a/docs/Samba3-HOWTO/images/WXPP009.png b/docs/Samba3-HOWTO/images/WXPP009.png Binary files differnew file mode 100644 index 0000000000..b540e238b8 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WXPP009.png diff --git a/docs/Samba3-HOWTO/images/WXPP014.png b/docs/Samba3-HOWTO/images/WXPP014.png Binary files differnew file mode 100644 index 0000000000..f1e02d3ce3 --- /dev/null +++ b/docs/Samba3-HOWTO/images/WXPP014.png diff --git a/docs/Samba3-HOWTO/images/a_small.png b/docs/Samba3-HOWTO/images/a_small.png Binary files differnew file mode 100644 index 0000000000..a6622ef6cf --- /dev/null +++ b/docs/Samba3-HOWTO/images/a_small.png diff --git a/docs/Samba3-HOWTO/images/access1.dia b/docs/Samba3-HOWTO/images/access1.dia Binary files differnew file mode 100644 index 0000000000..7fd2673800 --- /dev/null +++ b/docs/Samba3-HOWTO/images/access1.dia diff --git a/docs/Samba3-HOWTO/images/browsing1.dia b/docs/Samba3-HOWTO/images/browsing1.dia Binary files differnew file mode 100644 index 0000000000..8235df45f6 --- /dev/null +++ b/docs/Samba3-HOWTO/images/browsing1.dia diff --git a/docs/Samba3-HOWTO/images/cups1.dia b/docs/Samba3-HOWTO/images/cups1.dia Binary files differnew file mode 100644 index 0000000000..e4cd3b1239 --- /dev/null +++ b/docs/Samba3-HOWTO/images/cups1.dia diff --git a/docs/Samba3-HOWTO/images/cups2.dia b/docs/Samba3-HOWTO/images/cups2.dia Binary files differnew file mode 100644 index 0000000000..9dfb60f335 --- /dev/null +++ b/docs/Samba3-HOWTO/images/cups2.dia diff --git a/docs/Samba3-HOWTO/images/domain.dia b/docs/Samba3-HOWTO/images/domain.dia Binary files differnew file mode 100644 index 0000000000..a994d423e2 --- /dev/null +++ b/docs/Samba3-HOWTO/images/domain.dia diff --git a/docs/Samba3-HOWTO/images/ethereal1.png b/docs/Samba3-HOWTO/images/ethereal1.png Binary files differnew file mode 100644 index 0000000000..c8655389d0 --- /dev/null +++ b/docs/Samba3-HOWTO/images/ethereal1.png diff --git a/docs/Samba3-HOWTO/images/ethereal2.png b/docs/Samba3-HOWTO/images/ethereal2.png Binary files differnew file mode 100644 index 0000000000..f366772d3b --- /dev/null +++ b/docs/Samba3-HOWTO/images/ethereal2.png diff --git a/docs/Samba3-HOWTO/images/idmap-gid2sid.dia b/docs/Samba3-HOWTO/images/idmap-gid2sid.dia Binary files differnew file mode 100644 index 0000000000..b3b1d88c50 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap-gid2sid.dia diff --git a/docs/Samba3-HOWTO/images/idmap-groups.dia b/docs/Samba3-HOWTO/images/idmap-groups.dia Binary files differnew file mode 100644 index 0000000000..04da158c53 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap-groups.dia diff --git a/docs/Samba3-HOWTO/images/idmap-sid2gid.dia b/docs/Samba3-HOWTO/images/idmap-sid2gid.dia Binary files differnew file mode 100644 index 0000000000..e6e5107698 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap-sid2gid.dia diff --git a/docs/Samba3-HOWTO/images/idmap-sid2uid.dia b/docs/Samba3-HOWTO/images/idmap-sid2uid.dia Binary files differnew file mode 100644 index 0000000000..91e00530a6 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap-sid2uid.dia diff --git a/docs/Samba3-HOWTO/images/idmap-store-gid2sid.dia b/docs/Samba3-HOWTO/images/idmap-store-gid2sid.dia Binary files differnew file mode 100644 index 0000000000..957613b6f3 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap-store-gid2sid.dia diff --git a/docs/Samba3-HOWTO/images/idmap-uid2sid.dia b/docs/Samba3-HOWTO/images/idmap-uid2sid.dia Binary files differnew file mode 100644 index 0000000000..de6ccaacb3 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap-uid2sid.dia diff --git a/docs/Samba3-HOWTO/images/idmap.dia b/docs/Samba3-HOWTO/images/idmap.dia Binary files differnew file mode 100644 index 0000000000..555933978b --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap.dia diff --git a/docs/Samba3-HOWTO/images/idmap_winbind_no_loop.png b/docs/Samba3-HOWTO/images/idmap_winbind_no_loop.png Binary files differnew file mode 100644 index 0000000000..5393f6a192 --- /dev/null +++ b/docs/Samba3-HOWTO/images/idmap_winbind_no_loop.png diff --git a/docs/Samba3-HOWTO/images/pdftoepsonusb.dia b/docs/Samba3-HOWTO/images/pdftoepsonusb.dia Binary files differnew file mode 100644 index 0000000000..2f846ee8d4 --- /dev/null +++ b/docs/Samba3-HOWTO/images/pdftoepsonusb.dia diff --git a/docs/Samba3-HOWTO/images/pdftosocket.dia b/docs/Samba3-HOWTO/images/pdftosocket.dia Binary files differnew file mode 100644 index 0000000000..53b6b7117c --- /dev/null +++ b/docs/Samba3-HOWTO/images/pdftosocket.dia diff --git a/docs/Samba3-HOWTO/images/trusts1.dia b/docs/Samba3-HOWTO/images/trusts1.dia Binary files differnew file mode 100644 index 0000000000..95cbbaa42f --- /dev/null +++ b/docs/Samba3-HOWTO/images/trusts1.dia diff --git a/docs/Samba3-HOWTO/images/w2kp001.png b/docs/Samba3-HOWTO/images/w2kp001.png Binary files differnew file mode 100644 index 0000000000..43adf23463 --- /dev/null +++ b/docs/Samba3-HOWTO/images/w2kp001.png diff --git a/docs/Samba3-HOWTO/images/w2kp002.png b/docs/Samba3-HOWTO/images/w2kp002.png Binary files differnew file mode 100644 index 0000000000..13bb029f53 --- /dev/null +++ b/docs/Samba3-HOWTO/images/w2kp002.png diff --git a/docs/Samba3-HOWTO/images/w2kp003.png b/docs/Samba3-HOWTO/images/w2kp003.png Binary files differnew file mode 100644 index 0000000000..c7b779900e --- /dev/null +++ b/docs/Samba3-HOWTO/images/w2kp003.png diff --git a/docs/Samba3-HOWTO/images/w2kp004.png b/docs/Samba3-HOWTO/images/w2kp004.png Binary files differnew file mode 100644 index 0000000000..d0e005a36e --- /dev/null +++ b/docs/Samba3-HOWTO/images/w2kp004.png diff --git a/docs/Samba3-HOWTO/images/w2kp005.png b/docs/Samba3-HOWTO/images/w2kp005.png Binary files differnew file mode 100644 index 0000000000..a729b40cd7 --- /dev/null +++ b/docs/Samba3-HOWTO/images/w2kp005.png diff --git a/docs/Samba3-HOWTO/images/w2kp006.png b/docs/Samba3-HOWTO/images/w2kp006.png Binary files differnew file mode 100644 index 0000000000..ea96db055a --- /dev/null +++ b/docs/Samba3-HOWTO/images/w2kp006.png diff --git a/docs/Samba3-HOWTO/images/wxpp001.png b/docs/Samba3-HOWTO/images/wxpp001.png Binary files differnew file mode 100644 index 0000000000..2e689a17e2 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp001.png diff --git a/docs/Samba3-HOWTO/images/wxpp004.png b/docs/Samba3-HOWTO/images/wxpp004.png Binary files differnew file mode 100644 index 0000000000..656f67942e --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp004.png diff --git a/docs/Samba3-HOWTO/images/wxpp006.png b/docs/Samba3-HOWTO/images/wxpp006.png Binary files differnew file mode 100644 index 0000000000..a20b3ed583 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp006.png diff --git a/docs/Samba3-HOWTO/images/wxpp007.png b/docs/Samba3-HOWTO/images/wxpp007.png Binary files differnew file mode 100644 index 0000000000..cf41352220 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp007.png diff --git a/docs/Samba3-HOWTO/images/wxpp008.png b/docs/Samba3-HOWTO/images/wxpp008.png Binary files differnew file mode 100644 index 0000000000..9958c7c873 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp008.png diff --git a/docs/Samba3-HOWTO/images/wxpp010.png b/docs/Samba3-HOWTO/images/wxpp010.png Binary files differnew file mode 100644 index 0000000000..068a0dfc73 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp010.png diff --git a/docs/Samba3-HOWTO/images/wxpp011.png b/docs/Samba3-HOWTO/images/wxpp011.png Binary files differnew file mode 100644 index 0000000000..0cf88c04a6 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp011.png diff --git a/docs/Samba3-HOWTO/images/wxpp012.png b/docs/Samba3-HOWTO/images/wxpp012.png Binary files differnew file mode 100644 index 0000000000..d89f3b5d31 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp012.png diff --git a/docs/Samba3-HOWTO/images/wxpp013.png b/docs/Samba3-HOWTO/images/wxpp013.png Binary files differnew file mode 100644 index 0000000000..451240ee38 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp013.png diff --git a/docs/Samba3-HOWTO/images/wxpp015.png b/docs/Samba3-HOWTO/images/wxpp015.png Binary files differnew file mode 100644 index 0000000000..12fe2f31b2 --- /dev/null +++ b/docs/Samba3-HOWTO/images/wxpp015.png diff --git a/docs/Samba3-HOWTO/index.xml b/docs/Samba3-HOWTO/index.xml new file mode 100644 index 0000000000..7ccbb834d3 --- /dev/null +++ b/docs/Samba3-HOWTO/index.xml @@ -0,0 +1,164 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE book PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> + +<book id="Samba-HOWTO-Collection" + xmlns:xi="http://www.w3.org/2003/XInclude"> +<title>The Official Samba-3 HOWTO and Reference Guide</title> + +<bookinfo> + <authorgroup> + <editor>&person.jelmer;</editor> + <editor>&person.jht;</editor> + <editor>&person.jerry;</editor> + </authorgroup> + <pubdate><?latex \today ?></pubdate> +</bookinfo> + + <?latex \setcounter{page}{5} ?> + + <xi:include href="../Samba-HOWTO-Collection-attributions.xml"> + <xi:fallback/> + </xi:include> + + <?latex \cleardoublepage ?> + + <xi:include href="TOSHARG-preface.xml"/> + + <?latex \cleardoublepage ?> + + <xi:include href="TOSHARG-foreword-tridge.xml"/> + + <?latex \cleardoublepage ?> + +<!-- Contents --> + <toc/> + + <?latex \cleardoublepage ?> + + <lot/> + + <xi:include href="TOSHARG-IntroSMB.xml"/> + +<!-- Chapters --> +<part id="introduction"> +<title>General Installation</title> +<?latex \pagenumbering{arabic} ?> + +<partintro> +<title>Preparing Samba for Configuration</title> + +<para> +This section of the Samba-HOWTO-Collection contains general info on how to install Samba +and how to configure the parts of Samba you will most likely need. +PLEASE read this. +</para> + +</partintro> + + <xi:include href="TOSHARG-Install.xml"/> + <xi:include href="TOSHARG-FastStart.xml"/> + +</part> + +<part id="type"> +<title>Server Configuration Basics</title> +<partintro> +<title>First Steps in Server Configuration</title> + +<para> +Samba can operate in various modes within SMB networks. This HOWTO section contains information on +configuring Samba to function as the type of server your network requires. Please read this +section carefully. +</para> + +</partintro> + + <xi:include href="TOSHARG-ServerType.xml"/> + <xi:include href="TOSHARG-PDC.xml"/> + <xi:include href="TOSHARG-BDC.xml"/> + <xi:include href="TOSHARG-DomainMember.xml"/> + <xi:include href="TOSHARG-StandAloneServer.xml"/> + <xi:include href="TOSHARG-WindowsClientConfig.xml"/> + +</part> + +<part id="optional"> +<title>Advanced Configuration</title> +<partintro> +<title>Valuable Nuts and Bolts Information</title> + +<para> +Samba has several features that you might want or might not want to use. +The chapters in this part each cover specific Samba features. +</para> + +</partintro> + + <xi:include href="TOSHARG-NetworkBrowsing.xml"/> + <xi:include href="TOSHARG-Passdb.xml"/> + <xi:include href="TOSHARG-Group-Mapping.xml"/> + <xi:include href="TOSHARG-TheNetCommand.xml"/> + <xi:include href="TOSHARG-IDMAP.xml"/> + <xi:include href="TOSHARG-RightsAndPriviliges.xml"/> + <xi:include href="TOSHARG-AccessControls.xml"/> + <xi:include href="TOSHARG-locking.xml"/> + <xi:include href="TOSHARG-Securing.xml"/> + <xi:include href="TOSHARG-InterdomainTrusts.xml"/> + <xi:include href="TOSHARG-msdfs.xml"/> + <xi:include href="TOSHARG-Printing.xml"/> + <xi:include href="TOSHARG-CUPS-printing.xml"/> + <xi:include href="TOSHARG-VFS.xml"/> + <xi:include href="TOSHARG-Winbind.xml"/> + <xi:include href="TOSHARG-AdvancedNetworkAdmin.xml"/> + <xi:include href="TOSHARG-PolicyMgmt.xml"/> + <xi:include href="TOSHARG-ProfileMgmt.xml"/> + <xi:include href="TOSHARG-PAM.xml"/> + <xi:include href="TOSHARG-Integrating-with-Windows.xml"/> + <xi:include href="TOSHARG-Unicode.xml"/> + <xi:include href="TOSHARG-Backup.xml"/> + <xi:include href="TOSHARG-HighAvailability.xml"/> + <xi:include href="TOSHARG-LargeFile.xml"/> + <!-- <xi:include href="TOSHARG-SecureLDAP.xml"/> --> + +</part> + +<part id="migration"> +<title>Migration and Updating</title> + + <xi:include href="TOSHARG-upgrading-to-3.0.xml"/> + <xi:include href="TOSHARG-NT4Migration.xml"/> + <xi:include href="TOSHARG-SWAT.xml"/> + +</part> + +<part id="troubleshooting"> +<title>Troubleshooting</title> + + <xi:include href="TOSHARG-Diagnosis.xml"/> + <xi:include href="TOSHARG-Problems.xml"/> + <xi:include href="TOSHARG-Bugs.xml"/> + +</part> + +<part id="Appendix"> +<title>Appendixes</title> + + <xi:include href="TOSHARG-Compiling.xml"/> + <xi:include href="TOSHARG-Portability.xml"/> + <xi:include href="TOSHARG-Other-Clients.xml"/> + <xi:include href="TOSHARG-Speed.xml"/> + <xi:include href="TOSHARG-DNS-DHCP-Configuration.xml"/> + +<!-- Comment out the following line to include the manpages. + *Please* do not commit with the line below enabled! --> + <!-- <xi:include href="manpages.xml"/> --> + <xi:include href="http://www.gnu.org/licenses/gpl.xml"/> + + <xi:include href="TOSHARG-glossary.xml"/> + + <?latex \chaptermark{Subject index} ?> + + <index/> +</part> + +</book> diff --git a/docs/Samba3-HOWTO/manpages.xml b/docs/Samba3-HOWTO/manpages.xml new file mode 100644 index 0000000000..69801c44ec --- /dev/null +++ b/docs/Samba3-HOWTO/manpages.xml @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE reference PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<reference id="manuals" xmlns:xi="http://www.w3.org/2003/XInclude"> <title>Manual pages</title> + + <para>This appendix contains most of the manual pages from the official Samba distribution. All manual pages have been written by members of + <ulink url="http://samba.org/samba/team.html">the Samba Team</ulink>.</para> + + <xi:include href="../manpages-3/net.8.xml"/> + <xi:include href="../manpages-3/nmbd.8.xml"/> + <xi:include href="../manpages-3/nmblookup.1.xml"/> + <xi:include href="../manpages-3/pdbedit.8.xml"/> + <xi:include href="../manpages-3/profiles.1.xml"/> + <xi:include href="../manpages-3/rpcclient.1.xml"/> + <xi:include href="../manpages-3/smbcacls.1.xml"/> + <xi:include href="../manpages-3/smbclient.1.xml"/> + <xi:include href="../manpages-3/smb.conf.5.xml"/> + <xi:include href="../manpages-3/smbcquotas.1.xml"/> + <xi:include href="../manpages-3/smbd.8.xml"/> + <xi:include href="../manpages-3/smbpasswd.5.xml"/> + <xi:include href="../manpages-3/smbpasswd.8.xml"/> + <xi:include href="../manpages-3/smbstatus.1.xml"/> + <xi:include href="../manpages-3/smbtree.1.xml"/> + <xi:include href="../manpages-3/tdbbackup.8.xml"/> + <xi:include href="../manpages-3/tdbdump.8.xml"/> + <xi:include href="../manpages-3/testparm.1.xml"/> + <xi:include href="../manpages-3/wbinfo.1.xml"/> + <xi:include href="../manpages-3/winbindd.8.xml"/> + +</reference> + + |
