summaryrefslogtreecommitdiff
path: root/docs-xml/Samba3-HOWTO
diff options
context:
space:
mode:
authorGerald W. Carter <jerry@samba.org>2008-04-22 10:09:40 -0500
committerGerald W. Carter <jerry@samba.org>2008-04-23 08:47:48 -0500
commit8f8a9f01909ba29e2b781310baeeaaddc3f15f0d (patch)
tree90c6b720ad3a7bc815245c0ef28820424f89d658 /docs-xml/Samba3-HOWTO
parent197238246389c40edc60c6630d18d6913086e630 (diff)
downloadsamba-8f8a9f01909ba29e2b781310baeeaaddc3f15f0d.tar.gz
samba-8f8a9f01909ba29e2b781310baeeaaddc3f15f0d.tar.bz2
samba-8f8a9f01909ba29e2b781310baeeaaddc3f15f0d.zip
Moving docs tree to docs-xml to make room for generated docs in the release tarball.
(This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14)
Diffstat (limited to 'docs-xml/Samba3-HOWTO')
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml1710
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml485
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-BDC.xml862
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Backup.xml241
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Bugs.xml287
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-CUPS-printing.xml5237
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-ChangeNotes.xml244
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Compiling.xml590
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml392
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml346
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Diagnosis.xml603
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-DomainMember.xml1419
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-FastStart.xml1306
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Further-Resources.xml174
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Group-Mapping.xml920
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-HighAvailability.xml500
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml1124
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Install.xml702
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml745
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml602
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-IntroSMB.xml224
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-LargeFile.xml89
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-NT4Migration.xml631
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml2218
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Other-Clients.xml351
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-PAM.xml1013
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-PDC.xml1409
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Passdb.xml2675
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml607
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Portability.xml270
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Printing.xml3273
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Problems.xml329
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml1320
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml600
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml640
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml405
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Securing.xml448
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-ServerType.xml833
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Speed.xml327
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-StandAloneServer.xml341
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Support.xml163
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-TheNetCommand.xml1916
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Unicode.xml571
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-VFS.xml949
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-Winbind.xml1479
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml599
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-foreword-cargill.xml79
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-foreword-tridge.xml48
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-glossary.xml254
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-inside-cover.xml43
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-locking.xml1140
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml176
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-preface.xml61
-rw-r--r--docs-xml/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml871
-rw-r--r--docs-xml/Samba3-HOWTO/conventions.xml60
-rw-r--r--docs-xml/Samba3-HOWTO/gpl-3.0.xml836
-rw-r--r--docs-xml/Samba3-HOWTO/hitlist-content14
-rw-r--r--docs-xml/Samba3-HOWTO/images/10small.pngbin0 -> 46666 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/11small.pngbin0 -> 27817 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/12small.pngbin0 -> 29508 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/13small.pngbin0 -> 30506 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/14small.pngbin0 -> 56042 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/1small.pngbin0 -> 20739 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/2small.pngbin0 -> 15016 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/3small.pngbin0 -> 15785 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/4small.pngbin0 -> 22370 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/5small.pngbin0 -> 27857 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/6small.pngbin0 -> 32612 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/7small.pngbin0 -> 29350 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/8small.pngbin0 -> 45259 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/9small.pngbin0 -> 30509 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME001.pngbin0 -> 8576 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME002.pngbin0 -> 6913 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME003.pngbin0 -> 6448 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME004.pngbin0 -> 8864 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME005.pngbin0 -> 6421 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME006.pngbin0 -> 5999 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME007.pngbin0 -> 5855 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME008.pngbin0 -> 2337 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME009.pngbin0 -> 8863 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME010.pngbin0 -> 6454 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME011.pngbin0 -> 5810 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME012.pngbin0 -> 6454 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME013.pngbin0 -> 5844 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WME014.pngbin0 -> 5802 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WXPP002.pngbin0 -> 25711 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WXPP003.pngbin0 -> 18079 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WXPP005.pngbin0 -> 15378 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WXPP009.pngbin0 -> 18976 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/WXPP014.pngbin0 -> 28767 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/a_small.pngbin0 -> 115304 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/access1.svg308
-rw-r--r--docs-xml/Samba3-HOWTO/images/browsing1.svg2025
-rw-r--r--docs-xml/Samba3-HOWTO/images/cups1.svg274
-rw-r--r--docs-xml/Samba3-HOWTO/images/cups2.svg320
-rw-r--r--docs-xml/Samba3-HOWTO/images/domain.svg2288
-rw-r--r--docs-xml/Samba3-HOWTO/images/ethereal1.pngbin0 -> 18517 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/ethereal2.pngbin0 -> 38069 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap-gid2sid.svg277
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap-groups.svg129
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap-sid2gid.svg277
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap-sid2uid.svg365
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap-store-gid2sid.svg122
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap-uid2sid.svg365
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap.svg119
-rw-r--r--docs-xml/Samba3-HOWTO/images/idmap_winbind_no_loop.pngbin0 -> 9172 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/pdftoepsonusb.svg156
-rw-r--r--docs-xml/Samba3-HOWTO/images/pdftosocket.svg94
-rw-r--r--docs-xml/Samba3-HOWTO/images/trusts1.svg792
-rw-r--r--docs-xml/Samba3-HOWTO/images/w2kp001.pngbin0 -> 10891 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/w2kp002.pngbin0 -> 11966 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/w2kp003.pngbin0 -> 8892 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/w2kp004.pngbin0 -> 12127 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/w2kp005.pngbin0 -> 9951 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/w2kp006.pngbin0 -> 9244 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp001.pngbin0 -> 31712 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp004.pngbin0 -> 29694 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp006.pngbin0 -> 12651 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp007.pngbin0 -> 12781 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp008.pngbin0 -> 19550 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp010.pngbin0 -> 19725 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp011.pngbin0 -> 8579 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp012.pngbin0 -> 8918 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp013.pngbin0 -> 30107 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/images/wxpp015.pngbin0 -> 9713 bytes
-rw-r--r--docs-xml/Samba3-HOWTO/index.xml237
-rw-r--r--docs-xml/Samba3-HOWTO/manpages.xml73
127 files changed, 53972 insertions, 0 deletions
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml b/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml
new file mode 100644
index 0000000000..48f439dead
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-AccessControls.xml
@@ -0,0 +1,1710 @@
+<?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>
+<indexterm><primary>share</primary></indexterm>
+<indexterm><primary>network access controls</primary></indexterm>
+<indexterm><primary>unauthorized access</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>
+<indexterm><primary>file access permissions</primary></indexterm>
+<indexterm><primary>directory access permissions</primary></indexterm>
+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>
+<indexterm><primary>bridge</primary></indexterm>
+<indexterm><primary>directory controls</primary></indexterm>
+<indexterm><primary>directory permissions</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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>
+<indexterm><primary>Access Control List</primary></indexterm>
+<indexterm><primary>commercial Linux products</primary></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>
+<indexterm><primary>network administrator</primary></indexterm>
+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>
+<indexterm><primary>interoperability</primary></indexterm>
+<indexterm><primary>data interchange</primary></indexterm>
+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 much 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>
+<indexterm><primary>UNIX file system access controls</primary></indexterm>
+<indexterm><primary>access controls</primary></indexterm>
+<indexterm><primary>permissions and controls</primary></indexterm>
+ 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>
+<indexterm><primary>share settings</primary></indexterm>
+ 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>
+<indexterm><primary>ACLs on shares</primary></indexterm>
+ Just as it is possible in MS Windows NT to set ACLs on shares
+ themselves, so it is possible to do 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>
+<indexterm><primary>native ACLs</primary></indexterm>
+ 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 support. 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 overrides,
+ but for the greater part we 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 MS 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 file 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 because 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 uppercase 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 namespace 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. The Windows client will ask for a case-insensitive file
+ lookup, and that is the reason for which Samba must offer a consistent selection in the
+ event that the UNIX directory contains multiple files that would match a case insensitive
+ file listing.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Directory Separators</term>
+ <listitem><para>
+ <indexterm><primary>Directory Separators</primary></indexterm>
+ MS Windows and DOS use 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 as 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
+ startup files for various UNIX applications, or they may be files that contain
+ startup 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>Shortcuts</primary></indexterm>
+ MS Windows make use of <emphasis>links and shortcuts</emphasis> 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>
+<indexterm><primary>create</primary></indexterm>
+<indexterm><primary>delete</primary></indexterm>
+<indexterm><primary>rename</primary></indexterm>
+ There are three basic operations for managing directories: <command>create</command>, <command>delete</command>,
+ <command>rename</command>. <link linkend="TOSH-Accesstbl">Managing Directories with UNIX and
+ Windows</link> compares the commands in Windows and UNIX that implement these operations.
+ </para>
+
+ <table frame="all" id="TOSH-Accesstbl">
+ <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>
+
+ </sect2>
+
+ <sect2>
+ <title>File and Directory Access Control</title>
+
+ <para>
+ <indexterm><primary>ACLs</primary><secondary>File System</secondary></indexterm>
+<indexterm><primary>POSIX ACLs</primary></indexterm>
+<indexterm><primary>EAs</primary></indexterm>
+ The network administrator is strongly advised to read basic UNIX 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 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 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 is shown in <link linkend="access1">Overview of UNIX permissions
+ field</link>.
+ </para>
+
+ <figure id="access1">
+ <title>Overview of UNIX permissions field.</title>
+ <imagefile scale="40">access1</imagefile>
+ </figure>
+
+ <para>
+ Any bit flag may be unset. An unset bit flag is the equivalent of "cannot" and is represented
+ as a <quote>-</quote> character (see <link linkend="access2"/>)
+<indexterm><primary>read</primary></indexterm>
+<indexterm><primary>write</primary></indexterm>
+<indexterm><primary>execute</primary></indexterm>
+<indexterm><primary>user</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>other</primary></indexterm>
+ </para>
+
+<example id="access2">
+<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>
+<indexterm><primary>character device</primary></indexterm>
+<indexterm><primary>block device</primary></indexterm>
+<indexterm><primary>pipe device</primary></indexterm>
+<indexterm><primary>UNIX Domain Socket</primary></indexterm>
+ Additional possibilities in the [type] field are c = character device, b = block device, p = pipe device,
+ s = UNIX Domain Socket.
+ </para>
+
+ <para>
+<indexterm><primary>read</primary></indexterm>
+<indexterm><primary>write</primary></indexterm>
+<indexterm><primary>execute</primary></indexterm>
+<indexterm><primary>SGID</primary></indexterm>
+<indexterm><primary>SUID</primary></indexterm>
+ 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 (SUID) or group ID (SGID) on execution (s), sticky (t).
+ </para>
+
+ <para>
+<indexterm><primary>sticky bit</primary></indexterm>
+<indexterm><primary>unlinked</primary></indexterm>
+<indexterm><primary>/tmp</primary></indexterm>
+<indexterm><primary>world-writable</primary></indexterm>
+ 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>
+<indexterm><primary>write</primary></indexterm>
+<indexterm><primary>read</primary></indexterm>
+<indexterm><primary>setting up directories</primary></indexterm>
+<indexterm><primary>set user id</primary><see>SUID</see></indexterm>
+<indexterm><primary>set group id</primary><see>SGID</see></indexterm>
+ 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>, 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>
+<indexterm><primary>protect files</primary></indexterm>
+<indexterm><primary>protect directories</primary></indexterm>
+<indexterm><primary>access controls</primary></indexterm>
+<indexterm><primary>capability to delete</primary></indexterm>
+ 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. Anyone who has write permission on the
+ directory that contains a file and has write permission for it has the capability to delete it.
+ </para>
+
+ <para>
+<indexterm><primary>directory permissions</primary></indexterm>
+<indexterm><primary>delete a file</primary></indexterm>
+<indexterm><primary>write access</primary></indexterm>
+ 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 has write access, even if that user does not own the file.
+ </para>
+
+ <para>
+<indexterm><primary>file system capabilities</primary></indexterm>
+<indexterm><primary>inheritance</primary></indexterm>
+<indexterm><primary>POSIX ACLs</primary></indexterm>
+<indexterm><primary>extended attributes</primary></indexterm>
+ 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 "best fit" translation to POSIX ACLs. Some UNIX file systems do, however support, a feature known
+ as extended attributes. Only the Windows concept of <emphasis>inheritance</emphasis> is implemented by Samba through
+ the appropriate extended attribute.
+ </para>
+
+ <para>
+<indexterm><primary>extended attributes</primary></indexterm>
+<indexterm><primary>immutible</primary></indexterm>
+<indexterm><primary>chattr</primary></indexterm>
+<indexterm><primary>CAP_LINUX_IMMUTABLE</primary></indexterm>
+ 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>
+ <title>Test for File Immutibility Support</title>
+
+ <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; chattr +i `filename'
+</screen>
+ </para></step>
+
+ <step><para>
+ Login as the user who owns the file (not root) and 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 operating systems and file system types that support the immutible bit, it is possible to create directories
+ that cannot 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
+ be 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 affect 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
+ force 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 use 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"/> parameter may be useful.
+ </para>
+
+ <para>
+ As always, it is highly advisable to use the easiest 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 or she 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">User and Group Based Controls</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 superuser (root).
+ Users 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 username 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>
+ Directory permission-based controls, if misused, can result in considerable difficulty in diagnosing the causes of
+ misconfiguration. Use them sparingly and carefully. By gradually introducing each, one at a time, 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">File and Directory Permission Based Controls</link> for information
+ regarding the parameters that may be used to set 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. Unwritable 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 ACLs.
+ </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 parameter documented in <link linkend="mcoc">Other Controls</link> are often used by administrators
+ in ways that create inadvertent barriers to file access. Such are the consequences of not understanding the
+ full implications of &smb.conf; file settings.
+ </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 timestamps 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 override 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>per-share access control</primary></indexterm>
+<indexterm><primary>Everyone - Full Control</primary></indexterm>
+<indexterm><primary>specific restrictions</primary></indexterm>
+<indexterm><primary>share access</primary></indexterm>
+ <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>
+<indexterm><primary>access control</primary></indexterm>
+<indexterm><primary>MMC</primary></indexterm>
+<indexterm><primary>Computer Management</primary></indexterm>
+ At this time Samba does not provide a tool for configuring access control settings on the share
+ itself the only way to create those settings is to use either the NT4 Server Manager or the Windows 200x
+ Microsoft Management Console (MMC) for Computer Management. There are currently no plans to provide
+ this capability in the Samba command-line tool set.
+ </para>
+
+ <para>
+<indexterm><primary>share_info.tdb</primary></indexterm>
+<indexterm><primary>/usr/local/samba/var</primary></indexterm>
+<indexterm><primary>tdbdump</primary></indexterm>
+<indexterm><primary>tdb files</primary></indexterm>
+ 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 share permissions management is platform-dependent. Choose the best tool for your environment.
+ </para>
+
+ <sect3>
+ <title>Windows NT4 Workstation/Server</title>
+ <para>
+<indexterm><primary>manage share permissions</primary></indexterm>
+<indexterm><primary>share permissions</primary></indexterm>
+<indexterm><primary>NT Server Manager</primary></indexterm>
+<indexterm><primary>Windows NT4</primary></indexterm>
+ The tool you need to manage share permissions on a Samba server from a Windows NT4 Workstation or 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 the Microsoft
+ web site <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;173673">support</ulink> section.
+ </para>
+
+ <procedure>
+ <title>Instructions</title>
+
+ <step><para>
+ Launch the <application>NT4 Server Manager</application> and 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 and 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>
+<indexterm><primary>Windows NT4/200x/XP</primary></indexterm>
+<indexterm><primary>ACLs on share</primary></indexterm>
+<indexterm><primary>Sharing</primary></indexterm>
+<indexterm><primary>Permissions</primary></indexterm>
+ On <application>MS Windows NT4/200x/XP</application> system, ACLs 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 "Everyone" full control on the share.
+ </para>
+
+ <para>
+<indexterm><primary>Computer Management</primary></indexterm>
+<indexterm><primary>MMC</primary></indexterm>
+<indexterm><primary>tool</primary></indexterm>
+ MS Windows 200x and later versions come with a tool called the <application>Computer Management</application>
+ snap-in for the 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>
+<indexterm><primary>Share Permissions</primary></indexterm>
+ 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 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
+ nonfunctional with a Samba share at this time, because 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:
+ <screen>
+ <constant>SERVER\user (Long name)</constant>
+ </screen>
+ <replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server, <replaceable>user</replaceable>
+ is the username 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>
+<indexterm><primary>Take Ownership</primary></indexterm>
+ 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 as whom 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. Because 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>
+<indexterm><primary>chown</primary></indexterm>
+<indexterm><primary>ownership</primary></indexterm>
+<indexterm><primary>Seclib</primary></indexterm>
+ 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 file system
+ 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 downloadable 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 it 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><replaceable>SERVER</replaceable> is the NetBIOS name of the Samba server,
+ <replaceable>user</replaceable> is the username 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 <emphasis>Full Control</emphasis>.
+ </para>
+
+
+ <para>
+ The permissions field is displayed differently for files and directories. Both are discussed next.
+ </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 <emphasis>no permissions</emphasis> 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 action are 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 also need to
+ 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 because 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 <emphasis>no
+ permissions</emphasis> on the UNIX side. If you view the permissions again, the <emphasis>no
+ permissions</emphasis> 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>
+ Because 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 uncheck the
+ <guilabel>Replace permissions on existing files</guilabel> checkbox 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>
+
+<?latex \newpage ?>
+ <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:
+
+
+ <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 <emphasis>1</emphasis> 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 <emphasis>1</emphasis> 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 <emphasis>on</emphasis>.</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 performs 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 <emphasis>on</emphasis>,
+ then set the following parameters in the &smb.conf; file in that
+ share-specific section:
+ </para>
+
+<?latex \newpage ?>
+ <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 or herself 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 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 administration 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 administrator and therefore
+ 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 noticeably 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 &lt;- the file name
+# owner: jeremy &lt;-- the file owner
+# group: users &lt;-- the POSIX group owner
+user::rwx &lt;-- perms for the file owner (user)
+user:tpot:r-x &lt;-- perms for the additional user `tpot'
+group::r-- &lt;-- perms for the file group owner (group)
+group:engrs:r-- &lt;-- perms for the additonal group `engineers'
+mask:rwx &lt;-- the mask that is `ANDed' with groups
+other::--- &lt;-- perms applied to everyone else (other)
+</screen>
+ Directory ACLs have the following signficance:
+<screen>
+# file: testdir &lt;-- the directory name
+# owner: jeremy &lt;-- the directory owner
+# group: jeremy &lt;-- the POSIX group owner
+user::rwx &lt;-- directory perms for owner (user)
+group::rwx &lt;-- directory perms for owning group (group)
+mask::rwx &lt;-- the mask that is `ANDed' with group perms
+other:r-x &lt;-- perms applied to everyone else (other)
+default:user::rwx &lt;-- inherited owner perms
+default:user:tpot:rwx &lt;-- inherited extra perms for user `tpot'
+default:group::r-x &lt;-- inherited group perms
+default:mask:rwx &lt;-- inherited default mask
+default:other:--- &lt;-- 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">How
+ Windows File ACLs Map to UNIX POSIX File ACLs</link>.
+ 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 one-to-one 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 ACLs. This has precedence 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
+ 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 and
+ UNIX POSIX ACLs to Windows ACEs (Access Control Entries, the discrete components of
+ an 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 topics on the mailing list. The following
+are examples recently taken from the mailing list.
+</para>
+
+
+ <sect2>
+ <title>Users Cannot Write to a Public Share</title>
+
+ <para>
+ The following complaint has frequently been voiced on the Samba mailing list:
+ <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
+ other users to change the file.
+ </quote>
+ </para>
+
+ <para>
+ Here is one way the problem can be solved:
+ </para>
+
+ <procedure>
+ <step>
+ <para>
+ Go to the top of the directory that is shared.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Set the ownership to whatever public user and group you want
+<screen>
+&prompt;find `directory_name' -type d -exec chown user:group {}\;
+&prompt;find `directory_name' -type d -exec chmod 2775 {}\;
+&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>SGID bit</constant> on all directories. Read your
+ UNIX/Linux man page on what that does. This ensures that all files and directories
+ that are created in the directory tree will be owned by the current user and will
+ be owned by the group that owns the directory in which it is created.
+ </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 2775 /foodbar</userinput>
+&prompt;<userinput>ls -al /foodbar/..</userinput>
+</screen>
+ </para>
+
+ <para>You should see:
+<screen>
+drwxrwsr-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 jill engr 0 2007-01-18 19:41 Afile
+</screen>
+ </para>
+ </step>
+
+ <step>
+ <para>
+ If the user that must have write permission in the directory is not a member of the group
+ <emphasis>engr</emphasis> set in the &smb.conf; entry for the share:
+ <smbconfblock>
+<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, 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 workaround to solve the permissions problem. It 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 readable/writable by the
+ owner and group set on the directory itself.
+ </para>
+
+ </sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml b/docs-xml/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml
new file mode 100644
index 0000000000..2ecfa4b1c3
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-AdvancedNetworkAdmin.xml
@@ -0,0 +1,485 @@
+<?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>June 15 2005</pubdate>
+</chapterinfo>
+
+<title>Advanced Network Management</title>
+
+<para>
+<indexterm><primary>access control</primary></indexterm>
+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>
+<indexterm><primary>Windows 9x/Me</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 the Microsoft <ulink noescape="1"
+url="ftp://ftp.microsoft.com/Softlib/MSLFILES/NEXUS.EXE">Nexus</ulink> link.
+</para>
+
+<para>
+<indexterm><primary>SRVTOOLS.EXE</primary></indexterm>
+<indexterm><primary>User Manager for Domains</primary></indexterm>
+<indexterm><primary>Server Manager</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>
+<indexterm><primary>remote desktop management</primary></indexterm>
+<indexterm><primary>network environment</primary></indexterm>
+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>
+<indexterm><primary>remote desktop capabilities</primary></indexterm>
+ 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>
+<indexterm><primary>Windows Terminal server</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>remote login</primary></indexterm>
+ 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 or 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>
+<indexterm><primary>Remote X protocol</primary></indexterm>
+<indexterm><primary>VNC/RFB</primary></indexterm>
+<indexterm><primary>rdesktop/RDP</primary></indexterm>
+ 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>
+<indexterm><primary>modem/ISDN</primary></indexterm>
+ 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>
+<indexterm><primary>KDE konqueror</primary></indexterm>
+<indexterm><primary>mouse-over</primary></indexterm>
+<indexterm><primary>rdesktop</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+ I test drove 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 631,750 points at first try.
+ </para>
+
+ <para>
+<indexterm><primary>NX</primary></indexterm>
+<indexterm><primary>TightVNC</primary></indexterm>
+<indexterm><primary>rdesktop</primary></indexterm>
+<indexterm><primary>Remote X</primary></indexterm>
+ NX performs better on my local LAN than any of the other <quote>pure</quote>
+ connection methods I use from time to time: TightVNC, rdesktop or
+ Remote X. It is even faster than a direct crosslink connection between
+ two nodes.
+ </para>
+
+ <para>
+<indexterm><primary>Remote X</primary></indexterm>
+<indexterm><primary>KDE session</primary></indexterm>
+<indexterm><primary>copy'n'paste</primary></indexterm>
+ 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 test driving NX to anybody with a only a passing interest in remote computing
+ the <ulink noescape="1" url="http://www.nomachine.com/testdrive.php">NX</ulink> utility.
+ </para>
+
+ <para>
+ Just download the free-of-charge client software (available for Red Hat,
+ SuSE, Debian and Windows) and be up and running within 5 minutes (they
+ need to send you your account data, though, because you are assigned
+ a real UNIX account on their testdrive.nomachine.com box).
+ </para>
+
+ <para>
+ They plan to get to the point were you can have NX application servers
+ running as a cluster of nodes, and users simply start an NX session locally
+ and can select applications to run transparently (apps may even run on
+ another NX node, but pretend to be on the same as used for initial login,
+ because it displays in the same window. You also can run it
+ full-screen, and after a short time you forget that it is a remote session
+ at all).
+ </para>
+
+ <para>
+<indexterm><primary>GPL</primary></indexterm>
+ 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>
+<indexterm><primary>OSS/Free Software</primary></indexterm>
+<indexterm><primary>LTSP</primary></indexterm>
+<indexterm><primary>KDE</primary></indexterm>
+<indexterm><primary>GNOME</primary></indexterm>
+<indexterm><primary>NoMachine</primary></indexterm>
+ NoMachine is 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>
+ <sect2>
+ <title>Remote Management with ThinLinc</title>
+ <para>
+ Another alternative for remote access is <emphasis>ThinLinc</emphasis> from Cendio.
+ </para>
+
+ <para>
+<indexterm><primary>ThinLinc</primary></indexterm>
+<indexterm><primary>terminal server</primary></indexterm>
+<indexterm><primary>Linux</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>TightVNC</primary></indexterm>
+<indexterm><primary>SSH</primary></indexterm>
+<indexterm><primary>NFS</primary></indexterm>
+<indexterm><primary>PulseAudio</primary></indexterm>
+ ThinLinc is a terminal server solution that is available for Linux and Solaris based on standard
+ protocols such as SSH, TightVNC, NFS and PulseAudio.
+ </para>
+
+ <para>
+<indexterm><primary>LAN</primary></indexterm>
+<indexterm><primary>thin client</primary></indexterm>
+ ThinLinc an be used both in the LAN environment to implement a Thin Client strategy for an organization, and as
+ secure remote access solution for people working from remote locations, even over smallband connections.
+ ThinLinc is free to use for a single concurrent user.
+ </para>
+
+ <para>
+<indexterm><primary>Citrix</primary></indexterm>
+<indexterm><primary>Windows Terminal Server</primary></indexterm>
+<indexterm><primary>Java</primary></indexterm>
+ The product can also be used as a frontend to access Windows Terminal Server or Citrix farms, or even Windows
+ XP machines, securing the connection via the ssh protocol. The client is available both for Linux (supporting
+ all Linux distributions as well as numerous thin terminals) and for Windows. A Java-based Web client is also
+ available.
+ </para>
+
+ <para>
+ ThinLinc may be evaluated by connecting to Cendio's demo system, see
+ <ulink noescape="1" url="http://www.cendio.com">Cendio's</ulink> web site
+ <ulink noescape="1" url="http://www.cendio.com/testdrive">testdrive</ulink> center.
+ </para>
+
+ <para>
+ Cendio is a major contributor to several open source projects including
+ <ulink noescape="1" url="http://www.tightvnc.com">TightVNC</ulink>,
+ <ulink noescape="1" url="http://pulseaudio.org">PulseAudio</ulink> , unfsd,
+ <ulink noescape="1" url="http://www.python.org">Python</ulink> and
+ <ulink noescape="1" url="http://www.rdesktop.org">rdesktop</ulink>.
+ </para>
+
+ </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:
+
+<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>
+</para>
+
+<para>
+Those wishing to use a 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 Knowledge Base 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 foolproof 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-xml/Samba3-HOWTO/TOSHARG-BDC.xml b/docs-xml/Samba3-HOWTO/TOSHARG-BDC.xml
new file mode 100644
index 0000000000..35fdd9ee57
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-BDC.xml
@@ -0,0 +1,862 @@
+<?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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>LDAP</primary><secondary>slave</secondary></indexterm>
+<indexterm><primary>scalability</primary></indexterm>
+Samba-3 can act 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 &smbmdash; if the slave finds its master down at the wrong time,
+you will have stability and operational problems.
+</para>
+
+<para>
+<indexterm><primary>two-way</primary><secondary>propagation</secondary></indexterm>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+<indexterm><primary>non-LDAP</primary><secondary>backend</secondary></indexterm>
+<indexterm><primary>propagate</primary></indexterm>
+While it is possible to run a Samba-3 BDC with a non-LDAP backend, that backend must allow some form of
+"two-way" propagation of changes from the BDC to the master. At this time only LDAP delivers the capability
+to propagate identity database changes from the BDC to the PDC. The BDC can use a slave LDAP server, while it
+is preferable for the PDC to use as its primary an LDAP master server.
+</para>
+
+<para>
+<indexterm><primary>non-LDAP</primary><secondary>backend</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>non-LDAP</secondary></indexterm>
+<indexterm><primary>domain</primary><secondary>member</secondary><tertiary>server</tertiary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>trust account password</primary></indexterm>
+<indexterm><primary>domain trust</primary></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>
+<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>
+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">The Domain Backend Account Distribution Options table below</link> lists
+possible design configurations for a PDC/BDC infrastructure.
+</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 failover 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; 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>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>logon requests</primary></indexterm>
+<indexterm><primary>LanMan</primary></indexterm>
+<indexterm><primary>Netlogon</primary></indexterm>
+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>
+<indexterm>network<primary></primary><secondary>logon</secondary><tertiary>service</tertiary></indexterm>
+<indexterm><primary>Windows NT3.10</primary></indexterm>
+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>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>authentication server</primary></indexterm>
+<indexterm><primary>username</primary></indexterm>
+<indexterm><primary>password</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>Security Account Manager</primary><see>SAM</see></indexterm>
+<indexterm><primary>domain control database</primary><see>SAM</see></indexterm>
+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>
+<indexterm><primary>account information</primary></indexterm>
+<indexterm><primary>machine accounts database</primary></indexterm>
+<indexterm><primary>profile</primary></indexterm>
+<indexterm><primary>network access profile</primary></indexterm>
+<indexterm><primary>desktop profile</primary></indexterm>
+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>
+<indexterm><primary>%SystemRoot%\System32\config</primary></indexterm>
+<indexterm><primary>C:\WinNT\System32\config</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>SAM</primary></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 BDCs are present
+on the network.
+</para>
+
+<para>
+There are two situations in which it is desirable to install BDCs:
+</para>
+
+<itemizedlist>
+ <listitem><para>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>BDC</primary></indexterm>
+ On the local network that the PDC 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>
+ <indexterm><primary>network</primary><secondary>wide-area</secondary></indexterm>
+ At each remote site, to reduce wide-area network traffic and to add stability to
+ remote network operations. The design of the network, and the strategic placement of
+ BDCs, 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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>user account database</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>trigger</primary></indexterm>
+The interoperation 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>
+<indexterm><primary>SAM</primary><secondary>replication</secondary></indexterm>
+<indexterm><primary>SAM</primary><secondary>delta file</secondary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+Samba-3 cannot 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 interoperate with a PDC (NT4 or Samba)
+to synchronize the SAM from delta files that are held by BDCs.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+Samba-3 cannot function as a BDC to an MS Windows NT4 PDC, and Samba-3 cannot
+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>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>promoted</primary></indexterm>
+<indexterm><primary>demoted</primary></indexterm>
+<indexterm><primary>reconfiguration</primary></indexterm>
+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 online, 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 cannot be
+promoted in this manner because reconfiguration of Samba requires changes to the &smb.conf; file. It is easy
+enough to manuall change the &smb.conf; file and then restart relevant Samba network services.
+</para>
+
+<sect3>
+<title>Example PDC Configuration</title>
+
+<para>
+<indexterm><primary>domain logon</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+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">the Minimal smb.conf for a PDC in Use with a BDC &smbmdash; LDAP Server on PDC
+section</link> for an example of the minimum required settings.
+</para>
+
+<example id="minimalPDC">
+<title>Minimal smb.conf for a PDC in Use with a BDC &smbmdash; LDAP Server on PDC</title>
+<smbconfblock>
+<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>
+<smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption>
+<smbconfoption name="ldap user suffix">ou=Users</smbconfoption>
+<smbconfoption name="ldap group suffix">ou=Groups</smbconfoption>
+<smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+<smbconfoption name="ldap admin dn">cn=sambadmin,dc=quenya,dc=org</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>profile path</primary></indexterm>
+<indexterm><primary>home drive</primary></indexterm>
+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>.
+Refer to <link linkend="samba-pdc">the Domain Control chapter</link> for specific recommendations for PDC
+configuration. Alternately, fully documented working example network configurations using OpenLDAP and Samba
+as available in the <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample">book</ulink> <quote>Samba-3
+by Example</quote> that may be obtained from local and on-line book stores.
+</para>
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>LDAP Configuration Notes</title>
+
+<para>
+<indexterm><primary>LDAP</primary><secondary>master</secondary></indexterm>
+<indexterm><primary>LDAP</primary><secondary>slave</secondary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+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>
+<indexterm><primary>LDAP</primary><secondary>master</secondary></indexterm>
+<indexterm><primary>LDAP</primary><secondary>server</secondary></indexterm>
+<indexterm><primary>CN</primary></indexterm>
+<indexterm><primary>DN</primary></indexterm>
+<indexterm><primary>RFC2830</primary></indexterm>
+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>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>transport layer security</primary><see>TLS</see></indexterm>
+<indexterm><primary>/etc/ssl/certs/slapd.pem</primary></indexterm>
+<indexterm><primary>slapd.pem</primary></indexterm>
+<indexterm><primary>Red Hat Linux</primary></indexterm>
+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 re-created with
+a correct hostname.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>machine account</primary></indexterm>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>replication</primary></indexterm>
+<indexterm><primary>duplicate</primary></indexterm>
+Do not install a Samba PDC so that is uses an LDAP 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 fallback configuration (secondary) LDAP server, you would specify
+the secondary LDAP server in the &smb.conf; file as shown in <link linkend="mulitldapcfg">the Multiple LDAP
+Servers in &smb.conf; example</link>.
+</para>
+
+<example id="mulitldapcfg">
+<title>Multiple LDAP Servers in &smb.conf;</title>
+<smbconfblock>
+<smbconfoption name="passdb backend">ldapsam:"ldap://master.quenya.org ldap://slave.quenya.org"</smbconfoption>
+</smbconfblock>
+</example>
+
+</sect2>
+
+<sect2>
+<title>Active Directory Domain Control</title>
+
+<para>
+<indexterm><primary>MS Windows 2000</primary></indexterm>
+<indexterm><primary>Active Directory</primary></indexterm>
+<indexterm><primary>directory</primary></indexterm>
+<indexterm><primary>replicated</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+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 BDC to an Active Directory domain controller.
+</para>
+
+</sect2>
+
+<sect2>
+<title>What Qualifies a Domain Controller on the Network?</title>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+Every machine that is a domain controller for the domain MIDEARTH has to register the NetBIOS
+group name MIDEARTH&lt;1C&gt; with the WINS server and/or by broadcast on the local network.
+The PDC also registers the unique NetBIOS name MIDEARTH&lt;1B&gt; with the WINS server.
+The name type &lt;1B&gt; name is normally reserved for the Domain Master Browser (DMB), a role
+that has nothing to do with anything related to authentication, but the Microsoft domain
+implementation requires the DMB to be on the same machine as the PDC.
+</para>
+
+<para>
+<indexterm><primary>broadcast</primary></indexterm>
+<indexterm><primary>name registration</primary></indexterm>
+<indexterm><primary>SMB/CIFS</primary></indexterm>
+Where a WINS server is not used, broadcast name registrations alone must suffice. Refer to
+<link linkend="NetworkBrowsing">Network Browsing</link>,<link linkend="netdiscuss">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>
+<indexterm><primary>locate domain controller</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+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>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>broadcast messaging</primary></indexterm>
+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>
+<indexterm><primary>Windows NT4/200x/XP</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>logon requests</primary></indexterm>
+<indexterm><primary>credentials validation</primary></indexterm>
+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&lt;1C&gt;. 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>
+<indexterm><primary>realm</primary></indexterm>
+<indexterm><primary>logon authentication</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>_ldap._tcp.pdc._msdcs.quenya.org</primary></indexterm>
+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>
+<indexterm><primary>BDC</primary></indexterm>
+The creation of a BDC requires some steps to prepare the Samba server before
+&smbd; is executed for the first time. These steps are as follows:
+</para>
+
+<itemizedlist>
+ <listitem><para>
+ <indexterm><primary>SID</primary></indexterm>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>BDC</primary></indexterm>
+ <indexterm><primary>private/secrets.tdb</primary></indexterm>
+ <indexterm><primary>private/MACHINE.SID</primary></indexterm>
+ <indexterm><primary>domain SID</primary></indexterm>
+ 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>. For all versions of Samba released since 2.2.5
+ the domain SID is stored in the file <filename>private/secrets.tdb</filename>. This file is unique to each
+ server and cannot be copied from a PDC to a BDC; the BDC will generate a new SID at startup. It will overwrite
+ 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>
+ <indexterm><primary>domain SID</primary></indexterm>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>BDC</primary></indexterm>
+ <indexterm><primary>secrets.tdb</primary></indexterm>
+ <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>getsid</tertiary></indexterm>
+ 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>
+ <indexterm><primary>secrets.tdb</primary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>LDAP administration password</primary></indexterm>
+ 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>
+ The <smbconfoption name="ldap suffix"/> parameter and the <smbconfoption name="ldap idmap suffix"/>
+ parameter must be specified in the &smb.conf; file.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+ <indexterm><primary>user database</primary></indexterm>
+ <indexterm><primary>synchronized</primary></indexterm>
+ <indexterm><primary>NIS</primary></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>
+ <indexterm><primary>password database</primary></indexterm>
+ <indexterm><primary>replicated</primary></indexterm>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>BDC</primary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>rsync</primary></indexterm>
+ <indexterm><primary>ssh</primary></indexterm>
+ <indexterm><primary>LDAP</primary></indexterm>
+ 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.
+ The use of rsync is inherently flawed by the fact that the data will be replicated
+ at timed intervals. There is no guarantee that the BDC will be operating at all
+ times with correct and current machine and user account information. This means that
+ this method runs the risk of users being inconvenienced by discontinuity of access
+ to network services due to inconsistent security data. It must be born in mind that
+ Windows workstations update (change) the machine trust account password at regular
+ intervals &smbmdash; administrators are not normally aware that this is happening
+ or when it takes place.
+ </para>
+
+ <para>
+ <indexterm><primary>POSIX</primary></indexterm>
+ <indexterm><primary>LDAP</primary></indexterm>
+ <indexterm><primary>SambaSAMAccount</primary></indexterm>
+ <indexterm><primary>synchronize</primary></indexterm>
+ The use of LDAP for both the POSIX (UNIX user and group) accounts and for the
+ SambaSAMAccount data automatically ensures that all account change information
+ will be written to the shared directory. This eliminates the need for any special
+ action to synchronize account information because LDAP will meet that requirement.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>netlogon share</primary></indexterm>
+ <indexterm><primary>replicate</primary></indexterm>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>BDC</primary></indexterm>
+ <indexterm><primary>cron</primary></indexterm>
+ <indexterm><primary>rsync</primary></indexterm>
+ 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>. The use of
+ <command>rsync</command> for replication of the netlogon data is not critical to network security and is one
+ that can be manually managed given that the administrator will make all changes to the netlogon share as part
+ of a conscious move.
+ </para></listitem>
+
+</itemizedlist>
+
+<sect2>
+<title>Example Configuration</title>
+
+<para>
+Finally, the BDC has to be capable of being found by the workstations. This can be done by configuring the
+Samba &smb.conf; file <smbconfsection name="[global]"/> section as shown in <link linkend="minim-bdc">Minimal
+Setup for Being a BDC</link>.
+</para>
+
+<example id="minim-bdc">
+<title>Minimal Setup for Being a BDC</title>
+<smbconfblock>
+<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="ldap suffix">dc=abmas,dc=biz</smbconfoption>
+<smbconfoption name="ldap user suffix">ou=Users</smbconfoption>
+<smbconfoption name="ldap group suffix">ou=Groups</smbconfoption>
+<smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+<smbconfoption name="ldap admin dn">cn=sambadmin,dc=quenya,dc=org</smbconfoption>
+<smbconfoption name="idmap backend">ldap:ldap://master-ldap.quenya.org</smbconfoption>
+<smbconfoption name="idmap uid">10000-20000</smbconfoption>
+<smbconfoption name="idmap gid">10000-20000</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+Fully documented working example network configurations using OpenLDAP and Samba
+as available in the <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample">book</ulink> <quote>Samba-3
+by Example</quote> that may be obtained from local and on-line book stores.
+</para>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+This configuration causes the BDC to register only the name MIDEARTH&lt;1C&gt; with the WINS server. This is
+not a problem, as the name MIDEARTH&lt;1C&gt; 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 MIDEARTH&lt;1B&gt;, which is a unique NetBIOS name that is reserved for the PDC.
+</para>
+
+<para>
+<indexterm><primary>idmap backend</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>redirect</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>LDAP database</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>nss_ldap</primary></indexterm>
+The <parameter>idmap backend</parameter> will redirect the <command>winbindd</command> utility to use the LDAP
+database to store all mappings for Windows SIDs to UIDs and GIDs for UNIX accounts in a repository that is
+shared. The BDC will however depend on local resolution of UIDs and GIDs via NSS and the
+<command>nss_ldap</command> utility.
+</para>
+
+<note><para>
+<indexterm><primary>Server Type</primary><secondary>Domain Member</secondary></indexterm>
+<indexterm><primary>ID mapping</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>idmap backend</primary></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>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>domain member servers</primary></indexterm>
+The use of the <smbconfoption name="idmap backend">ldap:ldap://master.quenya.org</smbconfoption>
+option on a BDC only makes sense where ldapsam is used on a PDC. The purpose of 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>
+<indexterm><primary>domain control</primary></indexterm>
+Domain control was a new area for Samba, but there are now many examples that we may refer to.
+Updated information 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>; refer in particular to the
+<filename>WHATSNEW.txt</filename> in the Samba release tarball. The book, <quote>Samba-3 by Example</quote>
+documents well tested and proven configuration examples. You can obtain a copy of this
+<ulink url="http://www.samba.org/samba/docs/Samba3-ByExample.pdf">book</ulink> for the Samba web site.
+</para>
+
+<sect2>
+<title>Machine Accounts Keep Expiring</title>
+
+<para>
+<indexterm><primary>Machine Trust Accounts</primary></indexterm>
+<indexterm><primary>passdb</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>Local Machine Trust Account</primary></indexterm>
+This problem will occur when the passdb (SAM) files are copied from a central
+server but the local BDC 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
+overwritten when the SAM is recopied from the PDC. The result is that the domain member machine
+on startup 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>
+<indexterm><primary>SAM</primary></indexterm>
+No. The native NT4 SAM replication protocols have not yet been fully implemented.
+</para>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>logon requests</primary></indexterm>
+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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>SAM</primary></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>
+<indexterm><primary>plaintext password</primary></indexterm>
+<indexterm><primary>ssh</primary></indexterm>
+<indexterm><primary>rsync</primary></indexterm>
+As the smbpasswd file contains plaintext 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>
+<indexterm><primary>machine trust accounts</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+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>
+<indexterm><primary>pdb_ldap</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+The simple answer is yes. Samba's pdb_ldap code supports binding to a replica
+LDAP server and will also follow referrals and rebind 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-xml/Samba3-HOWTO/TOSHARG-Backup.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Backup.xml
new file mode 100644
index 0000000000..ede68229bc
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Backup.xml
@@ -0,0 +1,241 @@
+<?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>
+<indexterm><primary>backup</primary></indexterm>
+<indexterm><primary>UNIX system files</primary></indexterm>
+<indexterm><primary>system tools</primary></indexterm>
+<indexterm><primary>Samba mailing lists</primary></indexterm>
+The Samba project is over 10 years old. During the early history
+of Samba, UNIX administrators were its key implementors. UNIX administrators
+use UNIX system tools to backup UNIX system files. Over the past
+4 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>
+<indexterm><primary>Meccano set</primary></indexterm>
+<indexterm><primary>training course</primary></indexterm>
+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 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>
+<indexterm><primary>networking advocates</primary></indexterm>
+<indexterm><primary>clear purpose preferred</primary></indexterm>
+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>
+<indexterm><primary>due diligence</primary></indexterm>
+<indexterm><primary>research</primary></indexterm>
+<indexterm><primary>backup solution</primary></indexterm>
+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>
+<indexterm><primary>rsync</primary></indexterm>
+<indexterm><primary>rsyncd</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>
+<indexterm><primary>BackupPC</primary></indexterm>
+<indexterm><primary>laptops</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>smbclient</primary></indexterm>
+<indexterm><primary>tar</primary></indexterm>
+<indexterm><primary>rsh</primary></indexterm>
+<indexterm><primary>ssh</primary></indexterm>
+<indexterm><primary>rsync</primary></indexterm>
+ BackupPC is a high-performance Perl-based package for backing up Linux,
+ UNIX, and 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>
+<indexterm><primary>RAID</primary></indexterm>
+<indexterm><primary>local disk</primary></indexterm>
+<indexterm><primary>network storage</primary></indexterm>
+ 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>
+<indexterm><primary>GNU GPL</primary></indexterm>
+ 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>
+<indexterm><primary>rsync</primary></indexterm>
+<indexterm><primary>ftp</primary></indexterm>
+<indexterm><primary>http</primary></indexterm>
+<indexterm><primary>scp</primary></indexterm>
+<indexterm><primary>rcp</primary></indexterm>
+<indexterm><primary>checksum-search</primary></indexterm>
+ <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>
+<indexterm><primary>remote-update protocol</primary></indexterm>
+<indexterm><primary>transfer differences</primary></indexterm>
+<indexterm><primary>differences</primary></indexterm>
+ 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>
+<indexterm><primary>native dump</primary></indexterm>
+<indexterm><primary>GNU tar</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-xml/Samba3-HOWTO/TOSHARG-Bugs.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Bugs.xml
new file mode 100644
index 0000000000..0ef2c5cc76
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Bugs.xml
@@ -0,0 +1,287 @@
+<?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>
+<indexterm><primary>Bugzilla</primary></indexterm>
+<indexterm><primary>bug reports</primary></indexterm>
+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>
+<indexterm><primary>comp.protocols.smb</primary></indexterm>
+<indexterm><primary>newsgroup</primary></indexterm>
+<indexterm><primary>configuration problem</primary></indexterm>
+If you post the bug to the comp.protocols.smb
+newsgroup or the mailing list, do not assume 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 misconfigured 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>
+<indexterm><primary>debug level</primary></indexterm>
+<indexterm><primary>log level</primary></indexterm>
+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>
+
+<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>
+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>
+<indexterm><primary>debugging</primary></indexterm>
+<indexterm><primary>logging</primary></indexterm>
+<indexterm><primary>functional components</primary></indexterm>
+<indexterm><primary>cluttering</primary></indexterm>
+ 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
+ achieve 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 functional 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">Debuggable Functions</link>
+ may be used to attain 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>
+<screen>
+&prompt;<userinput>gdb smbd core</userinput>
+</screen>
+</para>
+
+<para>
+<indexterm><primary>dbx</primary></indexterm>
+<indexterm><primary>stack trace</primary></indexterm>
+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>
+<indexterm><primary>disass</primary></indexterm>
+If you know any assembly language, do a <command>disass</command> of the routine
+where the problem occurred (if it's 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>
+<indexterm><primary>PID</primary></indexterm>
+<indexterm><primary>gdb</primary></indexterm>
+<indexterm><primary>smbstatus</primary></indexterm>
+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 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 PID
+of the spinning process and type:
+<screen>
+&rootprompt; gdb /usr/local/samba/sbin/smbd
+</screen>
+<indexterm><primary>spinning process</primary></indexterm>
+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-xml/Samba3-HOWTO/TOSHARG-CUPS-printing.xml b/docs-xml/Samba3-HOWTO/TOSHARG-CUPS-printing.xml
new file mode 100644
index 0000000000..9b12e4cac5
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-CUPS-printing.xml
@@ -0,0 +1,5237 @@
+<?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>
+<indexterm><primary>default printing</primary></indexterm>
+ 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 have trouble finding out where to start debugging it. Refer to
+ <link linkend="classicalprinting">Classical Printing</link>, which contains much information
+ that is also relevant to CUPS.
+ </para>
+
+ <para>
+<indexterm><primary>CUPS</primary></indexterm>
+ CUPS sports quite a few unique and powerful features. While its basic functions may be grasped quite
+ easily, they are also new. Because it is different from other, more traditional printing systems, it is best
+ not to try to 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>
+<indexterm><primary>print spooling system</primary></indexterm>
+<indexterm><primary>CUPS</primary></indexterm>
+<indexterm><primary>printer management system</primary></indexterm>
+<indexterm><primary>IETF</primary></indexterm>
+<indexterm><primary>Internet Printing Protocol</primary><see>IPP</see></indexterm>
+<indexterm><primary>Internet Engineering Task Force</primary><see>IETF</see></indexterm>
+<indexterm><primary>GUI</primary></indexterm>
+<indexterm><primary>KDEPrint</primary></indexterm>
+ 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 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>
+<indexterm><primary>raw printers</primary></indexterm>
+<indexterm><primary>smart printers</primary></indexterm>
+ CUPS allows creation of <emphasis>raw</emphasis> printers (i.e., no print file format translation) as
+ well as <emphasis>smart</emphasis> printers (i.e., CUPS does file format conversion as required for the
+ printer). In many ways, this gives CUPS capabilities similar 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 explore how
+ to configure CUPS for interfacing with MS Windows print clients via Samba.
+ </para>
+
+ </sect2>
+
+</sect1>
+
+<sect1>
+ <title>Basic CUPS Support Configuration</title>
+
+ <para>
+<indexterm><primary>CUPS</primary></indexterm>
+<indexterm><primary>cupsd.conf</primary></indexterm>
+<indexterm><primary>/etc/printcap</primary></indexterm>
+<indexterm><primary>Printcap</primary></indexterm>
+<indexterm><primary>PrintcapFormat</primary></indexterm>
+Printing with CUPS in the most basic &smb.conf; setup in Samba-3.0 (as was true for 2.2.x) requires just two
+parameters: <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 regarding the CUPS
+server itself available from the <ulink noescape="1"
+url="http://localhost:631/documentation.html">CUPS</ulink> web site.
+ </para>
+
+ <sect2>
+ <title>Linking smbd with libcups.so</title>
+
+ <para>
+<indexterm><primary>libcups.so</primary></indexterm>
+ Samba has a special relationship to CUPS. Samba can be compiled with CUPS library support.
+ Most recent installations have this support enabled. By 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>
+<indexterm><primary>libcups</primary></indexterm>
+<indexterm><primary>ldd</primary></indexterm>
+ When Samba is compiled and linked with <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 if smbd has been linked with the
+ libcups library (<command>ldd</command> may not be present on other OS platforms, or its function may be embodied
+ by a different command):
+<screen>
+&rootprompt;<userinput>ldd `which smbd`</userinput>
+libssl.so.0.9.6 =&gt; /usr/lib/libssl.so.0.9.6 (0x4002d000)
+libcrypto.so.0.9.6 =&gt; /usr/lib/libcrypto.so.0.9.6 (0x4005a000)
+libcups.so.2 =&gt; /usr/lib/libcups.so.2 (0x40123000)
+[....]
+</screen>
+ </para>
+
+ <para>
+<indexterm><primary>libcups.so.2</primary></indexterm>
+ The line <computeroutput>libcups.so.2 =&gt; /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">the Simplest Printing-Related
+ &smb.conf; file</link> shows the simplest printing-related setup for &smb.conf; to
+ enable basic CUPS support:
+ </para>
+
+ <example id="cups-exam-simple">
+ <title>Simplest Printing-Related smb.conf</title>
+ <smbconfblock>
+ <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>
+ </smbconfblock>
+ </example>
+
+ <para>
+<indexterm><primary>PDF</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>printer driver</primary></indexterm>
+ 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 rarely 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 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 what problem this may cause and how to avoid it.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>More Complex CUPS &smb.conf; Settings</title>
+
+ <para>
+ <link linkend="overridesettings">The Overriding Global CUPS Settings for One Printer example</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>
+
+ <example id="overridesettings">
+ <title>Overriding Global CUPS Settings for One Printer</title>
+ <smbconfblock>
+ <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" >> /tmp/smbprn.log ; echo " `date`: p-%p s-%s f-%f" >> /tmp/smbprn.log ; echo " `date`: j-%j J-%J z-%z c-%c" >> /tmp/smbprn.log ; rm %f </smbconfoption>
+ <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>
+ </smbconfblock>
+ </example>
+
+ <para>
+ This special share is only 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
+ allows access from only three hosts. To prevent CUPS from 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 set up 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></indexterm>
+ <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 use of a print server: it routes all jobs through one
+ central system, which responds immediately, takes jobs from multiple concurrent clients, and transfers them to
+ the printer(s) in the correct order.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Raw Print Serving: 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 is ready to be sent to the printing
+ device. In this case, a native (vendor-supplied) Windows printer driver needs to
+ be installed on each and every client for the target device.
+ </para>
+
+ <para>
+<indexterm><primary>render</primary></indexterm>
+<indexterm><primary>vendor-provided drivers</primary></indexterm>
+ 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 raw print-through.
+ This is achieved by installation of the printer as if it were physically
+ attached to the Windows client. You then redirect output to a raw network
+ print queue. This procedure may be followed to achieve this:
+ </para>
+
+ <procedure>
+ <title>Configuration Steps for Raw CUPS Printing Support</title>
+
+ <step><para>
+<indexterm><primary>/etc/cups/mime.types</primary></indexterm>
+ 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>
+<indexterm><primary>/etc/cups/mime.convs</primary></indexterm>
+ 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, and 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, that is, Printing to <constant>LPT1:</constant>.
+ </para></step>
+
+ <step><para>
+ Edit the configuration under the <guimenu>Detail</guimenu> tab and 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 LanMan 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) that 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 <filename>error_log</filename> 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>
+<indexterm><primary>MIME type</primary></indexterm>
+ That CUPS is 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.
+ </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 <link linkend="classicalprinting">Classical Printing
+ chapter</link> of this book. 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 tool set method.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+<indexterm><primary>cupsaddsmb</primary></indexterm>
+ These three methods apply to CUPS all the same. The <command>cupsaddsmb</command> utility is a new and more
+ convenient way to load the Windows drivers into Samba and is provided if you use CUPS.
+ </para>
+
+ <para>
+ <command>cupsaddsmb</command> is discussed in much detail later in this chapter. 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> print server, that is, a server that spools
+ print jobs <quote>raw</quote>, leaving the print data untouched.
+ </para>
+
+ <para>
+ You might need to set up CUPS in a smarter way. The reasons could be manifold:
+ </para>
+
+<indexterm><primary>print statistics</primary></indexterm>
+<indexterm><primary>average print run</primary></indexterm>
+<indexterm><primary>print quota</primary></indexterm>
+ <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 set up 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 are 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
+ 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 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 it is so.
+ </para>
+
+
+ <para>
+ <indexterm><primary>PCL</primary></indexterm>
+ <indexterm><primary>PDL</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>Adobe</primary></indexterm>
+<indexterm><primary>page description languages</primary><see>PDL</see></indexterm>
+ You can't expect to throw just any file format at a printer and have it get printed. A file format conversion
+ must take place. 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 Hewlett-Packard) have developed into semi-official <quote>standards</quote> by being the most widely
+ used 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>
+<indexterm><primary>Enhanced MetaFile</primary><see>EMF</see></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 (What You See Is What You Get) 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>
+<indexterm><primary>Xprint</primary></indexterm>
+<indexterm><primary>core graphic engine</primary></indexterm>
+ To the GDI foundation in MS Windows, Apple has chosen to put paper and screen output on a common foundation
+ for its (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.
+ Apple's <emphasis>core graphic engine</emphasis> uses a <emphasis>PDF</emphasis> derivative for all display work.
+ </para></note>
+
+ <para>
+ The example in <link linkend="1small">Windows Printing to a Local Printer</link> illustrates local Windows
+ printing.
+ </para>
+
+ <figure id="1small">
+ <title>Windows Printing to a Local Printer.</title>
+ <imagefile>1small</imagefile>
+ </figure>
+
+ </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>, 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>
+<indexterm><primary>color</primary></indexterm>
+<indexterm><primary>linewidth</primary></indexterm>
+<indexterm><primary>scale</primary></indexterm>
+<indexterm><primary>distort</primary></indexterm>
+<indexterm><primary>rotate</primary></indexterm>
+<indexterm><primary>shift</primary></indexterm>
+<indexterm><primary>raster images</primary></indexterm>
+<indexterm><primary>display PostScript</primary></indexterm>
+<indexterm><primary>graphical objects</primary></indexterm>
+ The PostScript programming language is an <quote>invention</quote> by Adobe, but its specifications have been
+ published extensively. 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 or her 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 that 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>
+<indexterm><primary>PostScript interpreter</primary></indexterm>
+<indexterm><primary>raster image processor</primary><see>RIP</see></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
+ that 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. The RIP does 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 than PostScript printing a file from a Windows origin.
+ </para>
+
+ <note><para>
+ <indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>PPD-aware</primary></indexterm>
+<indexterm><primary>PostScript Printer Description</primary><see>PPD</see></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. as illustrated in <link linkend="2small">Printing to a PostScript Printer</link>.
+ </para>
+ </note>
+
+ <figure id="2small">
+ <title>Printing to a PostScript Printer.</title>
+ <imagefile>2small</imagefile>
+ </figure>
+
+ <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 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: 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. This is shown in
+ <link linkend="3small">Ghostscript as a RIP for Non-PostScript Printers</link>.
+ </para>
+
+ <figure id="3small">
+ <title>Ghostscript as a RIP for Non-PostScript Printers.</title>
+ <imagefile>3small</imagefile>
+ </figure>
+
+ <tip><para>
+<indexterm><primary>PNG</primary></indexterm>
+<indexterm><primary>AFPL</primary></indexterm>
+<indexterm><primary>ESP</primary></indexterm>
+ Use the <quote>gs -h</quote> command to check for all built-in <quote>devices</quote> on 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>
+<indexterm><primary>PDL</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+ While PostScript in essence is a 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>
+<indexterm><primary>PDF distilling</primary></indexterm>
+ A PostScript file that was created to contain device-specific commands
+ for achieving a certain print job output (e.g., duplexed, 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>
+<indexterm><primary>CUPS</primary></indexterm>
+<indexterm><primary>PPDs</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+ CUPS can handle all spec-compliant PPDs as supplied by the manufacturers for their PostScript models. Even if
+ a vendor does not mention our favorite OS in his or her 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 stricter 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>
+<indexterm><primary>W32X86/2</primary></indexterm>
+ 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> subdirectory for the PPD you are seeking.
+ </para></tip>
+ </sect2>
+
+ <sect2>
+ <title>CUPS Also Uses PPDs for Non-PostScript Printers</title>
+
+ <para>
+<indexterm><primary>non-PostScript</primary></indexterm>
+<indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>CUPS filtering</primary></indexterm>
+ 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>
+<indexterm><primary>CUPS filtering</primary></indexterm>
+<indexterm><primary>Ghostscript</primary></indexterm>
+<indexterm><primary>MIME type</primary></indexterm>
+<indexterm><primary>MIME recognition</primary></indexterm>
+<indexterm><primary>MIME conversion rules</primary></indexterm>
+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 print file is subjected to an initial
+autotyping. The autotyping 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 set up 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>
+<indexterm><primary>generic raster format</primary></indexterm>
+<indexterm><primary>CUPS raster</primary></indexterm>
+ 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>
+<indexterm><primary>raster driver</primary></indexterm>
+ The second stage uses a <quote>raster driver</quote> that converts
+ the generic CUPS raster to a device-specific raster.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>Ghostscript</primary></indexterm>
+<indexterm><primary>GNU Ghostscript</primary></indexterm>
+<indexterm><primary>ESP Ghostscript</primary></indexterm>
+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 recompile 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 (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>
+<indexterm><primary>foomatic-rip</primary></indexterm>
+<indexterm><primary>ESP Ghostscript</primary></indexterm>
+CUPS printers may be set up 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 Foomatic/cupsomatic, particularly the new version
+called now <emphasis>foomatic-rip</emphasis>, follows).
+</para>
+
+ <sect2>
+ <title>MIME Types and CUPS Filters</title>
+
+
+ <para>
+ <indexterm><primary>MIME</primary><secondary>filters</secondary></indexterm>
+ <indexterm><primary>MIME</primary></indexterm>
+<indexterm><primary>mime.types</primary></indexterm>
+<indexterm><primary>application/pdf</primary></indexterm>
+<indexterm><primary>autotyping</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 autotyping 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>
+<indexterm><primary>%PDF</primary></indexterm>
+<indexterm><primary>.pdf</primary></indexterm>
+ This means if a filename has 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,&lt;04&gt;%!)
+</programlisting>
+<indexterm><primary>suffixes</primary></indexterm>
+<indexterm><primary>.ai</primary></indexterm>
+<indexterm><primary>.eps</primary></indexterm>
+<indexterm><primary>.ps</primary></indexterm>
+<indexterm><primary>generic PostScript</primary></indexterm>
+<indexterm><primary>application/postscript</primary></indexterm>
+ 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>
+<indexterm><primary>/etc/cups/</primary></indexterm>
+ 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>
+<indexterm><primary>application/postscript</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>filter</primary></indexterm>
+<indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>transformation</primary></indexterm>
+ 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>
+<indexterm><primary>ASCII</primary></indexterm>
+<indexterm><primary>HP-GL</primary></indexterm>
+<indexterm><primary>PDF</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>DVI</primary></indexterm>
+<indexterm><primary>GIF</primary></indexterm>
+<indexterm><primary>PNG</primary></indexterm>
+<indexterm><primary>TIFF</primary></indexterm>
+<indexterm><primary>JPEG</primary></indexterm>
+<indexterm><primary>Photo-CD</primary></indexterm>
+<indexterm><primary>SUN-Raster</primary></indexterm>
+<indexterm><primary>PNM</primary></indexterm>
+<indexterm><primary>PBM</primary></indexterm>
+<indexterm><primary>SGI-RGB</primary></indexterm>
+<indexterm><primary>MIME</primary></indexterm>
+<indexterm><primary>filters</primary></indexterm>
+ 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>
+<indexterm><primary>/etc/cups/mime.convs</primary></indexterm>
+<indexterm><primary>application/pdf</primary></indexterm>
+<indexterm><primary>application/postscript</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>
+<indexterm><primary>pdftops</primary></indexterm>
+ 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>
+<indexterm><primary>hpgltops</primary></indexterm>
+ 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>
+<indexterm><primary>application/x-shell</primary></indexterm>
+<indexterm><primary>text/plain</primary></indexterm>
+<indexterm><primary>texttops</primary></indexterm>
+<programlisting>
+application/x-shell application/postscript 33 texttops
+text/plain application/postscript 33 texttops
+</programlisting>
+<indexterm><primary>application/x-shell</primary></indexterm>
+ 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 predefined there. You can plug in any filter you like to 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 with 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 <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 arguments:
+ </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>
+<indexterm><primary>non-PostScript printers</primary></indexterm>
+<indexterm><primary>raster</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>
+<indexterm><primary>prefilters</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>ASCII text</primary></indexterm>
+<indexterm><primary>PDF</primary></indexterm>
+<indexterm><primary>DVI</primary></indexterm>
+<indexterm><primary>HP-GL.</primary></indexterm>
+<indexterm><primary>MIME type</primary></indexterm>
+<indexterm><primary>application/postscript</primary></indexterm>
+<indexterm><primary>pstops</primary></indexterm>
+<indexterm><primary>application/vnd.cups-postscript</primary></indexterm>
+ But what happens if you send one of the supported non-PS formats to print? Then CUPS runs
+ <quote>prefilters</quote> on these input formats to generate PostScript first. There are prefilters to create
+ PostScript 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 prefilter 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. This is shown in <link linkend="4small">Prefiltering in
+ CUPS to Form PostScript</link>.
+ </para>
+
+ <figure id="4small">
+ <title>Prefiltering in CUPS to Form PostScript.</title>
+ <imagefile scale="25">4small</imagefile>
+ </figure>
+
+ </sect2>
+
+ <sect2>
+ <title>pstops</title>
+
+ <para>
+<indexterm><primary>pstops</primary></indexterm>
+<indexterm><primary>application/postscript</primary></indexterm>
+<indexterm><primary>application/vnd.cups-postscript</primary></indexterm>
+<indexterm><primary>output duplexing</primary></indexterm>
+<indexterm><primary>stapling</primary></indexterm>
+<indexterm><primary>punching</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+ <emphasis>pstops</emphasis> is a filter that is used to convert <parameter>application/postscript</parameter> to
+ <parameter>application/vnd.cups-postscript</parameter>. As stated earlier, 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. An example is illustrated in <link
+ linkend="5small">Adding Device-Specific Print Options</link>.
+ </para>
+
+ <figure id="5small">
+ <title>Adding Device-Specific Print Options.</title>
+ <imagefile scale="25">5small</imagefile>
+ </figure>
+
+ <para>
+ This is not all. Other tasks performed by it are:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ Selecting the range of pages to be printed (e.g., you can choose to
+ print only pages <quote>3, 6, 8-11, 16, and 19-21</quote>, or only odd-numbered
+ pages).
+ </para></listitem>
+
+ <listitem><para>
+ Putting two 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>
+<indexterm><primary>pstoraster</primary></indexterm>
+<indexterm><primary>rasterization</primary></indexterm>
+<indexterm><primary>raster drivers</primary></indexterm>
+ <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. This is shown in <link linkend="cups-raster">the PostScript to
+ Intermediate Raster Format diagram</link>.
+ </para>
+
+ <figure id="cups-raster">
+ <title>PostScript to Intermediate Raster Format.</title>
+ <imagefile scale="25">6small</imagefile>
+ </figure>
+
+ <para>
+<indexterm><primary>CUPS raster</primary></indexterm>
+<indexterm><primary>generic raster</primary></indexterm>
+<indexterm><primary>IANA</primary></indexterm>
+<indexterm><primary>raster drivers</primary></indexterm>
+ 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 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 of the first stage of rasterization so these vendors do not need to care about
+ Ghostscript complications (in fact, there are currently more than one vendor financing the development of CUPS
+ raster drivers). This is illustrated in <link linkend="cups-raster2">the CUPS-Raster Production Using
+ Ghostscript illustration</link>.
+ </para>
+
+ <figure id="cups-raster2">
+ <title>CUPS-Raster Production Using Ghostscript.</title>
+ <imagefile>7small</imagefile>
+ </figure>
+
+ <para>
+<indexterm><primary>pstoraster</primary></indexterm>
+<indexterm><primary>GNU Ghostscript</primary></indexterm>
+<indexterm><primary>AFPL Ghostscript</primary></indexterm>
+<indexterm><primary>standalone filter</primary></indexterm>
+ CUPS versions before version 1.1.15 shipped a binary (or source code) standalone filter, named
+ <parameter>pstoraster</parameter>. <parameter>pstoraster</parameter>, which was derived from GNU Ghostscript
+ 5.50 and could be installed instead of and in addition to any GNU or AFPL Ghostscript package without
+ conflicting.
+ </para>
+
+ <para>
+ Since version 1.1.15, this feature has changed. The functions for this filter 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 fails when this command is executed: <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>
+<indexterm><primary>prefilter</primary></indexterm>
+<indexterm><primary>imagetoraster</primary></indexterm>
+ In the section about prefilters, we mentioned the prefilter
+ 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 previously
+ mentioned prefilters. We summarize in a flowchart the image file
+ filtering in <link linkend="small8">the Image Format to CUPS-Raster Format Conversion illustration</link>.
+ </para>
+
+ <figure id="small8">
+ <title>Image Format to CUPS-Raster Format Conversion.</title>
+ <imagefile>8small</imagefile>
+ </figure>
+
+ </sect2>
+
+ <sect2>
+ <title>rasterto [printers specific]</title>
+
+ <para>
+<indexterm><primary>rastertoalps</primary></indexterm>
+<indexterm><primary>rastertobj</primary></indexterm>
+<indexterm><primary>rastertoepson</primary></indexterm>
+<indexterm><primary>rastertoescp</primary></indexterm>
+<indexterm><primary>rastertopcl</primary></indexterm>
+<indexterm><primary>rastertoturboprint</primary></indexterm>
+<indexterm><primary>rastertoescp</primary></indexterm>
+<indexterm><primary>rastertohp</primary></indexterm>
+<indexterm><primary>rastertoprinter</primary></indexterm>
+<indexterm><primary>rastertoprinter</primary></indexterm>
+<indexterm><primary>Gimp-Print</primary></indexterm>
+ CUPS ships with quite a variety of raster drivers for processing CUPS raster. On my system, I find in
+ /usr/lib/cups/filter/ the following: <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 fewer drivers than this; some of these are
+ installed by commercial add-ons to CUPS (like <parameter>rastertoturboprint</parameter>), and others (like
+ <parameter>rastertoprinter</parameter>) by third-party driver development projects (such as Gimp-Print)
+ wanting to cooperate as closely as possible with CUPS. See <link linkend="small9">the Raster to
+ Printer-Specific Formats illustration</link>.
+ </para>
+
+ <figure id="small9">
+ <title>Raster to Printer-Specific Formats.</title>
+ <imagefile>9small</imagefile>
+ </figure>
+ </sect2>
+
+ <sect2>
+ <title>CUPS Backends</title>
+
+ <para>
+<indexterm><primary>CUPS filtering chain</primary></indexterm>
+<indexterm><primary>print queue</primary></indexterm>
+ 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 for sending print jobs over the network, and one 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 use
+ 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 greatly 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) and
+ <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) and
+ <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. Examples of 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 systemwide default printer set up to be connected to
+ a devnull:/ backend: there are just too many people sending jobs
+ without specifying a printer, and scripts and programs that do not name
+ a printer. The systemwide default deletes the job and sends a polite
+ email back to the $USER asking him or her to always specify the correct
+ printer name.)
+ </para>
+
+ <para>
+<indexterm><primary>lpinfo</primary></indexterm>
+<indexterm><primary>CUPS backends</primary></indexterm>
+ 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>
+<indexterm><primary>PPDs</primary></indexterm>
+<indexterm><primary>Foomatic Printer</primary></indexterm>
+<indexterm><primary>Linuxprinting.org</primary></indexterm>
+ <parameter>cupsomatic</parameter> filters may be the most widely used on CUPS
+ installations. You must be clear 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 &amp; 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
+ autoconstructed from the selected PPD and command line options give to
+ the print job.
+ </para>
+
+ <para>
+ <indexterm><primary>point'n'print</primary></indexterm>
+<indexterm><primary>foomatic-rip</primary></indexterm>
+<indexterm><primary>Adobe specifications</primary></indexterm>
+<indexterm><primary>hi-res photo</primary></indexterm>
+<indexterm><primary>normal color</primary></indexterm>
+<indexterm><primary>grayscale</primary></indexterm>
+<indexterm><primary>draft</primary></indexterm>
+<indexterm><primary>media type</primary></indexterm>
+<indexterm><primary>resolution</primary></indexterm>
+<indexterm><primary>inktype</primary></indexterm>
+<indexterm><primary>dithering algorithm</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 of PPDs, which
+ 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 with the Adobe spec. 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 that the new <constant>foomatic-rip</constant> 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 chapter.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title><filename>mime.convs</filename></title>
+
+ <para>
+ CUPS autoconstructs all possible filtering chain paths for any given
+ MIME type and every printer installed. But how does it decide in
+ favor of or against a specific alternative? (There may 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>
+<indexterm><primary>cupsd.conf</primary></indexterm>
+<indexterm><primary>FilterLimit</primary></indexterm>
+ Setting <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>
+<indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>lpadmin</primary></indexterm>
+<indexterm><primary>rawprinter</primary></indexterm>
+ 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:
+<screen>
+&prompt;<userinput>lpadmin -P rawprinter -v socket://11.12.13.14:9100 -E</userinput>
+</screen>
+ 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>
+<indexterm><primary>/etc/cups/mime.types</primary></indexterm>
+<indexterm><primary>application/octet-stream</primary></indexterm>
+ 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 by default,
+ you will probably have experienced 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>
+<indexterm><primary>raw mode</primary></indexterm>
+ Both contain entries (at the end of the respective files) that 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 autotyping 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>
+<indexterm><primary>security-aware</primary></indexterm>
+<indexterm><primary>MIME type</primary></indexterm>
+<indexterm><primary>/etc/cups/mime.types</primary></indexterm>
+<indexterm><primary>/etc/cups/mime.convs</primary></indexterm>
+ That CUPS is 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 allowed by it. 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 for Non-PostScript Printers</title>
+
+ <para>
+ <indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>non-PostScript</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>RIP</primary></indexterm>
+<indexterm><primary>Ghostscript</primary></indexterm>
+<indexterm><primary>device-specific commands</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 that
+ 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-PostScript 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 autoconstruct 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
+ 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 Table 21.1<link linkend="cups-ppds"></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 24-pin impact printers and compatible </entry> </row>
+
+ <row><entry>epson24.ppd</entry> <entry>Epson 24-pin impact printers and compatible </entry> </row>
+
+ <row><entry>okidata9.ppd</entry> <entry>Okidata 9-pin impact printers and compatible </entry> </row>
+
+ <row><entry>okidat24.ppd</entry> <entry>Okidata 24-pin 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 </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>
+<indexterm><primary>pstoraster</primary></indexterm>
+ 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 is 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, and some are proprietary.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ Often this produces better quality (and has several more advantages) than other methods.
+ This is shown in <link linkend="cupsomatic-dia"> the cupsomatic/foomatic Processing Versus Native CUPS
+ illustration</link>.
+ </para>
+
+ <figure id="cupsomatic-dia">
+ <title>cupsomatic/foomatic Processing Versus Native CUPS.</title>
+ <imagefile>10small</imagefile>
+ </figure>
+
+ <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, maintained, or supported. It now been
+ replaced by <parameter>foomatic-rip</parameter>. <parameter>foomatic-rip</parameter> is a complete rewrite
+ of the old <parameter>cupsomatic</parameter> idea, but very much improved and generalized to
+ other (non-CUPS) spoolers. An upgrade to <parameter>foomatic-rip</parameter> 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>
+ Like the old <parameter>cupsomatic</parameter> method, the <parameter>foomatic-rip</parameter> (new) method
+ from Linuxprinting.org uses 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>
+<indexterm><primary>cupsomatic</primary></indexterm>
+<indexterm><primary>pstoraster</primary></indexterm>
+<indexterm><primary>rastertosomething</primary></indexterm>
+<indexterm><primary>rasterization</primary></indexterm>
+<indexterm><primary>Foomatic/cupsomatic</primary></indexterm>
+<indexterm><primary>rendering</primary></indexterm>
+ <parameter>cupsomatic</parameter> kidnaps the print file after the
+ <parameter>application/vnd.cups-postscript</parameter> stage and deviates it through the CUPS-external,
+ systemwide Ghostscript installation. Therefore, the print file 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. <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>
+<indexterm><primary>HP JetDirect</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>two-up</primary></indexterm>
+<indexterm><primary>duplex</primary></indexterm>
+ Assume you want to print a PDF file to an HP JetDirect-connected
+ PostScript printer, but you want to print pages 3-5, 7, and 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 autotyped as
+ <parameter>application/pdf</parameter>.</para></listitem>
+
+ <listitem><para>The file therefore must first pass the
+ <parameter>pdftops</parameter> prefilter, 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 pages
+ 2-5, 7, and 11-13, creates the imposed layout <quote>two pages on one 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 shown in <link linkend="pdftosocket">the PDF to socket chain
+ illustration</link>.
+ </para>
+
+<indexterm><primary>pdftosocket</primary></indexterm>
+ <figure id="pdftosocket">
+ <title>PDF to Socket Chain.</title>
+ <imagefile>pdftosocket</imagefile>
+ </figure>
+
+ <para>
+<indexterm><primary>USB</primary></indexterm>
+<indexterm><primary>Epson Stylus</primary></indexterm>
+<indexterm><primary>stphoto2.ppd</primary></indexterm>
+ 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 autotyped as
+ <parameter>application/pdf</parameter>.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>pdftops</primary></indexterm>
+<indexterm><primary>PDF</primary></indexterm>
+ The file must first pass the <parameter>pdftops</parameter> prefilter, 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>
+<indexterm><primary>pstops</primary></indexterm>
+<indexterm><primary>duplex printing</primary></indexterm>
+ 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 the 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, 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 <parameter>pstoraster</parameter> stage and becomes MIME type
+ <parameter>application/cups-raster</parameter>.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>rastertoepson</primary></indexterm>
+ 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 shown in <link linkend="pdftoepsonusb">the PDF to USB Chain
+ illustration</link>.
+ </para>
+
+ <figure id="pdftoepsonusb">
+ <title>PDF to USB Chain.</title>
+ <imagefile>pdftoepsonusb</imagefile>
+ </figure>
+ </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 1,000 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://www.easysw.com/printpro/">ESP PrintPro</ulink>
+ (commercial, non-free) is packaged with more than 3,000 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
+ other 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.de/english.html/">TurboPrint </ulink> (shareware, non-free) supports
+ roughly the same number 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 approximately 150 of HP's own printers and also provides
+ 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 provide 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>
+<indexterm><primary>PCL</primary></indexterm>
+<indexterm><primary>lpadmin</primary></indexterm>
+ CUPS also supports the use of <quote>interface scripts</quote> as known from
+ System V AT&amp;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 role similar to
+ PPDs for PostScript printers. Interface scripts may inject the Escape
+ sequences as required into the print data stream if the user, for example, selects
+ a certain paper tray, or changes paper orientation, or uses A3
+ paper. Interface 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:
+<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
+ use of interface scripts is 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 in <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 job file 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 is available. It is sufficient to have the Windows client drivers available and
+installed on the clients. This is illustrated in <link linkend="small11">the Print Driver Execution on the
+Client diagram</link>.
+</para>
+
+<figure id="small11">
+ <title>Print Driver Execution on the Client.</title>
+ <imagefile>11small</imagefile>
+</figure>
+
+</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.
+This is illustrated in <link linkend="small12">the Print Driver Execution on the Server diagram</link>.
+</para>
+
+ <figure id="small12">
+ <title>Print Driver Execution on the Server.</title>
+ <imagefile>12small</imagefile>
+ </figure>
+
+<para>
+However, something similar is possible with CUPS, so read on.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Network Printing (Windows Clients and 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's
+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 <parameter>[global]</parameter> 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&amp;T command set, with the -oraw option automatically passing through (if you want your own defined print
+commands to work with a Samba server that has CUPS support compiled in, simply use <smbconfoption
+name="classicalprinting">sysv</smbconfoption>). This is illustrated in <link linkend="13small">the Printing via
+CUPS/Samba Server diagram</link>.
+</para>
+
+ <figure id="13small">
+ <title>Printing via CUPS/Samba Server.</title>
+ <imagefile>13small</imagefile>
+ </figure>
+</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 spool 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 directory and resets it to healthy values with every restart. We have seen quite a
+few people who used a common spooling space for Samba and CUPS, and struggled 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 it runs 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 &smbmdash; if you own
+a PostScript printer, that is. PPD files 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 use 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, because 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 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 them 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>
+Windows NT printer drivers, which run in <quote>kernel mode</quote>, introduce 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 soundcard 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 until now there have been only two different PostScript drivers: the
+one 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 an attempt to work around problems, 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 number of printer options available for clients to use. 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 now 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) choose
+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, Even in Kernel
+Mode</title>
+
+<para>
+<indexterm><primary>DDK</primary></indexterm>
+<indexterm><primary>W32X86</primary></indexterm>
+<indexterm><primary>PostScript</primary></indexterm>
+<indexterm><primary>Visual Studio</primary></indexterm>
+<indexterm><primary>Microsoft driver</primary></indexterm>
+<indexterm><primary>Adobe</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 <link linkend="classicalprinting">Classical Printing</link>. In reality, this is a pure Samba
+business and relates only to the Samba-Windows client relationship.
+</para>
+
+<sect2>
+<title><emphasis>cupsaddsmb</emphasis>: The Unknown Utility</title>
+
+
+<para>
+<indexterm><primary>cupsaddsmb</primary></indexterm>
+The <parameter>cupsaddsmb</parameter> utility (shipped with all current CUPS versions) is an alternative
+method to transfer printer drivers into the Samba <smbconfsection name="[print$]"/> share. Remember, this
+share is where clients expect drivers deposited and set up 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 because 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 the 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 &smb.conf; for cupsaddsmb Usage</link>.
+</para>
+
+<example id="cupsadd-ex">
+<title>smb.conf for cupsaddsmb Usage</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+</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 package 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-based 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:
+<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 untar 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:
+<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:
+<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:
+<screen>
+&rootprompt;<userinput>cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/</userinput>
+</screen></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>
+<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 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 for Visual Studio and a DDK will be able to compile for himself or 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>
+
+<itemizedlist>
+ <listitem><para>cups.hlp</para></listitem>
+ <listitem><para>cupsdrvr.dll</para></listitem>
+ <listitem><para>cupsui.dll</para></listitem>
+</itemizedlist>
+
+<para>
+Adobe drivers are available for the older Windows 95/98/Me as well as
+for 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>
+
+<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>Windows NT, 2000, and XP are supported by:</para>
+
+<itemizedlist>
+ <listitem><para>ADOBEPS5.DLL</para></listitem>
+ <listitem><para>ADOBEPSU.DLL</para></listitem>
+ <listitem><para>ADOBEPSU.HLP</para></listitem>
+</itemizedlist>
+
+<note><para>
+<indexterm><primary>Adobe driver files</primary></indexterm>
+If both the Adobe driver files and the CUPS driver files for the support of Windows NT/200x/XP are presently
+installed on the server, the Adobe files will be ignored and the CUPS files 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. You probably 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, which you can get 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 the ESP print drivers package as an alternative to the
+Adobe PostScript drivers. To do so, 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">Easy Software</ulink> web site.
+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 selecting <guilabel>Export Driver...</guilabel> from
+the menu. Of course, you need to have prepared Samba beforehand to handle the driver files; that is, set up
+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>
+<indexterm><primary>cups.hlp</primary></indexterm>
+<indexterm><primary>WIN40</primary></indexterm>
+<indexterm><primary>W32X86</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>
+<indexterm><primary>Domain Controller</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>
+<indexterm><primary>Adobe PostScript</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, because 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>
+<indexterm><primary>CUPS PostScript</primary></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="classicalprinting">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 CUPS:
+</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?</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 print file starts with <parameter>&lt;1B
+ &gt;%-12345X</parameter> or <parameter>&lt;escape&gt;%-12345X</parameter> instead of
+ <parameter>%!PS</parameter>. This leads to the CUPS daemon autotyping 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 misconfigure the
+<indexterm><primary>Adobe driver</primary></indexterm>
+ 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
+<indexterm><primary>CUPS PostScript driver</primary></indexterm>
+ clients to the CUPS server is guaranteed to autotype
+ 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>
+ <indexterm><primary>banner pages</primary></indexterm>
+ 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 sorts of beneficial extensions on the CUPS side, but which will
+ not disturb any other applications because 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:
+<indexterm><primary>banner pages</primary></indexterm>
+<indexterm><primary>cupsaddsmb</primary></indexterm>
+<screen>
+&rootprompt;<userinput>cupsaddsmb -U root infotec_IS2027</userinput>
+Password for root required to access localhost via Samba: <userinput>['secret']</userinput>
+</screen></para>
+
+<para>
+<indexterm><primary>cupsaddsmb</primary></indexterm>
+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:
+<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>
+
+<warning><para>
+You will see the root password for the Samba account printed on screen.
+</para></warning>
+
+<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 may discover error messages like NT_STATUS_OBJECT_NAME_COLLISION in the output.
+This will occur when the directories WIN40 and W32X86 already existed in the <smbconfsection name="[print$]"/>
+driver download share (from a previous driver installation). These are harmless warning messages.
+</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):
+<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 at 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 printer
+drivers had problems installing properly. 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.
+Setting it to <quote>no</quote> will solve the problem. Refer to the &smb.conf; man page for explanation of
+the <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 against use of 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>
+<indexterm><primary>PDC</primary></indexterm>
+Can't get the standard <command>cupsaddsmb</command> command to run on a Samba PDC? Are you asked for the
+password credential 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>
+<indexterm><primary>raw print</primary></indexterm>
+<link linkend="small14">The 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 print queues!
+</para>
+
+ <figure id="small14">
+ <title>cupsaddsmb Flowchart.</title>
+ <imagefile>14small</imagefile></figure>
+</sect2>
+
+<sect2>
+<title>Installing the PostScript Driver on a Client</title>
+
+<para>
+<indexterm><primary>point'n'print</primary></indexterm>
+<indexterm><primary>cupsaddsmb</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>
+<indexterm><primary>Adobe PostScript driver</primary></indexterm>
+<indexterm><primary>net use lpt1:</primary></indexterm>
+<command>cupsaddsmb</command> will only reliably work with CUPS version 1.1.15 or higher and with Samba
+version 2.2.4, or later. 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:
+<screen>
+&dosprompt;<userinput>net use lpt1: \\sambaserver\printershare /user:ntadmin</userinput>
+</screen>
+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 LanMan way (not using MS-RPC).
+</para>
+</sect2>
+
+<sect2 id="cups-avoidps1">
+<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 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>, and <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>
+<indexterm><primary>adddriver</primary></indexterm>
+<indexterm><primary>AddPrinterDriver()</primary></indexterm>
+<indexterm><primary>getdriverdir</primary></indexterm>
+<command>adddriver &lt;arch&gt; &lt;config&gt;</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:
+<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 entered 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
+drivers can use a bidirectional 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 before adding the driver or else the
+RPC will fail.
+</para>
+
+<para>
+<indexterm><primary>setdriver</primary></indexterm>
+<indexterm><primary>SetPrinter()</primary></indexterm>
+<command>setdriver &lt;printername&gt; &lt;drivername&gt;</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>
+<indexterm><primary>enumprinters</primary></indexterm>
+<indexterm><primary>enumdrivers</primary></indexterm>
+See also the <command>enumprinters</command> and <command>enumdrivers</command> commands to
+obtain a list of installed printers and drivers.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Understanding the rpcclient man Page</title>
+
+<para>
+<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm>
+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:
+<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>&lt;config&gt;</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 call 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> 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
+listening to 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.
+</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:
+<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:
+<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>
+<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm>
+<indexterm><primary>cupsaddsmb</primary></indexterm>
+<indexterm><primary>setdriver</primary></indexterm>
+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> 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 set up 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. Because 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. Alternatively, 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 a
+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 ends 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><title>Tell Samba which printer should use these driver files (<command>setdriver</command>).</title></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 printer name (print queue) to any driver, this is a convenient way to set up 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 that <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. Another 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 appear 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>, and 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 &quot;\\sambaserver\mysmbtstprn&quot;</userinput>
+</screen>
+If it does not work, it could be a permissions problem with the <smbconfsection name="[print$]"/> share.
+</para>
+</step>
+
+<step>
+<title>(Optional) Print a test page.</title>
+
+<indexterm><primary>rundll32</primary></indexterm>
+<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..." &gt;&gt; /var/log/samba/log.smbd</userinput>
+</screen></para>
+</step>
+</procedure>
+</sect2>
+
+<sect2>
+<title>Troubleshooting Revisited</title>
+
+<para>
+<indexterm><primary>adddriver</primary></indexterm>
+The setdriver command will fail if in Samba's mind the queue is not
+already there. A successful installation displys the promising message that the:
+<screen>
+Printer Driver ABC successfully installed.
+</screen>
+following the <command>adddriver</command> parts of the procedure. But you may also see
+a disappointing message like this one:
+<computeroutput>
+result was NT_STATUS_UNSUCCESSFUL
+</computeroutput></para>
+
+<para>
+<indexterm><primary>lpstat</primary></indexterm>
+<indexterm><primary>rpcclient</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:
+<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:
+<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 stands for 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 <command>smbds</command> 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 could 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 setups unless 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:
+<screen>
+&rootprompt;<userinput>tdbbackup</userinput>
+ Usage: tdbbackup [options] &lt;fname...&gt;
+
+ 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:
+<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>. Alternatively, 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>
+<indexterm><primary>cupsomatic</primary></indexterm>
+<indexterm><primary>Adobe PPD</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 with 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 from the <ulink
+url="http://www.linuxprinting.org/">Linuxprinting.org</ulink> to create their printing-related software
+(which, by the way, works on all UNIXes and on Mac OS X and Darwin, too). The utilities from this sire have 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">1,000 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>
+<indexterm><primary>Windows PPD</primary></indexterm>
+At present, there are 690 devices dubbed as working perfectly: 181 are <emphasis>mostly</emphasis> perfect, 96
+are <emphasis>partially</emphasis> perfect, 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 multifunctional 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/">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. 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&amp;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&amp;show=0">PDQ-O-Matic</ulink> (for PDQ)
+and <ulink url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&amp;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&amp;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&amp;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>
+<indexterm><primary>PPDs</primary></indexterm>
+<indexterm><primary>Foomatic tutorial</primary></indexterm>
+<indexterm><primary>LinuxKongress2002</primary></indexterm>
+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>
+<indexterm><primary>foomatic-rip</primary></indexterm>
+<indexterm><primary>Adobe</primary></indexterm>
+<indexterm><primary>printer drivers</primary></indexterm>
+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>
+<indexterm><primary>Linuxprinting.org</primary></indexterm>
+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:
+</para>
+
+<itemizedlist>
+ <listitem><para>
+<indexterm><primary>Omni</primary></indexterm>
+ <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 its 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>
+<indexterm><primary>HPIJS</primary></indexterm>
+ <ulink url="http://hpinkjet.sf.net/">HPIJS</ulink> &smbmdash;
+ a free software project by HP to provide the support for its 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>
+<indexterm><primary>Gimp-Print</primary></indexterm>
+ <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 (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 is 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>
+<indexterm><primary>Mandriva</primary></indexterm>
+<indexterm><primary>Mandrake</primary></indexterm>
+<indexterm><primary>Conectiva</primary></indexterm>
+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, many additional contributions came from engineers with SuSE, Red
+Hat, Conectiva, Debian, and others. Vendor-neutrality is an important goal of the Foomatic project. Mandrake
+and Conectiva have merged and are now called Mandriva.
+</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>
+<indexterm><primary>Foomatic database</primary></indexterm>
+<indexterm><primary>XML-based datasets</primary></indexterm>
+<indexterm><primary>kprinter</primary></indexterm>
+<indexterm><primary>gtklp</primary></indexterm>
+<indexterm><primary>xpp</primary></indexterm>
+<indexterm><primary>HP Photosmart</primary></indexterm>
+<indexterm><primary>Epson Stylus inkjet</primary></indexterm>
+<indexterm><primary>non-PostScript printers</primary></indexterm>
+<indexterm><primary>raster</primary></indexterm>
+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 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 an 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-PostScript 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
+ author of 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>spoolerless</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&amp;printer=HP-LaserJet_4_Plus&amp;show=1">http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&amp;printer=HP-LaserJet_4_Plus&amp;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&amp;printer=HP-LaserJet_4_Plus&amp;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 browser's 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 reconstruct a good command line
+ for that darned printing script, but can't remember the exact
+ syntax. </para></listitem>
+
+ <listitem><para>Sometime 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&amp;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 job file. foomatic-rip is able to read and act upon these and uses some
+specially encoded Foomatic comments embedded in the job file. 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 them 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 can 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>:
+<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 no more than 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.org 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>
+<indexterm><primary>Adobe PostScript</primary></indexterm>
+<indexterm><primary>pstops</primary></indexterm>
+<indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>pstoraster</primary></indexterm>
+<indexterm><primary>PJL-header</primary></indexterm>
+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 and later releases, you can use the CUPS PostScript driver for Windows 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>Page number</para></listitem>
+
+ <listitem><para>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, billed to
+<parameter>#marketing</parameter>, and 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 1,000 and the job is aborted by the printer, the page count will
+ still show the figure of 1,000 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 1,000 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>
+
+<sect2>
+<title>Other Accounting Tools</title>
+
+<para>
+Other accounting tools that can be used includes: PrintAnalyzer, pyKota, printbill, LogReport.
+For more information regarding these tools you can try a Google search.
+</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 the 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. <parameter>cupsomatic</parameter> bypasses <parameter>pstoraster</parameter>, kidnaps the print file from CUPS,
+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 <parameter>cupsomatic</parameter> 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 autotyped
+<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 PostScript printers. If you
+want to print PostScript code on non-PostScript 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>Autodeletion or Preservation of CUPS Spool Files</title>
+
+<para>
+<indexterm><primary>/var/spool/samba</primary></indexterm>
+<indexterm><primary>/var/spool/cups/</primary></indexterm>
+<indexterm><primary>cupsd.conf</primary></indexterm>
+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 does 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><quote>MaxJobs 500</quote></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>Preconditions</title>
+
+<para>
+For everything to work as it should, 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"/>, and
+<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>
+<indexterm><primary>smbspool</primary></indexterm>
+<indexterm><primary>backends</primary></indexterm>
+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:
+<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 -&gt; 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 -&gt; /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 -&gt; /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:
+<screen>
+&rootprompt;<userinput>ln -s `which smbspool` /usr/lib/cups/backend/smb</userinput>
+</screen></para>
+
+<para>
+<indexterm><primary>smbspool</primary></indexterm>
+<indexterm><primary>troubleshooting</primary></indexterm>
+<command>smbspool</command> was 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>
+<indexterm><primary>PostScript printers</primary></indexterm>
+<indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>Windows NT PostScript driver</primary></indexterm>
+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. 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 diagrams in <link linkend="cups1">Filtering Chain 1</link> and <link linkend="cups2">Filtering Chain with
+cupsomatic</link> show how CUPS handles print jobs.
+</para>
+
+<figure id="cups1">
+ <title>Filtering Chain 1.</title>
+ <imagefile>cups1</imagefile>
+</figure>
+
+<!-- JJJ -->
+<figure id="cups2">
+ <title>Filtering Chain with cupsomatic</title>
+ <imagefile scale="45">cups2</imagefile>
+</figure>
+
+</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 set <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> Emit Error</title>
+
+ <para>
+ If <command>cupsaddsmb</command>, or <command>rpcclient addriver</command> emit the error message
+ WERR_BAD_PASSWORD, refer to <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 <literal>&lt;Location
+ /printers&gt;....&lt;/Location&gt;</literal> 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 bytes transferred 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 try. And you do not see a 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>
+<indexterm><primary>smbstatus</primary></indexterm>
+You see per <command>smbstatus</command> that you are connected as user nobody, but you want to be root or
+printer admin. This is probably due to <smbconfoption name="map to guest">bad user</smbconfoption>, which
+silently connected 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>
+
+<indexterm><primary>Local security policies</primary></indexterm>
+<indexterm><primary>unsigned drivers</primary></indexterm>
+<para>Local security policies may not allow the installation of unsigned drivers &smbmdash; <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>
+<indexterm><primary>SMB printers</primary></indexterm>
+<indexterm><primary>IPP client</primary></indexterm>
+Windows XP handles SMB printers on a <quote>per-user</quote> basis.
+This means every user needs to install the printer himself or herself. 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 &amp; 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 correct 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>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 step <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. to C.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>).
+</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. If the <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 in <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 <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> Mishandles 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>
+<indexterm><primary>lp</primary></indexterm>
+<indexterm><primary>Implicit Classes</primary></indexterm>
+<indexterm><primary>BrowseShortNames</primary></indexterm>
+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-balance 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 that person's
+jobs and send your own to his or her 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>, which 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 CUPS
+Printing Overview diagram</link>.
+</para>
+
+<figure id="a_small">
+ <title>CUPS Printing Overview.</title>
+ <imagefile scale="45">a_small</imagefile>
+</figure>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-ChangeNotes.xml b/docs-xml/Samba3-HOWTO/TOSHARG-ChangeNotes.xml
new file mode 100644
index 0000000000..6c2af32a75
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-ChangeNotes.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="ChangeNotes">
+<chapterinfo>
+ &author.jht;
+ &author.jerry;
+</chapterinfo>
+
+<title>Important and Critical Change Notes for the Samba 3.x Series</title>
+<para>
+Please read this chapter carefully before update or upgrading Samba. You should expect to find only critical
+or very important information here. Comprehensive change notes and guidance information can be found in the
+section <link linkend="upgrading-to-3.0">Updating and Upgrading Samba</link>.
+</para>
+
+<sect1>
+
+<title>Important Samba-3.2.x Change Notes</title>
+<para>
+!!!!!!!!!!!!Add all critical update notes here!!!!!!!!!!!!!
+</para>
+
+</sect1>
+
+<sect1>
+
+<title>Important Samba-3.0.x Change Notes</title>
+<para>
+These following notes pertain in particular to Samba 3.0.23 through Samba 3.0.25c (or more recent 3.0.25
+update). Samba is a fluid and ever changing project. Changes throughout the 3.0.x series release are
+documented in this documention - See <link linkend="oldupdatenotes">Upgrading from Samba-2.x to Samba-3.0.25</link>.
+</para>
+
+<para>
+Sometimes it is difficult to figure out which part, or parts, of the HOWTO documentation should be updated to
+reflect the impact of new or modified features. At other times it becomes clear that the documentation is in
+need of being restructured.
+</para>
+
+<para>
+In recent times a group of Samba users has joined the thrust to create a new <ulink
+url="http://wiki.samba.org/">Samba Wiki</ulink> that is slated to become the all-singing and all-dancing
+new face of Samba documentation. Hopefully, the Wiki will benefit from greater community input and
+thus may be kept more up to date. Until that golden dream materializes and matures it is necessary to
+continue to maintain the HOWTO. This chapter will document major departures from earlier behavior until
+such time as the body of this HOWTO is restructured or modified.
+</para>
+
+<para>
+This chapter is new to the release of the HOWTO for Samba 3.0.23. It includes much of the notes provided
+in the <filename>WHATSNEW.txt</filename> file that is included with the Samba source code release tarball.
+</para>
+
+<sect2>
+<title>User and Group Changes</title>
+
+<para>
+The change documented here affects unmapped user and group accounts only.
+</para>
+
+<para>
+<indexterm><primary>user</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>Relative Identifiers</primary><see>RID</see></indexterm>
+<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>vampire</tertiary></indexterm>
+The user and group internal management routines have been rewritten to prevent overlaps of
+assigned Relative Identifiers (RIDs). In the past the has been a potential problem when
+either manually mapping Unix groups with the <command>net groupmap</command> command or
+when migrating a Windows domain to a Samba domain by executing:
+<command>net rpc vampire</command>.
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>net</primary><secondary>getlocalsid</secondary></indexterm>
+Unmapped users are now assigned a SID in the <literal>S-1-22-1</literal> domain and unmapped
+groups are assigned a SID in the <literal>S-1-22-2</literal> domain. Previously they were
+assigned a RID within the SAM on the Samba server. For a domain controller this would have been under the
+authority of the domain SID where as on a member server or standalone server, this would have
+been under the authority of the local SAM (see the man page for <command>net getlocalsid</command>).
+</para>
+
+<para>
+<indexterm><primary>unmapped users</primary></indexterm>
+<indexterm><primary>unmapped groups</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>NTFS</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+The result is that any unmapped users or groups on an upgraded Samba domain controller may
+be assigned a new SID. Because the SID rather than a name is stored in Windows security
+descriptors, this can cause a user to no longer have access to a resource for example if a
+file was copied from a Samba file server to a local Windows client NTFS partition. Any files
+stored on the Samba server itself will continue to be accessible because UNIX stores the UNIX
+GID and not the SID for authorization checks.
+</para>
+
+<para>
+An example helps to illustrate the change:
+</para>
+
+<para>
+<indexterm><primary>group mapping</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>ACL</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+Assume that a group named <emphasis>developers</emphasis> exists with a UNIX GID of 782. In this
+case this user does not exist in Samba's group mapping table. It would be perfectly normal for
+this group to be appear in an ACL editor. Prior to Samba-3.0.23, the group SID might appear as
+<literal>S-1-5-21-647511796-4126122067-3123570092-2565</literal>.
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>NTFS</primary></indexterm>
+<indexterm><primary>access</primary></indexterm>
+<indexterm><primary>group permissions</primary></indexterm>
+With the release of Samba-3.0.23, the group SID would be reported as <literal>S-1-22-2-782</literal>. Any
+security descriptors associated with files stored on a Windows NTFS disk partition will not allow access based
+on the group permissions if the user was not a member of the
+<literal>S-1-5-21-647511796-4126122067-3123570092-2565</literal> group. Because this group SID is
+<literal>S-1-22-2-782</literal> and not reported in a user's token, Windows would fail the authorization check
+even though both SIDs in some respect refer to the same UNIX group.
+</para>
+
+<para>
+<indexterm><primary>group mapping</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+The workaround for versions of Samba prior to 3.0.23, is to create a manual domain group mapping
+entry for the group <emphasis>developers</emphasis> to point at the
+<literal>S-1-5-21-647511796-4126122067-3123570092-2565</literal> SID. With the release of Samba-3.0.23 this
+workaround is no longer needed.
+</para>
+</sect2>
+
+<sect2>
+<title>Essential Group Mappings</title>
+<para>
+Samba 3.0.x series releases before 3.0.23 automatically created group mappings for the essential Windows
+domain groups <literal>Domain Admins, Domain Users, Domain Guests</literal>. Commencing with Samba 3.0.23
+these mappings need to be created by the Samba administrator. Failure to do this may result in a failure to
+correctly authenticate and recoognize valid domain users. When this happens users will not be able to log onto
+the Windows client.
+</para>
+
+<note><para>
+Group mappings are essentail only if the Samba servers is running as a PDC/BDC. Stand-alone servers do not
+require these group mappings.
+</para></note>
+
+<para>
+The following mappings are required:
+</para>
+
+<table frame="all" id="TOSH-domgroups">
+ <title>Essential Domain Group Mappings</title>
+ <tgroup align="center" cols="3">
+ <thead>
+ <row><entry>Domain Group</entry><entry>RID</entry><entry>Example UNIX Group</entry></row>
+ </thead>
+ <tbody>
+ <row><entry>Domain Admins</entry><entry>512</entry><entry>root</entry></row>
+ <row><entry>Domain Users</entry><entry>513</entry><entry>users</entry></row>
+ <row><entry>Domain Guests</entry><entry>514</entry><entry>nobody</entry></row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+When the POSIX (UNIX) groups are stored in LDAP, it may be desirable to call these <literal>domadmins, domusers,
+domguests</literal> respectively.
+</para>
+
+<para>
+For further information regarding group mappings see <link linkend="groupmapping">Group Mapping: MS Windows
+and UNIX</link>.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Passdb Changes</title>
+
+<para>
+<indexterm><primary>backends</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SQL</primary></indexterm>
+<indexterm><primary>XML</primary></indexterm>
+The <smbconfoption name="passdb backend"/> parameter no long accepts multiple passdb backends in a
+chained configuration. Also be aware that the SQL and XML based passdb modules have been
+removed in the Samba-3.0.23 release. More information regarding external support for a SQL
+passdb module can be found on the <ulink url="http://pdbsql.sourceforge.net/">pdbsql</ulink> web site.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Group Mapping Changes in Samba-3.0.23</title>
+
+<para>
+<indexterm><primary>default mapping</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>group mappings</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>domain groups</primary></indexterm>
+The default mapping entries for groups such as <literal>Domain Admins</literal> are no longer
+created when using an <literal>smbpasswd</literal> file or a <literal>tdbsam</literal> passdb
+backend. This means that it is necessary to explicitly execute the <command>net groupmap add</command>
+to create group mappings, rather than use the <command>net groupmap modify</command> method to create the
+Windows group SID to UNIX GID mappings. This change has no effect on winbindd's IDMAP functionality
+for domain groups.
+</para>
+
+</sect2>
+
+<sect2>
+<title>LDAP Changes in Samba-3.0.23</title>
+
+<para>
+<indexterm><primary>LDAP schema</primary></indexterm>
+<indexterm><primary>sambaSID</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>slapindex</primary></indexterm>
+<indexterm><primary>slapd.conf</primary></indexterm>
+There has been a minor update the Samba LDAP schema file. A substring matching rule has been
+added to the <literal>sambaSID</literal> attribute definition. For OpenLDAP servers, this
+will require the addition of <literal>index sambaSID sub</literal> to the
+<filename>slapd.conf</filename> configuration file. It will be necessary to execute the
+<command>slapindex</command> command after making this change. There has been no change to the
+actual data storage schema.
+</para>
+
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Compiling.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Compiling.xml
new file mode 100644
index 0000000000..130da819e8
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Compiling.xml
@@ -0,0 +1,590 @@
+<?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>
+ <pubdate> June 2005 </pubdate>
+</chapterinfo>
+
+<title>How to Compile Samba</title>
+
+<para>
+You can obtain the Samba source file from the
+<ulink url="http://samba.org/">Samba Web site</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 ViewCVS</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://viewcvs.samba.org/">http://viewcvs.samba.org/</ulink>.
+</para>
+</sect3>
+
+<sect3>
+<title>Access via Subversion</title>
+
+<para>
+<indexterm><primary>Subversion</primary></indexterm>
+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 check out 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
+ <screen>
+ <userinput>svn co svn://svnanon.samba.org/samba/trunk samba</userinput>.
+ </screen>
+ </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:
+ <screen>
+ <userinput>svn co svn://svnanon.samba.org/samba/branches/SAMBA_3_0 samba_3</userinput>.
+ </screen>
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Whenever you want to merge in the latest code changes, use the following command from within the Samba
+ directory:
+ <screen>
+ <userinput>svn update</userinput>
+ </screen>
+ </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, because rsync is capable of compressing data streams, but it is also more useful than FTP because
+ during a partial update it will transfer only the data that is missing plus a small overhead. 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 as 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>
+<indexterm><primary>PGP</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:
+<screen>
+&prompt;<userinput>gpg --import samba-pubkey.asc</userinput>
+</screen>
+and verify the Samba source code integrity with:
+<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>
+
+<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:
+<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>
+<indexterm><primary>configure</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/source
+&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 first 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 nonstandard location, then
+ remember to add the configure option
+ <option>--with-krb5=<replaceable>DIR</replaceable></option>.
+ </para>
+
+ <para>
+ After you run configure, make sure that the
+ <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 is 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 id="startingSamba">
+ <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/sbin/smbd smbd
+netbios-ns dgram udp wait root /usr/local/samba/sbin/nmbd nmbd
+</programlisting>
+ </para>
+
+<indexterm><primary>/etc/inetd.conf</primary></indexterm>
+ <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 runtime, but fails on some UNIXes.
+ </para></note>
+
+ <warning><para>
+ Many UNIXes only accept around 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:
+<indexterm><primary>killall</primary></indexterm>
+<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>
+<indexterm><primary>startsmb</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>
+
+<para><programlisting>
+#!/bin/sh
+/usr/local/samba/sbin/smbd -D
+/usr/local/samba/sbin/winbindd -B
+/usr/local/samba/sbin/nmbd -D
+</programlisting></para>
+
+ <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>
+
+ <sect3>
+ <title>Starting Samba for Red Hat Linux</title>
+
+ <para>
+ Red Hat Linux has not always included all Samba components in the standard installation.
+ So versions of Red Hat Linux do not install the winbind utility, even though it is present
+ on the installation CDROM media. Check to see if the <command>winbindd</command> is present
+ on the system:
+<screen>
+&rootprompt; ls /usr/sbin/winbindd
+/usr/sbin/winbindd
+</screen>
+ This means that the appropriate RPM package was installed. The following response means
+ that it is not installed:
+<screen>
+/bin/ls: /usr/sbin/winbind: No such file or directory
+</screen>
+ In this case, it should be installed if you intend to use <command>winbindd</command>. Search
+ the CDROM installation media for the samba-winbind RPM and install it following Red Hat
+ guidelines.
+ </para>
+
+ <para>
+ The process for starting Samba will now be outlined. Be sure to configure Samba's &smb.conf;
+ file before starting Samba. When configured, start Samba by executing:
+<screen>
+&rootprompt; service smb start
+&rootprompt; service winbind start
+</screen>
+ These steps will start &nmbd;, &smbd; and &winbindd;.
+ </para>
+
+ <para>
+ To ensure that these services will be automatically restarted when the system is rebooted
+ execute:
+<screen>
+&rootprompt; chkconfig smb on
+&rootprompt; chkconfig winbind on
+</screen>
+ Samba will be started automatically at every system reboot.
+ </para>
+
+ </sect3>
+
+ <sect3>
+ <title>Starting Samba for Novell SUSE Linux</title>
+
+ <para>
+ Novell SUSE Linux products automatically install all essential Samba components in a default installation.
+ Configure your &smb.conf; file, then execute the following to start Samba:
+<screen>
+&rootprompt; rcnmb start
+&rootprompt; rcsmb start
+&rootprompt; rcwinbind start
+</screen>
+ Now execute these commands so that Samba will be started automatically following a system
+ reboot:
+<screen>
+&rootprompt; chkconfig nmb on
+&rootprompt; chkconfig smb on
+&rootprompt; chkconfig winbind on
+</screen>
+ The Samba services will now be started automatically following a system reboot.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml b/docs-xml/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml
new file mode 100644
index 0000000000..f46cc8e181
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml
@@ -0,0 +1,392 @@
+<?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="cfgsmarts">
+<chapterinfo>
+ &author.jht;
+ <pubdate>June 30, 2005</pubdate>
+</chapterinfo>
+<title>Advanced Configuration Techniques</title>
+
+<para>
+<indexterm><primary>configuration techniques</primary></indexterm>
+<indexterm><primary>include</primary></indexterm>
+Since the release of the first edition of this book there have been repeated requests to better document
+configuration techniques that may help a network administrator to get more out of Samba. Some users have asked
+for documentation regarding the use of the <smbconfoption name="include">file-name</smbconfoption> parameter.
+</para>
+
+<para>
+<indexterm><primary>multiple servers</primary></indexterm>
+<indexterm><primary>multiple server personalities</primary></indexterm>
+Commencing around mid-2004 there has been increasing interest in the ability to host multiple Samba servers on
+one machine. There has also been an interest in the hosting of multiple Samba server personalities on one
+server.
+</para>
+
+<para>
+<indexterm><primary>technical reviewers</primary></indexterm>
+<indexterm><primary>reviewers</primary></indexterm>
+Feedback from technical reviewers made the inclusion of this chapter a necessity. So, here is an
+answer the questions that have to date not been adequately addressed. Additional user input is welcome as
+it will help this chapter to mature. What is presented here is just a small beginning.
+</para>
+
+<para>
+<indexterm><primary>multiple servers</primary></indexterm>
+<indexterm><primary>multiple hosting</primary></indexterm>
+<indexterm><primary>domain controllers</primary></indexterm>
+There are a number of ways in which multiple servers can be hosted on a single Samba server. Multiple server
+hosting makes it possible to host multiple domain controllers on one machine. Each such machine is
+independent, and each can be stopped or started without affecting another.
+</para>
+
+<para>
+<indexterm><primary>multiple servers</primary></indexterm>
+<indexterm><primary>DMS</primary></indexterm>
+<indexterm><primary>anonymous server</primary></indexterm>
+Sometimes it is desirable to host multiple servers, each with its own security mode. For example, a single
+UNIX/Linux host may be a domain member server (DMS) as well as a generic anonymous print server. In this case,
+only domain member machines and domain users can access the DMS, but even guest users can access the generic
+print server. Another example of a situation where it may be beneficial to host a generic (anonymous) server
+is to host a CDROM server.
+</para>
+
+<para>
+<indexterm><primary>separate servers</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+Some environments dictate the need to have separate servers, each with their own resources, each of which are
+accessible only by certain users or groups. This is one of the simple, but highly effective, ways that Samba
+can replace many physical Windows servers in one Samba installation.
+</para>
+
+<sect1>
+<title>Implementation</title>
+
+<para>
+</para>
+
+<sect2>
+<title>Multiple Server Hosting</title>
+
+<para>
+<indexterm><primary>multiple server hosting</primary></indexterm>
+<indexterm><primary>separate instances</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>recompiling</primary></indexterm>
+<indexterm><primary>TDB</primary></indexterm>
+The use of multiple server hosting involves running multiple separate instances of Samba, each with it's own
+configuration file. This method is complicated by the fact that each instance of &nmbd;, &smbd; and &winbindd;
+must have write access to entirely separate TDB files. The ability to keep separate the TDB files used by
+&nmbd;, &smbd; and &winbindd; can be enabled either by recompiling Samba for each server hosted so each has its
+own default TDB directories, or by configuring these in the &smb.conf; file, in which case each instance of
+&nmbd;, &smbd; and &winbindd; must be told to start up with its own &smb.conf; configuration file.
+</para>
+
+<para>
+<indexterm><primary>independent</primary></indexterm>
+<indexterm><primary>listen own socket</primary></indexterm>
+<indexterm><primary>socket</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+Each instance should operate on its own IP address (that independent IP address can be an IP Alias).
+Each instance of &nmbd;, &smbd; and &winbindd; should listen only on its own IP socket. This can be secured
+using the <smbconfoption name="socket address"/> parameter. Each instance of the Samba server will have its
+own SID also, this means that the servers are discrete and independent of each other.
+</para>
+
+<para>
+<indexterm><primary>multiple server hosting</primary></indexterm>
+<indexterm><primary>private dir</primary></indexterm>
+<indexterm><primary>pid directory</primary></indexterm>
+<indexterm><primary>lock directory</primary></indexterm>
+<indexterm><primary>interfaces</primary></indexterm>
+<indexterm><primary>bind interfaces only</primary></indexterm>
+<indexterm><primary>netbios name</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>socket address</primary></indexterm>
+The user of multiple server hosting is non-trivial, and requires careful configuration of each aspect of
+process management and start up. The &smb.conf; parameters that must be carefully configured includes:
+<smbconfoption name="private dir"/>, <smbconfoption name="pid directory"/>,<smbconfoption name="lock
+directory"/>, <smbconfoption name="interfaces"/>, <smbconfoption name="bind interfaces only"/>, <smbconfoption
+name="netbios name"/>, <smbconfoption name="workgroup"/>, <smbconfoption name="socket address"/>.
+</para>
+
+<para>
+<indexterm><primary>multiple servers</primary></indexterm>
+<indexterm><primary>contribute</primary></indexterm>
+<indexterm><primary>comprehensive documentation</primary></indexterm>
+Those who elect to create multiple Samba servers should have the ability to read and follow
+the Samba source code, and to modify it as needed. This mode of deployment is considered beyond the scope of
+this book. However, if someone will contribute more comprehensive documentation we will gladly review it, and
+if it is suitable extend this section of this chapter. Until such documentation becomes available the hosting
+of multiple samba servers on a single host is considered not supported for Samba-3 by the Samba Team.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Multiple Virtual Server Personalities</title>
+
+<para>
+<indexterm><primary>multiple virtual servers</primary></indexterm>
+<indexterm><primary>netbios alias</primary></indexterm>
+<indexterm><primary>meta-services</primary></indexterm>
+Samba has the ability to host multiple virtual servers, each of which have their own personality. This is
+achieved by configuring an &smb.conf; file that is common to all personalities hosted. Each server
+personality is hosted using its own <smbconfoption name="netbios alias"/> name, and each has its own distinct
+<smbconfoption name="[global]"/> section. Each server may have its own stanzas for services and meta-services.
+</para>
+
+<para>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>security</primary></indexterm>
+<indexterm><primary>netbios aliases</primary></indexterm>
+When hosting multiple virtual servers, each with their own personality, each can be in a different workgroup.
+Only the primary server can be a domain member or a domain controller. The personality is defined by the
+combination of the <smbconfoption name="security"/> mode it is operating in, the <smbconfoption name="netbios
+aliases"/> it has, and the <smbconfoption name="workgroup"/> that is defined for it.
+</para>
+
+<para>
+<indexterm><primary>NetBIOS name</primary></indexterm>
+<indexterm><primary>NetBIOS-less SMB</primary></indexterm>
+<indexterm><primary>smb ports</primary></indexterm>
+<indexterm><primary>TCP port 139</primary></indexterm>
+<indexterm><primary>TCP port 445</primary></indexterm>
+<indexterm><primary>%L</primary></indexterm>
+This configuration style can be used either with NetBIOS names, or using NetBIOS-less SMB over TCP services.
+If run using NetBIOS mode (the most common method) it is important that the parameter <smbconfoption name="smb
+ports">139</smbconfoption> should be specified in the primary &smb.conf; file. Failure to do this will result
+in Samba operating over TCP port 445 and problematic operation at best, and at worst only being able to obtain
+the functionality that is specified in the primary &smb.conf; file. The use of NetBIOS over TCP/IP using only
+TCP port 139 means that the use of the <literal>%L</literal> macro is fully enabled. If the <smbconfoption
+name="smb ports">139</smbconfoption> is not specified (the default is <parameter>445 139</parameter>, or if
+the value of this parameter is set at <parameter>139 445</parameter> then the <literal>%L</literal> macro
+is not serviceable.
+</para>
+
+<para>
+<indexterm><primary>host multiple servers</primary></indexterm>
+<indexterm><primary>multiple personality</primary></indexterm>
+<indexterm><primary>NetBIOS-less</primary></indexterm>
+<indexterm><primary>%i macro</primary></indexterm>
+It is possible to host multiple servers, each with their own personality, using port 445 (the NetBIOS-less SMB
+port), in which case the <literal>%i</literal> macro can be used to provide separate server identities (by
+IP Address). Each can have its own <smbconfoption name="security"/> mode. It will be necessary to use the
+<smbconfoption name="interfaces"/>, <smbconfoption name="bind interfaces only"/> and IP aliases in addition to
+the <smbconfoption name="netbios name"/> parameters to create the virtual servers. This method is considerably
+more complex than that using NetBIOS names only using TCP port 139.
+</para>
+
+<para>
+<indexterm><primary>anonymous file server</primary></indexterm>
+Consider an example environment that consists of a standalone, user-mode security Samba server and a read-only
+Windows 95 file server that has to be replaced. Instead of replacing the Windows 95 machine with a new PC, it
+is possible to add this server as a read-only anonymous file server that is hosted on the Samba server. Here
+are some parameters:
+</para>
+
+<para>
+The Samba server is called <literal>ELASTIC</literal>, its workgroup name is <literal>ROBINSNEST</literal>.
+The CDROM server is called <literal>CDSERVER</literal> and its workgroup is <literal>ARTSDEPT</literal>. A
+possible implementation is shown here:
+</para>
+
+<para>
+<indexterm><primary>/etc/samba</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>smb.conf</primary></indexterm>
+The &smb.conf; file for the master server is shown in <link linkend="elastic">Elastic smb.conf File</link>.
+This file is placed in the <filename>/etc/samba</filename> directory. Only the &nmbd; and the &smbd; daemons
+are needed. When started the server will appear in Windows Network Neighborhood as the machine
+<literal>ELASTIC</literal> under the workgroup <literal>ROBINSNEST</literal>. It is helpful if the Windows
+clients that must access this server are also in the workgroup <literal>ROBINSNEST</literal> as this will make
+browsing much more reliable.
+</para>
+
+<example id="elastic">
+<title>Elastic smb.conf File</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">ROBINSNEST</smbconfoption>
+<smbconfoption name="netbios name">ELASTIC</smbconfoption>
+<smbconfoption name="netbios aliases">CDSERVER</smbconfoption>
+<smbconfoption name="smb ports">139</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>
+<smbconfoption name="include">/etc/samba/smb-%L.conf</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="[office]"/>
+<smbconfoption name="comment">Data</smbconfoption>
+<smbconfoption name="path">/data</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="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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>smb-cdserver.conf</primary></indexterm>
+The configuration file for the CDROM server is listed in <link linkend="cdserver">CDROM Server
+smb-cdserver.conf file</link>. This file is called <filename>smb-cdserver.conf</filename> and it should be
+located in the <filename>/etc/samba</filename> directory. Machines that are in the workgroup
+<literal>ARTSDEPT</literal> will be able to browse this server freely.
+</para>
+
+<example id="cdserver">
+<title>CDROM Server smb-cdserver.conf file</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">ARTSDEPT</smbconfoption>
+<smbconfoption name="netbios name">CDSERVER</smbconfoption>
+<smbconfoption name="map to guest">Bad User</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+
+<smbconfsection name="[carousel]"/>
+<smbconfoption name="comment">CDROM Share</smbconfoption>
+<smbconfoption name="path">/export/cddata</smbconfoption>
+<smbconfoption name="read only">Yes</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>different resources</primary></indexterm>
+<indexterm><primary>separate workgroups</primary></indexterm>
+<indexterm><primary>read-only access</primary></indexterm>
+<indexterm><primary>nobody account</primary></indexterm>
+The two servers have different resources and are in separate workgroups. The server <literal>ELASTIC</literal>
+can only be accessed by uses who have an appropriate account on the host server. All users will be able to
+access the CDROM data that is stored in the <filename>/export/cddata</filename> directory. File system
+permissions should set so that the <literal>others</literal> user has read-only access to the directory and its
+contents. The files can be owned by root (any user other than the nobody account).
+</para>
+
+</sect2>
+
+<sect2>
+<title>Multiple Virtual Server Hosting</title>
+
+<para>
+<indexterm><primary>primary domain controller</primary></indexterm>
+<indexterm><primary>extra machine</primary></indexterm>
+<indexterm><primary>same domain/workgroup</primary></indexterm>
+In this example, the requirement is for a primary domain controller for the domain called
+<literal>MIDEARTH</literal>. The PDC will be called <literal>MERLIN</literal>. An extra machine called
+<literal>SAURON</literal> is required. Each machine will have only its own shares. Both machines belong to the
+same domain/workgroup.
+</para>
+
+<para>
+<indexterm><primary>master smb.conf</primary></indexterm>
+<indexterm><primary>/etc/samba</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+The master &smb.conf; file is shown in <link linkend="mastersmbc">the Master smb.conf File Global Section</link>.
+The two files that specify the share information for each server are shown in <link linkend="merlinsmbc">the
+smb-merlin.conf File Share Section</link>, and <link linkend="sauronsmbc">the smb-sauron.conf File Share
+Section</link>. All three files are locate in the <filename>/etc/samba</filename> directory.
+</para>
+
+<example id="mastersmbc">
+<title>Master smb.conf File Global Section</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">MERLIN</smbconfoption>
+<smbconfoption name="netbios aliases">SAURON</smbconfoption>
+<smbconfoption name="passdb backend">tdbsam</smbconfoption>
+<smbconfoption name="smb ports">139</smbconfoption>
+<smbconfoption name="syslog">0</smbconfoption>
+<smbconfoption name="printcap name">CUPS</smbconfoption>
+<smbconfoption name="show add printer wizard">No</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/usermod -G '%g' '%u'</smbconfoption>
+<smbconfoption name="add machine script">/usr/sbin/useradd -s /bin/false -d /var/lib/nobody '%u'</smbconfoption>
+<smbconfoption name="logon script">scripts\login.bat</smbconfoption>
+<smbconfoption name="logon path"> </smbconfoption>
+<smbconfoption name="logon drive">X:</smbconfoption>
+<smbconfoption name="domain logons">Yes</smbconfoption>
+<smbconfoption name="preferred master">Yes</smbconfoption>
+<smbconfoption name="wins support">Yes</smbconfoption>
+<smbconfoption name="printing">CUPS</smbconfoption>
+<smbconfoption name="include">/etc/samba/smb-%L.conf</smbconfoption>
+</smbconfblock>
+</example>
+
+<example id="merlinsmbc">
+<title>MERLIN smb-merlin.conf File Share Section</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">MERLIN</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="[office]"/>
+<smbconfoption name="comment">Data</smbconfoption>
+<smbconfoption name="path">/data</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+
+<smbconfsection name="[netlogon]"/>
+<smbconfoption name="comment">NETLOGON</smbconfoption>
+<smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption>
+<smbconfoption name="read only">Yes</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+
+<smbconfsection name="[printers]"/>
+<smbconfoption name="comment">All Printers</smbconfoption>
+<smbconfoption name="path">/var/spool/samba</smbconfoption>
+<smbconfoption name="printable">Yes</smbconfoption>
+<smbconfoption name="use client driver">Yes</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+</smbconfblock>
+</example>
+
+<example id="sauronsmbc">
+<title>SAURON smb-sauron.conf File Share Section</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">SAURON</smbconfoption>
+
+<smbconfsection name="[www]"/>
+<smbconfoption name="comment">Web Pages</smbconfoption>
+<smbconfoption name="path">/srv/www/htdocs</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+</smbconfblock>
+</example>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml b/docs-xml/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml
new file mode 100644
index 0000000000..f64a677159
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-DNS-DHCP-Configuration.xml
@@ -0,0 +1,346 @@
+<?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>
+<indexterm><primary>Dynamic Host Configuration Protocol</primary><see>DHCP</see></indexterm>
+<indexterm><primary>Domain Name System</primary><see>DNS</see></indexterm>
+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>
+<indexterm><primary>ADS</primary></indexterm>
+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 namespace
+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>
+<indexterm><primary>Dynamic DNS</primary><see>DDNS</see></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>
+This chapter provides 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>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>DHCP</primary></indexterm>
+<indexterm><primary>BIND9.NET</primary></indexterm>
+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 site 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 DNS, see the <ulink
+url="http://www.oreilly.com/catalog/dns/index.htm">O'Reilly</ulink> web site, and the <ulink
+url="http://www.bind9.net/books-dhcp">BIND9.NET</ulink> web site for details.
+The books are:
+</para>
+
+<orderedlist>
+ <listitem><para>DNS and BIND, By Cricket Liu, Paul Albitz, ISBN: 1-56592-010-4</para></listitem>
+ <listitem><para>DNS &amp; Bind Cookbook, By Cricket Liu, ISBN: 0-596-00410-9</para></listitem>
+ <listitem><para>The DHCP Handbook (2nd Edition), By: Ralph Droms, Ted Lemon, ISBN 0-672-32327-3</para></listitem>
+</orderedlist>
+
+</sect1>
+
+<sect1>
+<title>Example Configuration</title>
+
+<para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+The DNS is to the Internet what water is to life. Nearly all information resources (host names) are resolved
+to their Internet protocol (IP) addresses through DNS. 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) &smbmdash; an artifact of NetBIOS networking over the TCP/IP
+protocols &smbmdash; has demonstrated scalability problems as well as a flat, nonhierarchical namespace that
+became unmanageable as the size and complexity of information technology networks grew.
+</para>
+
+<para>
+<indexterm><primary>RFC 1001</primary></indexterm>
+<indexterm><primary>RFC 1002</primary></indexterm>
+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 startup. Alternatively, where DHCP is used to assign workstation IP addresses,
+it is possible to register hostnames and their IP address by the DHCP server as
+soon as a client acknowledges an IP address lease. Finally, 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.
+ </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 startup script
+ that is part of the operating system.
+<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>
+ </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:
+<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>
+ </para>
+
+ <para>
+ The <filename>/var/named/127.0.0.zone</filename> file:
+<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>
+ </para>
+
+ <para>
+ The <filename>/var/named/quenya.org.host</filename> file:
+<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>
+</para>
+
+<para>
+ The <filename>/var/named/192.168.1.0.rev</filename> file:
+<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>
+ </para>
+
+ <para>
+<indexterm><primary>BIND</primary></indexterm>
+<indexterm><primary>dynamic registration files</primary></indexterm>
+ The configuration files shown here 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>
+ <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>
+ </para>
+
+ <para>
+ In this 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-xml/Samba3-HOWTO/TOSHARG-Diagnosis.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Diagnosis.xml
new file mode 100644
index 0000000000..951c879b49
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Diagnosis.xml
@@ -0,0 +1,603 @@
+<?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>
+<indexterm><primary>validate</primary></indexterm>
+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: 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 for our examples 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>
+
+<example id="tmpshare">
+<title>smb.conf with [tmp] Share</title>
+<smbconfblock>
+<smbconfsection name="[tmp]"/>
+<smbconfoption name="comment">temporary files </smbconfoption>
+<smbconfoption name="path">/tmp</smbconfoption>
+<smbconfoption name="read only">yes</smbconfoption>
+</smbconfblock>
+</example>
+
+<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>
+<indexterm><primary>error messages</primary></indexterm>
+<indexterm><primary>name resolution</primary></indexterm>
+<indexterm><primary>/etc/resolv.conf</primary></indexterm>
+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>
+<indexterm><primary>DNS server access</primary></indexterm>
+<indexterm><primary>name resolution</primary></indexterm>
+<indexterm><primary>dns proxy</primary></indexterm>
+<indexterm><primary>testparm</primary></indexterm>
+Also, if you do not have DNS server access for name resolution, please check
+that the settings for your &smb.conf; file results in <parameter>dns proxy = no</parameter>. The
+best way to check this is with <command>testparm smb.conf</command>.
+</para>
+
+
+<para>
+<indexterm><primary>log files</primary></indexterm>
+<indexterm><primary>tail</primary></indexterm>
+<indexterm><primary>/usr/local/samba/var</primary></indexterm>
+<indexterm><primary>/var/log/samba</primary></indexterm>
+<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>
+<indexterm><primary>/etc/samba</primary></indexterm>
+<indexterm><primary>/usr/local/samba/lib</primary></indexterm>
+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>
+<indexterm><primary>ping</primary></indexterm>
+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>
+<indexterm><primary>/etc/hosts</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>/etc/resolv.conf</primary></indexterm>
+If you get a message saying <quote><errorname>host not found</errorname></quote> or a similar message, then
+your DNS software or <filename>/etc/hosts</filename> file is not correctly set up. If using DNS, check that
+the <filename>/etc/resolv.conf</filename> has correct, current, entries in it. 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>
+<indexterm><primary>firewall</primary></indexterm>
+<indexterm><primary>iptables</primary></indexterm>
+<indexterm><primary>ipchains</primary></indexterm>
+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>
+<indexterm><primary>iptables</primary></indexterm>
+<indexterm><primary>ipchains</primary></indexterm>
+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>
+<indexterm><primary>bad password</primary></indexterm>
+<indexterm><primary>hosts allow</primary></indexterm>
+<indexterm><primary>hosts deny</primary></indexterm>
+<indexterm><primary>valid users</primary></indexterm>
+<indexterm><primary>guest account</primary></indexterm>
+<indexterm><primary>invalid users</primary></indexterm>
+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>
+<indexterm><primary>inetd.conf</primary></indexterm>
+If you get a message <literal>connection refused</literal> 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 <literal>session request failed,</literal> 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>
+
+
+<example id="modif1">
+<title>Configuration for Allowing Connections Only from a Certain Subnet</title>
+<smbconfblock>
+<smbconfsection name="[globals]"/>
+<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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>loopback adapter</primary></indexterm>
+In <link linkend="modif1">Configuration for Allowing Connections Only from a Certain Subnet</link>, 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>
+
+<example id="modif2">
+<title>Configuration for Allowing Connections from a Certain Subnet and localhost</title>
+<smbconfblock>
+<smbconfsection name="[globals]"/>
+<smbconfoption name="hosts deny">ALL</smbconfoption>
+<smbconfoption name="hosts allow">xxx.xxx.xxx.xxx/yy 127.</smbconfoption>
+<smbconfoption name="interfaces">eth0 lo</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>inetd</primary></indexterm>
+<indexterm><primary>smbclient</primary></indexterm>
+Another common cause of these two errors is having something already running on port <constant>139</constant>,
+such as Samba (&smbd; is running from <application>inetd</application> already) or 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>
+<indexterm><primary>subnet mask</primary></indexterm>
+<indexterm><primary>broadcast address</primary></indexterm>
+<indexterm><primary>log.nmbd</primary></indexterm>
+<indexterm><primary>network interface</primary></indexterm>
+<indexterm><primary>IP address</primary></indexterm>
+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>
+<indexterm><primary>nmblookup</primary></indexterm>
+Run the command <command>nmblookup -B BIGSERVER __SAMBA__</command>.
+You should get back the IP address of your Samba server.
+</para>
+
+<para>
+<indexterm><primary>inetd.conf</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>port 137</primary></indexterm>
+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>
+<indexterm><primary>nmblookup</primary></indexterm>
+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 <literal>got a positive name query response</literal>
+messages from several hosts.
+</para>
+
+<para>
+<indexterm><primary>nmblookup</primary></indexterm>
+If this does not give a result similar 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 PC's 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 &smbmdash; 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 set up 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>
+<indexterm><primary>dir</primary></indexterm>
+<indexterm><primary>get</primary></indexterm>
+<indexterm><primary>put</primary></indexterm>
+<indexterm><primary>help command</primary></indexterm>
+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>
+<indexterm><primary>net view</primary></indexterm>
+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>
+<indexterm><primary>nmbd</primary></indexterm>
+If you get a message <literal>network name not found</literal> 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>
+ Fix 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. 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 error,
+it probably means that the host is not contactable via TCP services.
+Check to see if the host is running TCP wrappers, and if so, add an entry in
+the <filename>hosts.allow</filename> file for your client (or subnet, 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 username 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 setting 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-xml/Samba3-HOWTO/TOSHARG-DomainMember.xml b/docs-xml/Samba3-HOWTO/TOSHARG-DomainMember.xml
new file mode 100644
index 0000000000..c0f43ff130
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-DomainMember.xml
@@ -0,0 +1,1419 @@
+<?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>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>machine trust account</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+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>
+<indexterm><primary>domain membership</primary></indexterm>
+<indexterm><primary>misinformation</primary></indexterm>
+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 lack of knowledge. Hopefully
+this chapter will fill the voids.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>single sign-on</primary></indexterm>
+<indexterm><primary>SSO</primary></indexterm>
+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>native member</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>domain control</primary></indexterm>
+<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>
+ <indexterm><primary>access rights</primary></indexterm>
+ <indexterm><primary>file ownership</primary></indexterm>
+ <indexterm><primary>access controls</primary></indexterm>
+ <indexterm><primary>SAM</primary></indexterm>
+ 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>
+ <indexterm><primary>domain members</primary></indexterm>
+ <indexterm><primary>network logon</primary></indexterm>
+ Only <application>MS Windows NT4/200x/XP Professional</application>
+ workstations that are domain members can use network logon facilities.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>domain member</primary></indexterm>
+ <indexterm><primary>policy files</primary></indexterm>
+ <indexterm><primary>NTConfig.POL</primary></indexterm>
+ <indexterm><primary>desktop profiles</primary></indexterm>
+ Domain member workstations can be better controlled through the use of
+ policy files (<filename>NTConfig.POL</filename>) and desktop profiles.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>logon script</primary></indexterm>
+ <indexterm><primary>transparent access</primary></indexterm>
+ <indexterm><primary>application servers</primary></indexterm>
+ Through the use of logon scripts, users can be given transparent access to network
+ applications that run off application servers.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>user access management</primary></indexterm>
+ <indexterm><primary>SAM</primary></indexterm>
+ <indexterm><primary>LDAP</primary></indexterm>
+ <indexterm><primary>ADS</primary></indexterm>
+ 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>
+<indexterm><primary>authenticate</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>rogue user</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 trust account is to prevent a rogue user and domain controller from colluding to gain
+access to a domain member workstation.
+</para>
+
+<para>
+<indexterm><primary>machine trust account</primary><secondary>password</secondary></indexterm>
+<indexterm><primary>shared secret</primary></indexterm>
+<indexterm><primary>unauthorized</primary></indexterm>
+<indexterm><primary>Windows NT/200x/XP Professional</primary></indexterm>
+<indexterm><primary>Windows 9x/Me/XP Home</primary></indexterm>
+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, participating in domain security operations, 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>
+<indexterm><primary>Windows Registry</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Machine Trust Account</primary></indexterm>
+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>
+ <indexterm><primary>domain security account</primary></indexterm>
+ <indexterm><primary>account information</primary></indexterm>
+ <indexterm><primary>backend database</primary></indexterm>
+ 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>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>UNIX login ID</primary></indexterm>
+ <indexterm><primary>UID</primary></indexterm>
+ <indexterm><primary>LanMan</primary></indexterm>
+ <indexterm><primary>NT-encrypted password</primary></indexterm>
+ <indexterm><primary>UNIX user identifier</primary><see>UID</see></indexterm>
+ 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>
+ <indexterm><primary>database</primary></indexterm>
+ <indexterm><primary>ldapsam</primary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>account controls</primary></indexterm>
+ 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>
+ <indexterm><primary>UNIX account</primary></indexterm>
+ <indexterm><primary>/etc/passwd</primary></indexterm>
+ 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 has not been a feature
+ of the early releases of Samba-3, and is not currently planned for release either.
+ </para></listitem>
+</itemizedlist>
+</para>
+
+<?latex \newpage ?>
+<para>
+<indexterm><primary>Machine Trust Accounts</primary><secondary>creating</secondary></indexterm>
+There are three ways to create Machine Trust Accounts:
+</para>
+
+<itemizedlist>
+ <listitem><para>
+ <indexterm><primary>manual UNIX account creation</primary></indexterm>
+ 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>
+ <indexterm><primary>Nexus toolkit</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>
+ <indexterm><primary>Machine Trust Account</primary></indexterm>
+ <indexterm><primary>joined client</primary></indexterm>
+ <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>
+
+<para>
+<indexterm><primary>enforcing</primary></indexterm>
+<indexterm><primary>machine trust account</primary><secondary>creation</secondary></indexterm>
+Neither MS Windows NT4/200x/XP Professional, nor Samba, provide any method for enforcing the method of machine
+trust account creation. This is a matter of the administrator's choice.
+</para>
+
+<sect2>
+<title>Manual Creation of Machine Trust Accounts</title>
+
+<para>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary>useradd</primary></indexterm>
+<indexterm><primary>vipw</primary></indexterm>
+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>adduser</quote> command
+that is normally used to create new UNIX accounts. The following is an example for
+a Linux-based Samba server:
+<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>
+<indexterm><primary>primary group</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>machine accounts</primary></indexterm>
+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
+numeric GID is 100.
+</para>
+
+<para>
+<indexterm><primary>chpass</primary></indexterm>
+<indexterm><primary>BSD</primary></indexterm>
+On *BSD systems, this can be done using the <command>chpass</command> utility:
+<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>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>$</primary></indexterm>
+<indexterm><primary>null shell</primary></indexterm>
+<indexterm><primary>home directory</primary></indexterm>
+The <filename>/etc/passwd</filename> entry will list the machine name
+with a <quote>$</quote> appended, and 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:
+<programlisting>
+doppy$:x:505:100:<replaceable>machine_nickname</replaceable>:/dev/null:/bin/false
+</programlisting>
+</para>
+
+<para>
+<indexterm><primary>machine_nickname</primary></indexterm>
+<indexterm><primary>machine_name</primary></indexterm>
+<indexterm><primary>Machine Trust Account</primary></indexterm>
+in which <replaceable>machine_nickname</replaceable> can be any
+descriptive name for the client, such as 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>
+<indexterm><primary>UNIX account</primary></indexterm>
+<indexterm><primary>Samba account</primary></indexterm>
+<indexterm><primary>Machine Trust Account</primary><secondary>password</secondary></indexterm>
+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:
+<screen>
+&rootprompt;<userinput>smbpasswd -a -m <replaceable>machine_name</replaceable></userinput>
+</screen>
+</para>
+
+<para>
+<indexterm><primary>machine_name</primary></indexterm>
+<indexterm><primary>NetBIOS name</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+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>
+<indexterm><primary>Machine Trust Account</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>Server Manager</primary></indexterm>
+<indexterm><primary>changes password</primary></indexterm>
+<indexterm><primary>NetBIOS name</primary></indexterm>
+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>
+<indexterm><primary>machine trust accounts</primary></indexterm>
+<indexterm><primary>automatic account creation</primary></indexterm>
+<indexterm><primary>Server Manager</primary></indexterm>
+A working <smbconfoption name="add machine script"/> is essential
+for machine trust accounts to be automatically created. This applies no matter whether
+you use automatic account creation or the NT4 Domain Server Manager.
+</para>
+
+<para>
+<indexterm><primary>SRVTOOLS.EXE</primary></indexterm>
+<indexterm><primary>SrvMgr.exe</primary></indexterm>
+<indexterm><primary>UsrMgr.exe</primary></indexterm>
+<indexterm><primary>domain management tools</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>
+<indexterm><primary>Microsoft Windows 9x/Me</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, it will unpack the same tools but for use on
+this platform.
+</para>
+
+<para>
+Further information about these tools may be obtained from Knowledge Base articles
+<ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;173673">173673</ulink>, and
+<ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;172540">172540</ulink>
+</para>
+
+<para>
+<indexterm><primary>srvmgr.exe</primary></indexterm>
+<indexterm><primary>Server Manager for Domains</primary></indexterm>
+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>
+<indexterm><primary>Machine Trust Account</primary><secondary>creation</secondary></indexterm>
+The third (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>
+<indexterm><primary>Machine Trust Account</primary><secondary>UNIX account</secondary></indexterm>
+<indexterm><primary>UNIX account</primary></indexterm>
+<indexterm><primary>add machine script</primary></indexterm>
+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>
+<indexterm><primary>useradd</primary></indexterm>
+<indexterm><primary>Red Hat Linux</primary></indexterm>
+Here is an example for a Red Hat Linux system:
+<smbconfblock>
+<smbconfsection name="[global]"/>
+<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>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>machine trust account</primary><secondary>create privilege</secondary></indexterm>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>root</primary></indexterm>
+ 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>
+<indexterm><primary>administrator account</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+ 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>
+<indexterm><primary>account</primary></indexterm>
+<indexterm><primary>create domain member</primary></indexterm>
+<indexterm><primary>root</primary></indexterm>
+<indexterm><primary>map</primary></indexterm>
+ The name of the account that is used to create domain member machine trust 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>
+<indexterm><primary>administrator account</primary></indexterm>
+<indexterm><primary>encryption key</primary></indexterm>
+<indexterm><primary>machine trust account</primary></indexterm>
+ 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>
+<indexterm><primary>Machine Trust Account</primary></indexterm>
+<indexterm><primary>Create a Computer Account</primary></indexterm>
+<indexterm><primary>join the machine</primary></indexterm>
+ 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>
+<indexterm><primary>Machine Trust Account</primary></indexterm>
+<indexterm><primary>on the fly</primary></indexterm>
+<indexterm><primary>Computer Account</primary></indexterm>
+<indexterm><primary>administrator account</primary></indexterm>
+ 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>
+<indexterm><primary></primary></indexterm>
+ Joining a Samba client to a domain is documented in <link linkend="domain-member-server">the next section</link>.
+ </para>
+</sect3>
+
+</sect2>
+</sect1>
+
+<sect1 id="domain-member-server">
+<title>Domain Member Server</title>
+
+<para>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>security context</primary></indexterm>
+<indexterm><primary>authentication regime</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+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>
+<indexterm><primary>authentication</primary><secondary>backend</secondary></indexterm>
+<indexterm><primary>distributed directory</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>iPlanet</primary></indexterm>
+<indexterm><primary>Sun</primary></indexterm>
+<indexterm><primary>Novell</primary></indexterm>
+<indexterm><primary>e-Directory</primary></indexterm>
+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 Novell e-Directory
+Server, and so on.
+</emphasis>
+</para>
+
+<note><para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>identity management</primary></indexterm>
+<indexterm><primary>machine authentication</primary></indexterm>
+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>
+<indexterm><primary>create a domain machine account</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>join the domain</primary></indexterm>
+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">Assumptions</link> lists names that are 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>Samba DMS 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>
+<indexterm><primary></primary></indexterm>
+First, you must edit your &smb.conf; file to tell Samba it should now use domain security.
+</para>
+
+<para>
+<indexterm><primary>security = user</primary></indexterm>
+<indexterm><primary>standalone server</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+Change (or add) your <smbconfoption name="security"/> line in the [global] section
+of your &smb.conf; to read:
+<smbconfblock>
+<smbconfoption name="security">domain</smbconfoption>
+</smbconfblock>
+Note that if the parameter <parameter>security = user</parameter> is used, this machine would function as a
+standalone server and not as a domain member server. Domain security mode causes Samba to work within the
+domain security context.
+</para>
+
+<para>
+Next change the <smbconfoption name="workgroup"/> line in the <smbconfsection name="[global]"/>
+section to read:
+<smbconfblock>
+<smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
+</smbconfblock>
+This is the name of the domain we are joining.
+</para>
+
+<para>
+<indexterm><primary>authenticate</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>authenticate users</primary></indexterm>
+<indexterm><primary>domain controllers</primary></indexterm>
+Finally, add (or modify) a <smbconfoption name="password server"/> line in the [global]
+section to read:
+<smbconfblock>
+<smbconfoption name="password server">DOMPDC DOMBDC1 DOMBDC2</smbconfoption>
+</smbconfblock>
+These are the PDC and BDCs 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>
+<indexterm><primary>list of domain controllers</primary></indexterm>
+<indexterm><primary>mechanism</primary></indexterm>
+<indexterm><primary>broadcast-based name resolution</primary></indexterm>
+<indexterm><primary>DNS name resolution</primary></indexterm>
+Alternatively, if you want smbd to determine automatically the list of domain controllers to use for
+authentication, you may set this line to be:
+<smbconfblock>
+<smbconfoption name="password server">*</smbconfoption>
+</smbconfblock>
+<indexterm><primary>WINS</primary></indexterm>
+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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
+<screen>
+&rootprompt;<userinput>net rpc join -S DOMPDC -U<replaceable>Administrator%password</replaceable></userinput>
+</screen>
+</para>
+
+<para>
+<indexterm><primary>NetBIOS name</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>WINS lookup</primary></indexterm>
+<indexterm><primary>NetBIOS broadcast</primary></indexterm>
+If the <option>-S DOMPDC</option> argument is not given, the domain name will be obtained from &smb.conf; and
+the NetBIOS name of the PDC will be obtained either using a WINS lookup or via NetBIOS broadcast based name
+look up.
+</para>
+
+<para>
+<indexterm><primary>joining the domain</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>Administrator%password</primary></indexterm>
+<indexterm><primary>Joined domain</primary></indexterm>
+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 following message in your terminal window.
+Where the older NT4-style domain architecture is used:
+<screen>
+<computeroutput>Joined domain DOM.</computeroutput>
+</screen>
+</para>
+
+<para>
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>join</tertiary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>join the ADS domain</primary></indexterm>
+Where Active Directory is used, the command used to join the ADS domain is:
+<screen>
+&rootprompt; net ads join -U<replaceable>Administrator%password</replaceable>
+</screen>
+And the following output is indicative of a successful outcome:
+<screen>
+<computeroutput>Joined SERV1 to realm MYREALM.</computeroutput>
+</screen>
+</para>
+
+<para>
+Refer to the <command>net</command> man page and to <link linkend="NetCommand">the chapter on remote
+administration</link> for further information.
+</para>
+
+<para>
+<indexterm><primary>join the domain</primary></indexterm>
+<indexterm><primary>create machine trust account</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+This process joins the server to the domain without separately having to create the machine
+trust account on the PDC beforehand.
+</para>
+
+<para>
+<indexterm><primary>machine account password</primary><secondary>change protocol</secondary></indexterm>
+<indexterm><primary>random machine account password</primary></indexterm>
+<indexterm><primary>/usr/local/samba/private/secrets.tdb</primary></indexterm>
+<indexterm><primary>/etc/samba/secrets.tdb</primary></indexterm>
+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. The trust account information that is needed by the DMS is written into the file
+<filename>/usr/local/samba/private/secrets.tdb</filename> or <filename>/etc/samba/secrets.tdb</filename>.
+</para>
+
+<para>
+<indexterm><primary>domain-level security</primary></indexterm>
+<indexterm><primary>shadow password file</primary></indexterm>
+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>
+<indexterm><primary>Samba daemons</primary></indexterm>
+<indexterm><primary>distribution</primary></indexterm>
+<indexterm><primary>/etc/init.d/samba</primary></indexterm>
+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>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>UNIX users</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+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>
+<indexterm><primary>winbind</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+Please refer to <link linkend="winbind">Winbind: Use of Domain Accounts</link>, for information on a system
+to automatically assign UNIX UIDs and GIDs to Windows NT domain users and groups.
+</para>
+
+<para>
+<indexterm><primary>domain-level</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>RPC</primary></indexterm>
+The advantage of 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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>connection resources</primary></indexterm>
+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 or BDC
+only for as long as is necessary to authenticate the user and then drop the connection, thus conserving PDC
+connection resources.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>authentication reply</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>NT groups</primary></indexterm>
+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"><emphasis>LinuxWorld</emphasis></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>
+
+<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 if not present is Yes.</smbconfcomment>
+<smbconfoption name="encrypt passwords">yes</smbconfoption>
+</smbconfblock>
+
+<para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>realm</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>ADS DC</primary></indexterm>
+<indexterm><primary>password server</primary></indexterm>
+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>
+The most common reason for which Samba may not be able to locate the ADS domain controller is a consequence of
+sites maintaining some DNS servers on UNIX systems without regard for the DNS requirements of the ADS
+infrastructure. There is no harm in specifying a preferred ADS domain controller using the <parameter>password
+server</parameter>.
+</para>
+
+<note><para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>authenticated</primary></indexterm>
+You do <emphasis>not</emphasis> need an 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>
+<indexterm><primary>MIT</primary></indexterm>
+<indexterm><primary>Heimdal</primary></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>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>SRV records</primary></indexterm>
+<indexterm><primary>DNS zon</primary></indexterm>
+<indexterm><primary>KDC</primary></indexterm>
+<indexterm><primary>_kerberos.REALM.NAME</primary></indexterm>
+Microsoft ADS automatically create SRV records in the DNS zone
+<parameter>_kerberos._tcp.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.
+A KDC is a Kerberos Key Distribution Center and forms an integral part of the Microsoft
+active directory infrastructure.
+</para>
+
+<para>
+<indexterm><primary>kinit</primary></indexterm>
+<indexterm><primary>DES-CBC-MD5</primary></indexterm>
+<indexterm><primary>DES-CBC-CRC</primary></indexterm>
+<indexterm><primary>encryption types</primary></indexterm>
+<indexterm><primary>kerberos</primary></indexterm>
+<indexterm><primary>Windows 2000</primary></indexterm>
+UNIX systems can use kinit and the DES-CBC-MD5 or DES-CBC-CRC encryption types to authenticate to the Windows
+2000 KDC. For further information regarding Windows 2000 ADS kerberos interoperability please refer to the
+Microsoft Windows 2000 Kerberos <ulink
+url="http://www.microsoft.com/windows2000/techinfo/planning/security/kerbsteps.asp">Interoperability</ulink>
+guide. Another very useful document that may be referred to for general information regarding Kerberos
+interoperability is <ulink url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC1510</ulink>. This RFC
+explains much of the magic behind the operation of Kerberos.
+</para>
+
+<para>
+<indexterm><primary>MIT</primary></indexterm>
+<indexterm><primary>KRB5</primary></indexterm>
+<indexterm><primary>SRV records</primary></indexterm>
+<indexterm><primary>krb5.conf</primary></indexterm>
+<indexterm><primary>DNS lookup</primary></indexterm>
+<indexterm><primary>libraries</primary></indexterm>
+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>
+<indexterm><primary>krb5.conf</primary></indexterm>
+When manually configuring <filename>krb5.conf</filename>, the minimal configuration is:
+<screen>
+[libdefaults]
+ default_realm = YOUR.KERBEROS.REALM
+
+[realms]
+ YOUR.KERBEROS.REALM = {
+ kdc = your.kerberos.server
+ }
+
+[domain_realms]
+ .kerberos.server = YOUR.KERBEROS.REALM
+</screen>
+</para>
+
+<para>
+<indexterm><primary>Heimdal</primary></indexterm>
+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>KDC</primary></indexterm>
+<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>
+<indexterm><primary>Heimdal</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>KDC</primary></indexterm>
+<indexterm><primary>Windows 2003</primary></indexterm>
+With Heimdal versions earlier than 0.6.x you can use only 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 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>
+<indexterm><primary>realm</primary></indexterm>
+<indexterm><primary>uppercase</primary></indexterm>
+<indexterm><primary>KDC</primary></indexterm>
+The realm must be in uppercase or you will get a <quote><errorname>Cannot find KDC for
+requested realm while getting initial credentials</errorname></quote> error (Kerberos
+is case-sensitive!).
+</para></note>
+
+<note><para>
+<indexterm><primary>synchronize</primary></indexterm>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>time difference</primary></indexterm>
+<indexterm><primary>clock skew</primary></indexterm>
+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 (clock skew) is more than five minutes.
+</para></note>
+
+<para>
+<indexterm><primary>clock skew</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+Clock skew limits are configurable in the Kerberos protocols. The default setting is five minutes.
+</para>
+
+<para>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>KDC</primary></indexterm>
+<indexterm><primary>hostname</primary></indexterm>
+<indexterm><primary>realm</primary></indexterm>
+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 be the NetBIOS name followed by the realm.
+</para>
+
+<para>
+<indexterm><primary>/etc/hosts</primary></indexterm>
+<indexterm><primary>KDC</primary></indexterm>
+<indexterm><primary>realm</primary></indexterm>
+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>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>Create the Computer Account</primary></indexterm>
+<indexterm><primary>Testing Server Setup</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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>
+<indexterm><primary>write permission</primary></indexterm>
+<indexterm><primary>Samba private directory</primary></indexterm>
+<indexterm><primary>Administrator account</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+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>
+The Administrator account can be any account that has been designated in the ADS domain security settings with
+permission to add machines to the ADS domain. It is, of course, a good idea to use an account other than Administrator.
+On the UNIX/Linux system, this command must be executed by an account that has UID=0 (root).
+</para>
+
+<para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>machine trust account</primary></indexterm>
+<indexterm><primary>organizational unit</primary></indexterm>
+<indexterm><primary>ADS manager</primary></indexterm>
+<indexterm><primary>kinit</primary></indexterm>
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>join</tertiary></indexterm>
+When making a Windows client a member of an ADS domain within a complex organization, you
+may want to create the machine trust 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 createcomputer="organizational_unit"</userinput>
+</screen>
+Your ADS manager will be able to advise what should be specified for the "organizational_unit" parameter.
+</para>
+
+<para>
+<indexterm><primary>organizational directory</primary></indexterm>
+<indexterm><primary>machine trust account</primary></indexterm>
+<indexterm><primary>container</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+For example, you may want to create the machine trust 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>
+This command will place the Samba server machine trust account in the container
+<literal>Computers/BusinessUnit/Department/Servers</literal>. The container should exist in the ADS directory
+before executing this command. Please note that forward slashes must be used, because backslashes are both
+valid characters in an OU name and used as escapes for other characters. If you need a backslash in an OU
+name, it may need to be quadrupled to pass through the shell escape and ldap escape.
+</para>
+
+<sect3>
+<title>Possible Errors</title>
+
+<para>
+<variablelist>
+ <varlistentry><term><errorname>ADS support not compiled in</errorname></term>
+ <listitem><para>
+ <indexterm><primary>config.cache</primary></indexterm>
+ <indexterm><primary>Kerberos</primary></indexterm>
+ <indexterm><primary>headers files</primary></indexterm>
+ 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>
+ <indexterm><primary>kinit</primary></indexterm>
+ <indexterm><primary>rights</primary></indexterm>
+ You need to log in 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>
+ <indexterm><primary>/etc/krb5.conf</primary></indexterm>
+ <indexterm><primary>unsupported encryption</primary></indexterm>
+ <indexterm><primary>Kerberos</primary></indexterm>
+ 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>
+<indexterm><primary>successful join</primary></indexterm>
+<indexterm><primary>computer account</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+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>
+<indexterm><primary>Windows 2000</primary></indexterm>
+<indexterm><primary>net</primary><secondary>use</secondary></indexterm>
+<indexterm><primary>DES-CBC-MD5</primary></indexterm>
+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>
+<indexterm><primary>DES-CBC-MD5</primary></indexterm>
+<indexterm><primary>ARCFOUR-HMAC-MD5</primary></indexterm>
+<indexterm><primary>encoding</primary></indexterm>
+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>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>Kerberos authentication</primary></indexterm>
+On your Samba server try to log in to a Windows 2000 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>
+<indexterm><primary>administrator password</primary></indexterm>
+<indexterm><primary>change password</primary></indexterm>
+<indexterm><primary>encryption types</primary></indexterm>
+You must change the administrator password at least once after installing a domain controller,
+to create the right encryption types.
+</para>
+
+<para>
+<indexterm><primary>_kerberos._udp</primary></indexterm>
+<indexterm><primary>_ldap._tcp</primary></indexterm>
+<indexterm><primary>default DNS setup</primary></indexterm>
+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>
+<indexterm><primary>maps UNIX users and groups</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+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>
+<indexterm><primary>mappings</primary></indexterm>
+<indexterm><primary>CIFS</primary></indexterm>
+<indexterm><primary>NFS</primary></indexterm>
+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>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>ldap idmap suffix</primary></indexterm>
+To use the <emphasis>LDAP</emphasis> <parameter>ldap idmap suffix</parameter>, set:
+</para>
+
+<smbconfblock>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+</smbconfblock>
+
+<para>
+See the &smb.conf; man page entry for the <smbconfoption name="ldap idmap suffix"></smbconfoption>
+parameter for further information.
+</para>
+
+<para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>LDAP administrative password</primary></indexterm>
+<indexterm><primary>secrets.tdb</primary></indexterm>
+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>
+In place of <literal>ldap-admin-password</literal>, substitute the LDAP administration password for your
+system.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>machine trust accounts</primary></indexterm>
+In the process of adding/deleting/re-adding domain member machine trust 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>reinstall</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>
+<indexterm><primary>machine trust account</primary></indexterm>
+<indexterm><primary>already exists</primary></indexterm>
+<quote>A Windows workstation was reinstalled. The original domain machine trust
+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>
+<indexterm><primary>NetBIOS name cache</primary></indexterm>
+<indexterm><primary>nbtstat</primary></indexterm>
+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. Alternately, the name cache can be flushed and
+reloaded with current data using the <command>nbtstat</command> command on the Windows client:
+<screen>
+&dosprompt; nbtstat -R
+</screen>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Adding Machine to Domain Fails</title>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>fails</primary></indexterm>
+<quote>Adding a Windows 200x or XP Professional machine to the Samba PDC Domain fails with a
+message that says, <errorname>"The machine could not be added at this time, there is a network problem.
+Please try again later."</errorname> Why?</quote>
+</para>
+
+<para>
+<indexterm><primary>check logs</primary></indexterm>
+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>
+<indexterm><primary>script</primary></indexterm>
+<indexterm><primary>path specified</primary></indexterm>
+ The script does not actually exist, or could not be located in the path specified.
+ </para>
+
+ <para>
+<indexterm><primary>UNIX system account</primary></indexterm>
+<indexterm><primary>Samba SAM account</primary></indexterm>
+ <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>
+<indexterm><primary>UNIX system account</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+ The machine could not be added to the UNIX system accounts file <filename>/etc/passwd</filename>.
+ </para>
+
+ <para>
+<indexterm><primary>legal UNIX system account name</primary></indexterm>
+<indexterm><primary>uppercase</primary></indexterm>
+ <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 uppercase characters
+ nor will it allow spaces in the name.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>backend database</primary></indexterm>
+<indexterm><primary>UNIX system account</primary></indexterm>
+<indexterm><primary>Samba backend database</primary></indexterm>
+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>
+<indexterm><primary>SMB signing</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>Windows 2003</primary></indexterm>
+<indexterm><primary>SMB/CIFS</primary></indexterm>
+ 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. This will not interfere with other Windows clients that do not
+ support the more advanced security features of Windows 2003 because the client will simply
+ negotiate a protocol that both it and the server suppport. This is a well-known fall-back facility
+ that is built into the SMB/CIFS protocols.
+ </para>
+
+</sect2>
+
+</sect1>
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-FastStart.xml b/docs-xml/Samba3-HOWTO/TOSHARG-FastStart.xml
new file mode 100644
index 0000000000..ff2552515b
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-FastStart.xml
@@ -0,0 +1,1306 @@
+<?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. <quote>Samba-3 by Example</quote>
+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 by 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 <quote>Samba-3 by Example</quote>
+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 <quote>Samba-3 by Example</quote>. 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 &amp; Reference Guide</quote> is intended
+as the equivalent of an auto mechanic's repair guide. The book <quote>Samba-3 by Example</quote> is the
+equivalent of the driver's guide that explains how to drive the car. If you want complete network
+configuration examples, go to <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample.pdf">Samba-3 by
+Example</ulink>.
+</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 nonexistent 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>
+The later example consider more complex systems that will either integrate into existing MS Windows networks
+or replace them entirely. These 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>Standalone Server</title>
+
+ <para>
+ <indexterm><primary>Server Type</primary><secondary>Stand-alone</secondary></indexterm>
+ A standalone 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 can be a complex server that is a member of a domain security context.
+ </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>
+
+ <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>
+
+ <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: Read-Only Server</title>
+ <step><para>
+ Add user to system (with creation of the user's 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 in <link linkend="anon-example">Anonymous Read-Only Server Configuration</link>.
+ </para></step>
+
+<example id="anon-example">
+<title>Anonymous Read-Only Server Configuration</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <step><para>
+ Test the configuration file by executing the following command:
+<screen>
+&rootprompt;<userinput>testparm</userinput>
+</screen>
+ Alternatively, where you are operating from a master configuration file called
+ <filename>smb.conf.master</filename>, the following sequence of commands might prove
+ more appropriate:
+<screen>
+&rootprompt; cd /etc/samba
+&rootprompt; testparm -s smb.conf.master > smb.conf
+&rootprompt; testparm
+</screen>
+ Note any error messages that might be produced. Proceed only if error-free output has been
+ obtained. An example of typical output that should be generated from the above configuration
+ file is shown here:
+<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. The method that
+ should be used is platform dependent. Refer to <link linkend="startingSamba">Starting Samba</link>
+ for further information regarding the starting of Samba.
+ </para></step>
+
+ <step><para>
+ Configure your MS 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
+ you click 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>
+
+<example id="anon-rw">
+<title>Modified Anonymous Read-Write smb.conf</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ </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 disable it in the following
+ configuration. <link linkend="anon-print"></link> is the resulting &smb.conf; file.
+ </para>
+
+<example id="anon-print">
+<title>Anonymous Print Server smb.conf</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <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. Samba makes
+ use of the direct printing application program interface that is provided by CUPS.
+ When Samba has been compiled and linked with the CUPS libraries, the default printing
+ system will be CUPS. By specifying that the printcap name is CUPS, Samba will use
+ the CUPS library API to communicate directly with CUPS for all printer functions.
+ It is possible to force the use of external printing commands by setting the value
+ of the <parameter>printing</parameter> to either SYSV or BSD, and thus the value of
+ the parameter <parameter>printcap name</parameter> must be set to something other than
+ CUPS. In such case, it could be set to the name of any file that contains a list
+ of printers that should be made available to Windows clients.
+ </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+twrx /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 misuse.
+ </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 the guest backend is
+ added to the list of active passdb backends no matter whether 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"/>.
+ </para></step>
+
+<example id="OfficeServer">
+<title>Secure Office Server smb.conf</title>
+<smbconfblock>
+<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="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>
+</smbconfblock>
+</example>
+
+ <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 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>
+ The following error message indicates that Samba was not running:
+<screen>
+&rootprompt; smbclient -L olorin -U%
+Error connecting to 192.168.1.40 (Connection refused)
+Connection to olorin failed
+</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 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 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 use the users from the last example. The accounting department
+ has a general printer that all departmental users may use. 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>
+ The 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 this 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">Member server smb.conf
+ (globals)</link> and <link linkend="fast-memberserver-shares">Member server smb.conf (shares
+ and services)</link>.
+ </para></step>
+
+<example id="fast-member-server">
+<title>Member Server smb.conf (Globals)</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<example id="fast-memberserver-shares">
+<title>Member Server smb.conf (Shares and Services)</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <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 do 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 (NSS) 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">Engineering Office smb.conf
+ (globals)</link> together with <link linkend="fast-engoffice-shares">Engineering Office smb.conf
+ (shares and services)</link>:
+ <indexterm><primary>pdbedit</primary></indexterm>
+ </para></step>
+
+<example id="fast-engoffice-global">
+<title>Engineering Office smb.conf (globals)</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<example id="fast-engoffice-shares">
+<title>Engineering Office smb.conf (shares and services)</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <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 by executing this shell script
+ (You could name the script <filename>initGroups.sh</filename>):
+<screen>
+#!/bin/bash
+#### Keep this as a shell script for future re-use
+
+# First assign well known groups
+net groupmap add ntgroup="Domain Admins" unixgroup=ntadmins rid=512 type=d
+net groupmap add ntgroup="Domain Users" unixgroup=users rid=513 type=
+net groupmap add ntgroup="Domain Guests" unixgroup=nobody rid=514 type=d
+
+# 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
+</screen>
+ </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 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 Lightweight 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.9.1</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>
+<title>Example slapd.conf File</title>
+<screen>
+# 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
+</screen>
+ </para></step>
+
+ <step><para>
+ Create the following file <filename>initdb.ldif</filename>:
+ <indexterm><primary>initdb.ldif</primary></indexterm>
+<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>
+ </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">LDAP backend smb.conf for PDC</link>. Add additional stanzas
+ as required.
+ </para></step>
+
+<example id="fast-ldap">
+<title>LDAP backend smb.conf for PDC</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <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 and 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. Note that
+ the &smb.conf; file does not specify the smbldap-tools scripts &smbmdash; they are
+ not needed on a BDC. Add additional stanzas for shares and printers as required.
+ </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">Remote LDAP BDC smb.conf</link>
+ uses a central LDAP server.
+ </para></step>
+
+<example id="fast-bdc">
+<title>Remote LDAP BDC smb.conf</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <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-xml/Samba3-HOWTO/TOSHARG-Further-Resources.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Further-Resources.xml
new file mode 100644
index 0000000000..0a9d7d1cd5
--- /dev/null
+++ b/docs-xml/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-xml/Samba3-HOWTO/TOSHARG-Group-Mapping.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Group-Mapping.xml
new file mode 100644
index 0000000000..337ae3d794
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Group-Mapping.xml
@@ -0,0 +1,920 @@
+<?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: MS Windows and UNIX</title>
+
+
+ <para>
+<indexterm significance="preferred"><primary>groups</primary><secondary>mapping</secondary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>associations</primary></indexterm>
+<indexterm><primary>UNIX groups</primary></indexterm>
+<indexterm><primary>groupmap</primary></indexterm>
+<indexterm><primary>net</primary></indexterm>
+ Starting with Samba-3, new group mapping functionality is available to create associations
+ between Windows group SIDs and UNIX group GIDs. The <command>groupmap</command> subcommand
+ included with the &net; tool can be used to manage these associations.
+ </para>
+
+ <para>
+<indexterm><primary>group mapping</primary></indexterm>
+<indexterm><primary>domain groups</primary></indexterm>
+ 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>
+<indexterm><primary>Windows 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>
+<indexterm><primary>MMC</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>ID range</primary></indexterm>
+<indexterm><primary>group accounts</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 and GIDs from the ID range specified by the
+ <smbconfoption name="idmap uid"/>/<smbconfoption name="idmap gid"/>
+ parameters in the &smb.conf; file.
+ </para>
+
+ <figure id="idmap-sid2gid">
+ <title>IDMAP: Group SID-to-GID Resolution.</title>
+ <imagefile scale="50">idmap-sid2gid</imagefile>
+ </figure>
+
+ <figure id="idmap-gid2sid">
+ <title>IDMAP: GID Resolution to Matching SID.</title>
+ <imagefile scale="50">idmap-gid2sid</imagefile>
+ </figure>
+
+ <para>
+ <indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>SID-to-GID</primary></indexterm>
+<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm>
+<indexterm><primary>group mappings</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>
+
+ <figure id="idmap-store-gid2sid">
+ <title>IDMAP Storing Group Mappings.</title>
+ <imagefile scale="50">idmap-store-gid2sid</imagefile>
+ </figure>
+
+ <para>
+ <indexterm><primary>groupadd</primary></indexterm>
+ <indexterm><primary>groupdel</primary></indexterm>
+<indexterm><primary>shadow utilities</primary></indexterm>
+<indexterm><primary>groupmod</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 uppercase 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 workarounds 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 workaround solution.
+ </para>
+
+ <para>
+<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm>
+ Another workaround 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>
+<indexterm><primary>Windows NT4/200x</primary></indexterm>
+<indexterm><primary>group privileges</primary></indexterm>
+ When you install <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 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>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>inherits rights</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+ 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 Admins</constant> group inherits the rights of the local <constant>Administrators</constant> group when
+ logging on the workstation.
+ </para>
+
+ <para>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+ 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>
+<indexterm><primary>/etc/group</primary></indexterm>
+ 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 executing the command:
+ </para>
+
+ <para>
+<screen>
+&rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm rid=512 type=d</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
+ to make 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 type=d</userinput>
+</screen>
+ The <literal>ntgroup</literal> value must be in quotes if it contains space characters to prevent
+ the space from being interpreted as a command delimiter.
+ </para>
+
+ <para>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>assigned RID</primary></indexterm>
+ Be aware that the RID parameter is an 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: User Private Group Problems</title>
+
+ <para>
+<indexterm><primary>group accounts</primary></indexterm>
+<indexterm><primary>Red Hat Linux</primary></indexterm>
+<indexterm><primary>private groups</primary></indexterm>
+ 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>
+<indexterm><primary>UNIX/Linux group</primary></indexterm>
+<indexterm><primary>Windows group</primary></indexterm>
+ 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>
+<indexterm><primary>nested groups</primary></indexterm>
+ This functionality is known as <constant>nested groups</constant> and was first added to
+ Samba-3.0.3.
+ </para>
+
+ <para>
+<indexterm><primary>nested groups</primary></indexterm>
+ All MS Windows products since the release of Windows NT 3.10 support the use of nested groups.
+ Many Windows network administrators depend on this capability because it greatly simplifies security
+ administration.
+ </para>
+
+ <para>
+<indexterm><primary>nested group</primary></indexterm>
+<indexterm><primary>group membership</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>local groups</primary></indexterm>
+<indexterm><primary>domain global groups</primary></indexterm>
+<indexterm><primary>domain global users</primary></indexterm>
+ 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>
+<indexterm><primary>individual domain user</primary></indexterm>
+<indexterm><primary>domain group settings</primary></indexterm>
+<indexterm><primary>Account Unknown</primary></indexterm>
+ 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>
+<indexterm><primary>directory access control</primary></indexterm>
+<indexterm><primary>local groups</primary></indexterm>
+<indexterm><primary>ACL</primary></indexterm>
+<indexterm><primary>Account Unknown</primary></indexterm>
+ Unraveling 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>
+<indexterm><primary>nested groups</primary></indexterm>
+<indexterm><primary>administrative privileges</primary></indexterm>
+<indexterm><primary>domain member workstations</primary></indexterm>
+<indexterm><primary>domain member servers</primary></indexterm>
+<indexterm><primary>member machine</primary></indexterm>
+<indexterm><primary>full rights</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>local administrative privileges</primary></indexterm>
+ 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
+ built-in 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 administrative
+ privileges on each domain member.
+ </para>
+
+ <para>
+<indexterm><primary>nested groups</primary></indexterm>
+<indexterm><primary>auxiliary members</primary></indexterm>
+<indexterm><primary>/etc/group</primary></indexterm>
+<indexterm><primary>winbind</primary></indexterm>
+ 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>
+<indexterm><primary>/etc/group</primary></indexterm>
+<indexterm><primary>libnss_winbind</primary></indexterm>
+<indexterm><primary>local groups</primary></indexterm>
+<indexterm><primary>Domain Users</primary></indexterm>
+<indexterm><primary>alias group</primary></indexterm>
+ 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. 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 domain controller 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>
+<indexterm><primary>nested groups</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>winbind</primary></indexterm>
+<indexterm><primary>local groups</primary></indexterm>
+<indexterm><primary>Domain User Manager</primary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group</tertiary></indexterm>
+ To enable the use of nested groups, <command>winbindd</command> must be used 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>
+<indexterm><primary>addmem</primary></indexterm>
+<indexterm><primary>delmem</primary></indexterm>
+ 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 privileges. 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> is done by executing:
+ <screen>
+ net rpc group addmem demo "DOM\Domain Users"
+ </screen>
+<indexterm><primary>getent group demo</primary></indexterm>
+<indexterm><primary>trusted domain</primary></indexterm>
+<indexterm><primary>foreign domain</primary></indexterm>
+<indexterm><primary>local access permissions</primary></indexterm>
+ 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>. The users from the foreign domain who are members of the group that has been
+ added to the <constant>demo</constant> group now have the same local access permissions as local domain
+ users have.
+ </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>
+<indexterm><primary>rights and privileges</primary></indexterm>
+<indexterm><primary>domain member client</primary></indexterm>
+<indexterm><primary>group account</primary></indexterm>
+ 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
+ domain administration tasks such as adding, deleting, and changing user and group account information, and
+ managing workstation domain membership accounts, can be handled by any account other than root.
+ </para>
+
+ <para>
+<indexterm><primary>privilege management</primary></indexterm>
+<indexterm><primary>delegated</primary></indexterm>
+<indexterm><primary>Administrator</primary></indexterm>
+ Samba-3.0.11 introduced a new privilege management interface (see <link linkend="rights">User 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) accounts.
+ </para>
+
+ <para>
+<indexterm><primary>mapped</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+ 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>
+<indexterm><primary>privilege</primary></indexterm>
+ 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>
+<indexterm><primary>system security</primary></indexterm>
+<indexterm><primary>privileges</primary></indexterm>
+ Many UNIX administrators continue to request that the Samba Team make it possible to add Windows workstations, or
+ the 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>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>Domain Server Manager</primary></indexterm>
+<indexterm><primary>Domain User Manager</primary></indexterm>
+<indexterm><primary>manage share-level ACL</primary></indexterm>
+<indexterm><primary>share-level ACLs</primary></indexterm>
+ There is no safe way to provide access on a UNIX/Linux system without providing
+ <constant>root</constant>-level privileges. Provision of <constant>root</constant> privileges can be done
+ either by logging on to 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>
+<indexterm><primary>Windows NT4/200x/XP</primary></indexterm>
+<indexterm><primary>well-known RID</primary></indexterm>
+<indexterm><primary>domain groups</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>NT groups</primary></indexterm>
+ When first installed, Windows NT4/200x/XP are preconfigured with certain user, group, and
+ alias entities. Each has a well-known 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 administrator's responsibility to create
+ (provision) the default NT groups.
+ </para>
+
+ <para>
+<indexterm><primary>default users</primary></indexterm>
+<indexterm><primary>default groups</primary></indexterm>
+<indexterm><primary>default aliases</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+ 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>.
+ </para>
+
+ <note><para>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+<indexterm><primary>domain groups</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+ It is the administrator's responsibility to create the essential domain groups and to assign each
+ its default RID.
+ </para></note>
+
+ <para>
+<indexterm><primary>domain groups</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+ 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 their default RIDs. 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>
+<indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>list</tertiary></indexterm>
+ You can list the various groups in the mapping database by executing
+ <command>net groupmap list</command>. Here is an example:
+ </para>
+
+ <para>
+<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm>
+<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>
+ <indexterm><primary>smbgrpadd.sh</primary></indexterm>
+<indexterm><primary>/etc/group</primary></indexterm>
+<indexterm><primary>groupadd</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
+ adds a temporary entry in the <filename>/etc/group</filename> file and then renames
+ it to the desired name. This is an example of a method to get around operating
+ system maintenance tool limitations such as those present in some version of the
+ <command>groupadd</command> tool.
+<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
+rm /etc/group.bak
+
+# Now return the GID as would normally happen.
+echo $thegid
+exit 0
+</programlisting>
+</example>
+</para>
+
+ <para>
+ The &smb.conf; entry for the above script shown in <link linkend="smbgrpadd">the configuration of
+ &smb.conf; for the add group Script</link> demonstrates how it may be used.
+
+<example id="smbgrpadd">
+<title>Configuration of &smb.conf; for the add group Script</title>
+<smbconfblock>
+<smbconfsection name="[global]"/>
+<smbconfoption name="add group script">/path_to_tool/smbgrpadd.sh &quot;%g&quot;</smbconfoption>
+</smbconfblock>
+</example>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Script to Configure Group Mapping</title>
+
+ <para>
+<indexterm><primary>initGroups.sh</primary></indexterm>
+ 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 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>.
+<indexterm><primary>initGroups.sh</primary></indexterm>
+<example id="set-group-map">
+<title>Script to Set Group Mapping</title>
+<programlisting>
+#!/bin/bash
+
+net groupmap add ntgroup="Domain Admins" unixgroup=ntadmin rid=512 type=d
+net groupmap add ntgroup="Domain Users" unixgroup=users rid=513 type=d
+net groupmap add ntgroup="Domain Guests" unixgroup=nobody rid=514 type=d
+
+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>
+
+ <note><para>
+ Versions of Samba-3 prior to 3.0.23 automatically create default group mapping for the
+ <literal>Domain Admins, Domain Users</literal> and <literal>Domain Guests</literal> Windows
+ groups, but do not map them to UNIX GIDs. This was a cause of administrative confusion and
+ trouble. Commencing with Samba-3.0.23 this annomaly has been fixed - thus all Windows groups
+ must now be manually and explicitly created and mapped to a valid UNIX GID by the Samba
+ administrator.
+ </para></note>
+
+ </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 be carefully tested
+manually before putting it into active service.
+</para>
+
+ <sect2>
+ <title>Adding Groups Fails</title>
+
+ <para>
+<indexterm><primary>groupadd</primary></indexterm>
+ 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>
+<indexterm><primary>uppercase character</primary></indexterm>
+<indexterm><primary>space character</primary></indexterm>
+ The most common cause of failure is an attempt to add an MS Windows group account
+ that has an uppercase character and/or a space character in it.
+ </para>
+
+ <para>
+<indexterm><primary>groupadd</primary></indexterm>
+ There are three possible workarounds. 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 Domain Users to the Workstation Power Users Group</title>
+
+ <para><quote>
+ What must I do to add domain users to the Power Users group?
+ </quote></para>
+
+ <para>
+<indexterm><primary>Domain Users group</primary></indexterm>
+ 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 Users</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>, that is, 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-xml/Samba3-HOWTO/TOSHARG-HighAvailability.xml b/docs-xml/Samba3-HOWTO/TOSHARG-HighAvailability.xml
new file mode 100644
index 0000000000..1ce81d404e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-HighAvailability.xml
@@ -0,0 +1,500 @@
+<?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>
+<indexterm><primary>availability</primary></indexterm>
+<indexterm><primary>intolerance</primary></indexterm>
+<indexterm><primary>vital task</primary></indexterm>
+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>
+<indexterm><primary>fail</primary></indexterm>
+<indexterm><primary>managed by humans</primary></indexterm>
+<indexterm><primary>economically wise</primary></indexterm>
+<indexterm><primary>anticipate failure</primary></indexterm>
+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>
+<indexterm><primary>high availability</primary></indexterm>
+<indexterm><primary>CIFS/SMB</primary></indexterm>
+<indexterm><primary>state of knowledge</primary></indexterm>
+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>
+<indexterm><primary>SambaXP conference</primary></indexterm>
+<indexterm><primary>Germany</primary></indexterm>
+<indexterm><primary>inspired structure</primary></indexterm>
+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>
+<indexterm><primary>clustering technologies</primary></indexterm>
+<indexterm><primary>affordable power</primary></indexterm>
+<indexterm><primary>unstoppable services</primary></indexterm>
+ 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:
+<indexterm><primary>clustered file server</primary></indexterm>
+<indexterm><primary>connect transparently</primary></indexterm>
+<indexterm><primary>transparently reconnected</primary></indexterm>
+<indexterm><primary>distributed file system</primary></indexterm>
+ </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 serve 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>
+<indexterm><primary>state information</primary></indexterm>
+ All TCP/IP connections are dependent on state information.
+ </para>
+ <para>
+<indexterm><primary>TCP failover</primary></indexterm>
+ 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 failover.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<indexterm><primary>CIFS/SMB</primary></indexterm>
+<indexterm><primary>TCP</primary></indexterm>
+ CIFS/SMB (the Windows networking protocols) uses TCP connections.
+ </para>
+ <para>
+ This means that from a basic design perspective, failover is not
+ seriously considered.
+ <itemizedlist>
+ <listitem><para>
+ All current SMB clusters are failover solutions
+ &smbmdash; they rely on the clients to reconnect. They provide server
+ failover, but clients can lose information due to a server failure.
+<indexterm><primary>server failure</primary></indexterm>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Servers keep state information about client connections.
+ <itemizedlist>
+<indexterm><primary>state</primary></indexterm>
+ <listitem><para>CIFS/SMB involves a lot of state.</para></listitem>
+ <listitem><para>Every file open must be compared with other open files
+ to check share modes.</para></listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <sect3>
+ <title>The Front-End Challenge</title>
+
+ <para>
+<indexterm><primary>cluster servers</primary></indexterm>
+<indexterm><primary>single server</primary></indexterm>
+<indexterm><primary>TCP data streams</primary></indexterm>
+<indexterm><primary>front-end virtual server</primary></indexterm>
+<indexterm><primary>virtual server</primary></indexterm>
+<indexterm><primary>de-multiplex</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+ 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>
+<indexterm><primary>IPC$ connections</primary></indexterm>
+<indexterm><primary>RPC calls</primary></indexterm>
+ 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>Demultiplexing SMB Requests</title>
+
+ <para>
+<indexterm><primary>SMB requests</primary></indexterm>
+<indexterm><primary>SMB state information</primary></indexterm>
+<indexterm><primary>front-end virtual server</primary></indexterm>
+<indexterm><primary>complicated problem</primary></indexterm>
+ 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>
+<indexterm><primary>vuid</primary></indexterm>
+<indexterm><primary>tid</primary></indexterm>
+<indexterm><primary>fid</primary></indexterm>
+ 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>
+<indexterm><primary>SMB requests</primary></indexterm>
+<indexterm><primary>Terminal Server</primary></indexterm>
+ SMB requests are sent by vuid to their associated server. No code exists today to
+ effect 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>
+<indexterm><primary>de-multiplexing</primary></indexterm>
+ 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>
+<indexterm><primary>backend</primary></indexterm>
+<indexterm><primary>SMB semantics</primary></indexterm>
+<indexterm><primary>share modes</primary></indexterm>
+<indexterm><primary>locking</primary></indexterm>
+<indexterm><primary>oplock</primary></indexterm>
+<indexterm><primary>distributed file systems</primary></indexterm>
+ 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>
+<indexterm><primary>server pool</primary></indexterm>
+ 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>
+<indexterm><primary>SMB services</primary></indexterm>
+<indexterm><primary>oplock handling</primary></indexterm>
+<indexterm><primary>server pool</primary></indexterm>
+<indexterm><primary>backend file system pool</primary></indexterm>
+ 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>
+<indexterm><primary>NFS</primary></indexterm>
+<indexterm><primary>interoperability</primary></indexterm>
+ 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 interoperability 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>
+<indexterm><primary>POSIX semantics</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>POSIX locks</primary></indexterm>
+<indexterm><primary>SMB locks</primary></indexterm>
+ 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>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>tdb</primary></indexterm>
+<indexterm><primary>Clustered smbds</primary></indexterm>
+ 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 interserver communications in the server pool is a design prerequisite
+ for a fully functional system. Possibilities for this include:
+ </para>
+
+ <itemizedlist>
+<indexterm><primary>Myrinet</primary></indexterm>
+<indexterm><primary>scalable coherent interface</primary><see>SCI</see></indexterm>
+ <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 interconnect
+ system to permit transparent failover 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>
+<indexterm><primary>failure semantics</primary></indexterm>
+<indexterm><primary>oplock messages</primary></indexterm>
+ 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 interserver
+ pool failure semantics function, and how should such functionality 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>
+<indexterm><primary>failover servers</primary></indexterm>
+<indexterm><primary>exported file system</primary></indexterm>
+<indexterm><primary>distributed locking protocol</primary></indexterm>
+ Allowing failover servers to handle different functions within the exported file system
+ removes the problem of requiring a distributed locking protocol.
+ </para>
+
+ <para>
+<indexterm><primary>high-speed server interconnect</primary></indexterm>
+<indexterm><primary>complex file name space</primary></indexterm>
+ 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>
+<indexterm><primary>virtual server</primary></indexterm>
+ 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>
+<indexterm><primary>resource failover</primary></indexterm>
+<indexterm><primary>high-availability services</primary></indexterm>
+<indexterm><primary>dedicated heartbeat</primary></indexterm>
+<indexterm><primary>LAN</primary></indexterm>
+<indexterm><primary>failover process</primary></indexterm>
+ Failover servers must communicate in order to handle resource failover. This is essential
+ for high-availability services. The use of a dedicated heartbeat is a common technique to
+ introduce some intelligence into the failover process. This is often done over a dedicated
+ link (LAN or serial).
+ </para>
+
+ <para>
+<indexterm><primary>SCSI</primary></indexterm>
+<indexterm><primary>Red Hat Cluster Manager</primary></indexterm>
+<indexterm><primary>Microsoft Wolfpack</primary></indexterm>
+<indexterm><primary>Fiber Channel</primary></indexterm>
+<indexterm><primary>failover communication</primary></indexterm>
+ Many failover solutions (like Red Hat Cluster Manager and Microsoft Wolfpack)
+ can use a shared SCSI of Fiber Channel disk storage array for failover 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>
+<indexterm><primary>Linux High Availability project</primary></indexterm>
+ 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>
+<indexterm><primary>backend failures</primary></indexterm>
+<indexterm><primary>continuity of service</primary></indexterm>
+ Front-end server complexity remains a challenge for high availability because it must deal
+ gracefully with backend failures, while at the same time providing 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 works even
+ at the file level.
+ </para>
+
+ <para>
+ Above all, at the cost of complexity of management, a distributed system (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 failover 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-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml b/docs-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml
new file mode 100644
index 0000000000..2ff794939c
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-IDMAP.xml
@@ -0,0 +1,1124 @@
+<?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 the operating systems 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 identity mapping (IDMAP) of Windows security identifiers (SIDs)
+to UNIX UIDs and GIDs.
+</para>
+
+<para>
+To ensure sufficient coverage, each possible Samba deployment type is discussed.
+This is followed by an overview of how the IDMAP facility may be implemented.
+</para>
+
+<para>
+<indexterm><primary>network client</primary></indexterm>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>IDMAP infrastructure</primary></indexterm>
+<indexterm><primary>default behavior</primary></indexterm>
+The IDMAP facility is of concern where more than one Samba server (or Samba network client)
+is installed in a domain. Where there is a single Samba server, do not be too concerned regarding
+the IDMAP infrastructure &smbmdash; the default behavior of Samba is nearly always sufficient.
+Where mulitple Samba servers are used it is often necessary to move data off one server and onto
+another, and that is where the fun begins!
+</para>
+
+<para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>nss_ldap</primary></indexterm>
+<indexterm><primary>NT4 domain members</primary></indexterm>
+<indexterm><primary>ADS domain members</primary></indexterm>
+<indexterm><primary>security name-space</primary></indexterm>
+Where user and group account information is stored in an LDAP directory every server can have the same
+consistent UID and GID for users and groups. This is achieved using NSS and the nss_ldap tool. Samba
+can be configured to use only local accounts, in which case the scope of the IDMAP problem is somewhat
+reduced. This works reasonably well if the servers belong to a single domain, and interdomain trusts
+are not needed. On the other hand, if the Samba servers are NT4 domain members, or ADS domain members,
+or if there is a need to keep the security name-space separate (i.e., the user
+<literal>DOMINICUS\FJones</literal> must not be given access to the account resources of the user
+<literal>FRANCISCUS\FJones</literal><footnote>Samba local account mode results in both
+<literal>DOMINICUS\FJones</literal> and <literal>FRANCISCUS\FJones</literal> mapping to the UNIX user
+<literal>FJones</literal>.</footnote> free from inadvertent cross-over, close attention should be given
+to the way that the IDMAP facility is configured.
+</para>
+
+<para>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>domain access</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<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 the execution of the <command>winbindd</command> upon Samba startup.
+</para>
+
+<sect1>
+<title>Samba Server Deployment Types and IDMAP</title>
+
+<para>
+<indexterm><primary>Server Types</primary></indexterm>
+There are four basic server deployment types, as documented in <link linkend="ServerType">the chapter
+on Server Types and Security Modes</link>.
+</para>
+
+ <sect2>
+ <title>Standalone Samba Server</title>
+
+ <para>
+ <indexterm><primary>stand-alone server</primary></indexterm>
+ <indexterm><primary>Active Directory</primary></indexterm>
+ <indexterm><primary>NT4 Domain</primary></indexterm>
+ A standalone Samba server is an implementation that is not a member of a Windows NT4 domain,
+ a Windows 200X Active Directory domain, or a Samba domain.
+ </para>
+
+ <para>
+ <indexterm><primary>IDMAP</primary></indexterm>
+ <indexterm><primary>identity</primary></indexterm>
+ <indexterm><primary>local user</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 versions of MS Windows products. Windows NT4, as with MS Active Directory,
+ extensively makes use of Windows 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 it uses 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: </term>
+ <listitem>
+ <para>
+ <indexterm><primary>winbindd</primary></indexterm>
+ <indexterm><primary>smbd</primary></indexterm>
+ <indexterm><primary>network traffic</primary></indexterm>
+ <indexterm><primary>LoginID</primary></indexterm>
+ <indexterm><primary>account name</primary></indexterm>
+ <indexterm><primary>getpwnam</primary></indexterm>
+ <indexterm><primary>NSS</primary></indexterm>
+ <indexterm><primary>local users</primary></indexterm>
+ <indexterm><primary>local groups</primary></indexterm>
+ <indexterm><primary>/etc/passwd</primary></indexterm>
+ <indexterm><primary>/etc/group</primary></indexterm>
+ 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 is 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 "users and groups are local,"
+ 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>
+ <indexterm><primary>SessionSetupAndX</primary></indexterm>
+ <indexterm><primary>/etc/passwd</primary></indexterm>
+ For example, when the user <literal>BERYLIUM\WambatW</literal> tries to open a
+ connection to a Samba server the incoming SessionSetupAndX request will make a
+ system call to look up the user <literal>WambatW</literal> in the
+ <filename>/etc/passwd</filename> file.
+ </para>
+
+ <para>
+ <indexterm><primary>standalone</primary></indexterm>
+ <indexterm><primary>domain member server</primary></indexterm>
+ <indexterm><primary>NT4</primary></indexterm>
+ <indexterm><primary>ADS</primary></indexterm>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>tdbsam</primary></indexterm>
+ <indexterm><primary>passdb backend</primary></indexterm>
+ This configuration may be used with standalone Samba servers, domain member
+ servers (NT4 or ADS), and 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: </term>
+ <listitem>
+ <para>
+ <indexterm><primary>user accounts</primary></indexterm>
+ <indexterm><primary>group accounts</primary></indexterm>
+ <indexterm><primary>local accounts</primary></indexterm>
+ <indexterm><primary>repository</primary></indexterm>
+ <indexterm><primary>NIS</primary></indexterm>
+ <indexterm><primary>LDAP</primary></indexterm>
+ 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 an NIS-type database or else in LDAP.
+ </para>
+
+ <para>
+ <indexterm><primary>standalone</primary></indexterm>
+ <indexterm><primary>domain member server</primary></indexterm>
+ <indexterm><primary>NT4</primary></indexterm>
+ <indexterm><primary>ADS</primary></indexterm>
+ <indexterm><primary>PDC</primary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>tdbsam</primary></indexterm>
+ This configuration may be used with standalone Samba servers, domain member
+ servers (NT4 or ADS), and 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: </term>
+ <listitem>
+ <para>
+ <indexterm><primary>NT4 domain</primary></indexterm>
+ <indexterm><primary>ADS domain</primary></indexterm>
+ <indexterm><primary>winbind</primary></indexterm>
+ <indexterm><primary>domain control</primary></indexterm>
+ 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>
+ <indexterm><primary>UID numbers</primary></indexterm>
+ <indexterm><primary>GID numbers</primary></indexterm>
+ <indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+ <indexterm><primary>winbind</primary></indexterm>
+ <indexterm><primary>SID</primary></indexterm>
+ 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>
+ <indexterm><primary>UID</primary></indexterm>
+ <indexterm><primary>GID</primary></indexterm>
+ <indexterm><primary>IDMAP</primary></indexterm>
+ <indexterm><primary>corrupted file</primary></indexterm>
+ 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 becomes corrupted or lost, the repaired or rebuilt IDMAP file may allocate
+ UIDs and GIDs to different 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
+ the rightful owners.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>Winbind/NSS uses RID based IDMAP: </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, that do not apply
+ an ADS schema extension, and that do not have an installed 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>
+ <indexterm><primary>automatic mapping</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 subset 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: </term>
+ <listitem>
+ <para>
+ <indexterm><primary>Domain Member</primary></indexterm>
+ <indexterm><primary>winbind</primary></indexterm>
+ <indexterm><primary>SID</primary></indexterm>
+ <indexterm><primary>UID</primary></indexterm>
+ <indexterm><primary>GID</primary></indexterm>
+ <indexterm><primary>idmap gid</primary></indexterm>
+ <indexterm><primary>idmap uid</primary></indexterm>
+ <indexterm><primary>LDAP</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>
+ <indexterm><primary>LDAP server</primary></indexterm>
+ <indexterm><primary>LDAP redirects</primary></indexterm>
+ It is important that all LDAP IDMAP clients use only the master LDAP server because 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: </term>
+ <listitem>
+ <para>
+ The use of LDAP as the passdb backend is a smart solution for PDC, BDC, and
+ domain member servers. It is a neat method for assuring that UIDs, GIDs, and the matching
+ SIDs are 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, that is, SIDs from
+ standalone 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 using the Microsoft Services for UNIX
+ version 3.5 or 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 is 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 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 an 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, if a user has a UID of 4321, and the algorithmic RID base has a value of 1000, the RID will
+ be <literal>1000 + (2 x 4321) = 9642</literal>. Thus, if the domain SID is
+ <literal>S-1-5-21-89238497-92787123-12341112</literal>, the resulting SID is
+ <literal>S-1-5-21-89238497-92787123-12341112-9642</literal>.
+ </para>
+
+ <para>
+ <indexterm><primary>on-the-fly</primary></indexterm>
+ <indexterm><primary>SID</primary></indexterm>
+ <indexterm><primary>passdb backend</primary></indexterm>
+ <indexterm><primary>ldapsam</primary></indexterm>
+ The foregoing type of SID is produced by Samba as an automatic function and is either produced on the fly
+ (as is 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>
+ <indexterm><primary>ADS</primary></indexterm>
+ <indexterm><primary>directory schema</primary></indexterm>
+ <indexterm><primary>account attributes</primary></indexterm>
+ <indexterm><primary>UID</primary></indexterm>
+ <indexterm><primary>GID</primary></indexterm>
+ <indexterm><primary>ADS schema</primary></indexterm>
+ <indexterm><primary>account management</primary></indexterm>
+ <indexterm><primary>MMC</primary></indexterm>
+ 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>
+ <indexterm><primary>passdb backend</primary></indexterm>
+ <indexterm><primary>BDC</primary></indexterm>
+ <indexterm><primary>LDAP backend</primary></indexterm>
+ Security identifiers used within a domain must be managed to avoid conflict and to preserve itegrity.
+ In an NT4 domain context, the PDC manages the distribution of all security credentials to the backup
+ domain controllers (BDCs). 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>
+ <indexterm><primary>read-only access</primary></indexterm>
+ <indexterm><primary>security credentials</primary></indexterm>
+ <indexterm><primary>LDAP</primary></indexterm>
+ <indexterm><primary>group account</primary></indexterm>
+ <indexterm><primary>write changes</primary></indexterm>
+ <indexterm><primary>directory</primary></indexterm>
+ 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 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>
+<indexterm><primary>winbind</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>
+ <link linkend="idmapnt4dms">NT4 Domain Member Server smb.con</link> is a simple example of an NT4 DMS
+ &smb.conf; file that shows only the global section.
+ </para>
+
+<example id="idmapnt4dms">
+<title>NT4 Domain Member Server smb.conf</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MEGANET2</smbconfoption>
+<smbconfoption name="security">DOMAIN</smbconfoption>
+<smbconfoption name="idmap uid">10000-20000</smbconfoption>
+<smbconfoption name="idmap gid">10000-20000</smbconfoption>
+<smbconfoption name="template primary group">"Domain Users"</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+</smbconfblock>
+</example>
+
+ <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 [dns] wins
+...
+</screen>
+ The use of DNS in the hosts entry should be made only if DNS is used on site.
+ </para>
+
+ <para>
+ The creation of the DMS requires the following steps:
+ </para>
+
+ <procedure>
+ <step><para>
+ Create or install an &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 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>
+ <indexterm><primary>nmbd</primary></indexterm>
+ <indexterm><primary>winbind</primary></indexterm>
+ <indexterm><primary>smbd</primary></indexterm>
+ 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>
+ <indexterm><primary>ADS domain</primary></indexterm>
+ The procedure for joining an ADS domain is similar to the NT4 domain join, except the &smb.conf; file
+ will have the contents shown in <link linkend="idmapadsdms">ADS Domain Member Server smb.conf</link>
+ </para>
+
+<example id="idmapadsdms">
+<title>ADS Domain Member Server smb.conf</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">BUTTERNET</smbconfoption>
+<smbconfoption name="netbios name">GARGOYLE</smbconfoption>
+<smbconfoption name="realm">BUTTERNET.BIZ</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="idmap uid">500-10000000</smbconfoption>
+<smbconfoption name="idmap gid">500-10000000</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+<smbconfoption name="winbind nested groups">Yes</smbconfoption>
+<smbconfoption name="printer admin">"BUTTERNET\Domain Admins"</smbconfoption>
+</smbconfblock>
+</example>
+
+ <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 an &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</primary><secondary>ads</secondary><tertiary>join</tertiary></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>
+ <indexterm><primary>failure</primary></indexterm>
+ <indexterm><primary>log level</primary></indexterm>
+ <indexterm><primary>identify</primary></indexterm>
+ The specific error message may differ from the above because it depends on the type of failure that
+ may have occurred. Increase the <parameter>log level</parameter> to 10, repeat the test,
+ and then examine the log files produced to identify the nature of the failure.
+ </para></step>
+
+ <step><para>
+ Start the <command>nmbd</command>, <command>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 downside 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 using 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> 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 and Active Directory.
+ To use this with an NT4 domain, do not include the <parameter>realm</parameter> parameter; 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 in <link linkend="idmapadsridDMS">ADS
+ Domain Member smb.conf using idmap_rid</link>.
+ </para>
+
+<example id="idmapadsridDMS">
+<title>ADS Domain Member smb.conf using idmap_rid</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">KPAK</smbconfoption>
+<smbconfoption name="netbios name">BIGJOE</smbconfoption>
+<smbconfoption name="realm">CORP.KPAK.COM</smbconfoption>
+<smbconfoption name="server string">Office Server</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="allow trusted domains">No</smbconfoption>
+<smbconfoption name="idmap backend">idmap_rid:KPAK=500-100000000</smbconfoption>
+<smbconfoption name="idmap uid">500-100000000</smbconfoption>
+<smbconfoption name="idmap gid">500-100000000</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+<smbconfoption name="winbind enum users">No</smbconfoption>
+<smbconfoption name="winbind enum groups">No</smbconfoption>
+<smbconfoption name="winbind nested groups">Yes</smbconfoption>
+<smbconfoption name="printer admin">"Domain Admins"</smbconfoption>
+</smbconfblock>
+</example>
+
+ <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 example, 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 startup of
+ <command>winbind</command>. Disabling 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 following procedure.
+ </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 use the idmap_rid facility:
+ </para>
+
+ <procedure>
+ <step><para>
+ Create or install an &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 because it depends on the type of failure that
+ may have occurred. Increase the <parameter>log level</parameter> to 10, repeat the test,
+ and then examine the log files produced to identify the nature of the failure.
+ </para></step>
+
+ <step><para>
+ Start the <command>nmbd</command>, <command>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 and
+ 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>
+ An example is for an ADS domain is shown in <link linkend="idmapldapDMS">ADS Domain Member Server using
+ LDAP</link>.
+ </para>
+
+<example id="idmapldapDMS">
+<title>ADS Domain Member Server using LDAP</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">SNOWSHOW</smbconfoption>
+<smbconfoption name="netbios name">GOODELF</smbconfoption>
+<smbconfoption name="realm">SNOWSHOW.COM</smbconfoption>
+<smbconfoption name="server string">Samba Server</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="log level">1 ads:10 auth:10 sam:10 rpc:10</smbconfoption>
+<smbconfoption name="ldap admin dn">cn=Manager,dc=SNOWSHOW,dc=COM</smbconfoption>
+<smbconfoption name="ldap idmap suffix">ou=Idmap</smbconfoption>
+<smbconfoption name="ldap suffix">dc=SNOWSHOW,dc=COM</smbconfoption>
+<smbconfoption name="idmap backend">ldap:ldap://ldap.snowshow.com</smbconfoption>
+<smbconfoption name="idmap uid">150000-550000</smbconfoption>
+<smbconfoption name="idmap gid">150000-550000</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+ <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">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 cannot 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 because 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 effect 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 as shown 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 and initialize the directory with the top-level entries needed by IDMAP,
+ 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 DMS 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</command>, <command>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>
+ An example &smb.conf; file is shown in <link linkend="idmaprfc2307">ADS Domain Member Server using
+RFC2307bis Schema Extension Date via NSS</link>.
+ </para>
+
+<example id="idmaprfc2307">
+<title>ADS Domain Member Server using RFC2307bis Schema Extension Date via NSS</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">BOBBY</smbconfoption>
+<smbconfoption name="realm">BOBBY.COM</smbconfoption>
+<smbconfoption name="security">ADS</smbconfoption>
+<smbconfoption name="idmap uid">150000-550000</smbconfoption>
+<smbconfoption name="idmap gid">150000-550000</smbconfoption>
+<smbconfoption name="template shell">/bin/bash</smbconfoption>
+<smbconfoption name="winbind cache time">5</smbconfoption>
+<smbconfoption name="winbind use default domain">Yes</smbconfoption>
+<smbconfoption name="winbind trusted domains only">Yes</smbconfoption>
+<smbconfoption name="winbind nested groups">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+ <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 of 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-xml/Samba3-HOWTO/TOSHARG-Install.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Install.xml
new file mode 100644
index 0000000000..9894ed2854
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Install.xml
@@ -0,0 +1,702 @@
+<?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>
+ <indexterm><primary>packages</primary></indexterm>
+ 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>
+ <indexterm><primary>compile</primary></indexterm>
+ 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>
+ <indexterm><primary>/etc/samba/smb.conf</primary></indexterm>
+ <indexterm><primary>SWAT</primary></indexterm>
+ 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>
+ <indexterm><primary>section name</primary></indexterm>
+ The &smb.conf; file uses the same syntax as the various old <filename>.ini</filename> files in Windows
+ 3.1: Each file consists of various sections, which are started by putting the section name between brackets
+ (<literal>[]</literal>) on a new line. Each contains zero or more key/value pairs separated by an equality
+ sign (<literal>=</literal>). The file is just a plaintext file, so you can open and edit it with your favorite
+ editing tool.
+ </para>
+
+ <para>
+ <indexterm><primary>meta-service</primary></indexterm>
+ <indexterm><primary>print</primary><secondary>queue</secondary></indexterm>
+ <indexterm><primary>share</primary></indexterm>
+ <indexterm><primary>spooler.</primary></indexterm>
+ <indexterm><primary>print</primary><secondary>spooler</secondary></indexterm>
+ <indexterm><primary>spool</primary><secondary>directory</secondary></indexterm>
+ Each section in the &smb.conf; file represents either a share or a meta-service on the Samba server. The
+ section <literal>[global]</literal> is special, since it contains settings that apply to the whole Samba
+ server. Samba supports a number of meta-services, each of which serves its own purpose. For example, the
+ <literal>[homes]</literal> share is a meta-service that causes Samba to provide a personal home share for
+ each user. The <literal>[printers]</literal> share is a meta-service that establishes print queue support
+ and that specifies the location of the intermediate spool directory into which print jobs are received
+ from Windows clients prior to being dispatched to the UNIX/Linux print spooler.
+ </para>
+
+ <para>
+<indexterm><primary>printers</primary></indexterm>
+<indexterm><primary>meta-service</primary></indexterm>
+<indexterm><primary>printcap</primary></indexterm>
+<indexterm><primary>lpstat</primary></indexterm>
+<indexterm><primary>CUPS API</primary></indexterm>
+<indexterm><primary>browseable</primary></indexterm>
+ The <literal>printers</literal> meta-service will cause every printer that is either specified in a
+ <literal>printcap</literal> file, via the <command>lpstat</command>, or via the CUPS API, to be
+ published as a shared print queue. The <literal>printers</literal> stanza in the &smb.conf; file can
+ be set as not browseable. If it is set to be browseable, then it will be visible as if it is a share.
+ That makes no sense given that this meta-service is responsible only for making UNIX system printers
+ available as Windows print queues. If a <literal>comment</literal> parameter is specified, the value
+ of it will be displayed as part of the printer name in Windows Explorer browse lists.
+ </para>
+
+ <para>
+ <indexterm><primary>stanza</primary></indexterm>
+ Each section of the &smb.conf; file that specifies a share, or a meta-service, is called a stanza.
+ The <literal>global</literal> stanza specifies settings that affect all the other stanzas in the
+ &smb.conf; file. Configuration parameters are documented in the &smb.conf; man page. Some parameters
+ can be used only in the <literal>global</literal> stanza, some only in share or meta-service stanzas,
+ and some can be used globally or just within a share or meta-service stanza.
+ </para>
+
+ <para>
+ <indexterm><primary>minimal</primary><secondary>configuration</secondary></indexterm>
+ <link linkend="smbconfminimal">A minimal smb.conf</link> contains a very minimal &smb.conf;.
+ <indexterm><primary>minimal configuration</primary></indexterm>
+ </para>
+
+ <example id="smbconfminimal">
+ <title>A minimal smb.conf</title>
+ <smbconfblock>
+
+ <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>
+ </smbconfblock>
+ </example>
+
+</sect2>
+
+<sect2 id="tdbdocs">
+ <title>TDB Database File Information</title>
+
+ <para>
+ This section contains brief descriptions of the databases that are used by Samba-3.
+ </para>
+
+ <para>
+<indexterm><primary>tdb file locations</primary></indexterm>
+ The directory in which Samba stores the tdb files is determined by compile-time directives. Samba-3 stores
+ tdb files in two locations. The best way to determine these locations is to execute the following
+ command:
+<screen>
+&rootprompt; smbd -b | grep PRIVATE_DIR
+ PRIVATE_DIR: /etc/samba/private
+</screen>
+ This means that the confidential tdb files are stored in the <filename>/etc/samba/private</filename>
+ directory. Samba-3 also uses a number of tdb files that contain more mundane data. The location of
+ these files can be found by executing:
+<screen>
+&rootprompt; smbd -b | grep LOCKDIR
+ LOCKDIR: /var/lib/samba
+</screen>
+ Therefore the remaining control files will, in the example shown, be stored in the
+ <filename>/var/lib/samba</filename> directory.
+ </para>
+
+ <para>
+<indexterm><primary>tdb file descriptions</primary></indexterm>
+ The persistent tdb files are described in <link linkend="tdbpermfiledesc">the Persistent TDB File
+ Descriptions table</link>. All persistent tdb files should be regularly backed up. Use the
+ <command>tdbbackup</command> utility to backup the tdb files. All persistent tdb files must be
+ preserved during machine migrations, updates and upgrades.
+ </para>
+
+ <para>
+ The temporary tdb files do not need to be backed up, nor do they need to be preseved across machine
+ migrations, updates or upgrades. The temporary tdb files are described in <link linkend="tdbtempfiledesc">
+ the Temporary TDB File Descriptions</link>.
+ </para>
+
+ <table frame='all' id="tdbpermfiledesc"><title>Persistent TDB File Descriptions</title>
+ <tgroup cols='2'>
+ <colspec align="left"/>
+ <colspec align="justify" colwidth="1*"/>
+ <colspec align="left"/>
+ <thead>
+ <row>
+ <entry align="left">Name</entry>
+ <entry align="justify">Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>account_policy</entry>
+ <entry><para>Samba/NT account policy settings, includes password expiration settings.</para></entry>
+ </row>
+ <row>
+ <entry>group_mapping</entry>
+ <entry><para>Mapping table from Windows groups/SID to UNIX groups.</para></entry>
+ </row>
+ <row>
+ <entry>ntdrivers</entry>
+ <entry><para>Stores per-printer installed driver information.</para></entry>
+ </row>
+ <row>
+ <entry>ntforms</entry>
+ <entry><para>Stores per-printer installed forms information.</para></entry>
+ </row>
+ <row>
+ <entry>ntprinters</entry>
+ <entry><para>Stores the per-printer devmode configuration settings.</para></entry>
+ </row>
+ <row>
+ <entry>passdb</entry>
+ <entry><para>
+ Exists only when the tdbsam passwd backend is used. This file stores the
+ SambaSAMAccount information. Note: This file requires that user POSIX account information is
+ availble from either the /etc/passwd file, or from an alternative system source.
+ </para></entry>
+ </row>
+ <row>
+ <entry>registry</entry>
+ <entry><para>
+ Read-only Samba database of a Windows registry skeleton that provides support for exporting
+ various database tables via the winreg RPCs.
+ </para></entry>
+ </row>
+ <row>
+ <entry>secrets</entry>
+ <entry><para>
+ This file stores the Workgroup/Domain/Machine SID, the LDAP directory update password, and
+ a further collection of critical environmental data that is necessary for Samba to operate
+ correctly. This file contains very sensitive information that must be protected. It is stored
+ in the PRIVATE_DIR directory.
+ </para></entry>
+ </row>
+ <row>
+ <entry>share_info</entry>
+ <entry><para>Stores per-share ACL information.</para></entry>
+ </row>
+ <row>
+ <entry>winbindd_idmap</entry>
+ <entry><para>Winbindd's local IDMAP database.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame='all' id="tdbtempfiledesc"><title>Temporary 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>brlock</entry>
+ <entry><para>Byte-range locking information.</para></entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>connections</entry>
+ <entry><para>A temporary cache for current connection information used to enforce max connections.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>eventlog/*tdb</entry>
+ <entry><para>Records of eventlog entries. In most circumstances this is just a cache of system logs.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>gencache</entry>
+ <entry><para>Generic caching database for dead WINS servers and trusted domain data.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>login_cache</entry>
+ <entry><para>A temporary cache for login information, in particular bad password attempts.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>messages</entry>
+ <entry><para>Temporary storage of messages being processed by smbd.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>netsamlogon_cache</entry>
+ <entry><para>Caches user net_info_3 structure data from net_samlogon requests (as a domain member).</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>perfmon/*.tdb</entry>
+ <entry><para>Performance counter information.</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>schannel_store</entry>
+ <entry><para>
+ A confidential file, stored in the PRIVATE_DIR, containing crytographic connection
+ information so that clients that have temporarily disconnected can reconnect without
+ needing to renegotiate the connection setup process.
+ </para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>sessionid</entry>
+ <entry><para>Temporary cache for miscellaneous session information and for utmp handling.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>unexpected</entry>
+ <entry><para>Stores packets received for which no process is actively listening.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>winbindd_cache</entry>
+ <entry><para>Cache of Identity information received from an NT4 domain or from ADS. Includes user
+ lists, etc.</para></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+</sect2>
+
+<sect2>
+ <title>Starting Samba</title>
+
+ <para>
+ <indexterm><primary>daemon</primary></indexterm>
+ 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 startup 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 startup 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 are found, <command>winbindd</command> will use the values specified for
+ for UID and GID allocation. If these parameters are not specified, <command>winbindd</command>
+ will start but it will not be able to allocate UIDs or GIDs.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <indexterm><primary>startup</primary><secondary>process</secondary></indexterm>
+ When Samba has been packaged by an operating system vendor, the startup 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 startup.
+ </para>
+
+</sect2>
+
+<sect2>
+ <title>Example Configuration</title>
+
+ <para>
+ <indexterm><primary>examples</primary></indexterm>
+ <indexterm><primary>source code</primary></indexterm>
+ <indexterm><primary>distribution</primary></indexterm>
+ <indexterm><primary>tarball</primary></indexterm>
+ <indexterm><primary>package</primary></indexterm>
+ There are sample configuration files in the examples subdirectory in the source code distribution tarball
+ package. 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
+ <filename>smb.conf.default</filename> configuration file and adapt it to your needs. It contains plenty of comments.
+ </para>
+
+ <para>
+ <indexterm><primary>simplest</primary><secondary>configuration</secondary></indexterm>
+ The simplest useful configuration file would contain something like that shown in
+ <link linkend="simple-example">Another simple smb.conf File</link>.
+ <indexterm><primary>simple configuration</primary></indexterm>
+ </para>
+
+<example id="simple-example">
+<title>Another simple smb.conf File</title>
+<smbconfblock>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
+
+<smbconfsection name="[homes]"/>
+<smbconfoption name="guest ok">no</smbconfoption>
+<smbconfoption name="read only">no</smbconfoption>
+</smbconfblock>
+</example>
+
+ <para>
+ <indexterm><primary>connections</primary></indexterm>
+ <indexterm><primary>account</primary></indexterm>
+ <indexterm><primary>login name</primary></indexterm>
+ <indexterm><primary>service name</primary></indexterm>
+ 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>
+ <indexterm><primary>smbd</primary></indexterm>
+ Make sure you put the &smb.conf; file in the correct place. Note, the correct location of this file
+ depends on how the binary files were built. You can discover the correct location by executing from
+ the directory that contains the <command>smbd</command> command file:
+<screen>
+&rootprompt; smbd -b | grep smb.conf
+</screen>
+ </para>
+
+ <para>
+ <indexterm><primary>security</primary><secondary>settings</secondary></indexterm>
+ For more information about security settings for the <smbconfsection name="[homes]"/> share, please refer to
+ <link linkend="securing-samba">Securing Samba</link>.
+ </para>
+
+<sect3>
+ <title>Test Your Config File with <command>testparm</command></title>
+
+ <para>
+ <indexterm><primary>validate</primary></indexterm>
+ <indexterm><primary>testparm</primary></indexterm>
+ <indexterm><primary>misconfigurations</primary></indexterm>
+ 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:
+ <screen>
+ &rootprompt; testparm /etc/samba/smb.conf
+ </screen>
+ Testparm will parse your configuration file and report any unknown parameters or incorrect syntax.
+ It also performs a check for common misconfigurations and will issue a warning if one is found.
+ </para>
+
+ <para>
+ Always run testparm again whenever the &smb.conf; file is changed!
+ </para>
+
+ <para>
+ <indexterm><primary>smbd</primary></indexterm>
+ <indexterm><primary>nmbd</primary></indexterm>
+ <indexterm><primary>winbindd</primary></indexterm>
+ <indexterm><primary>configuration</primary><secondary>documentation</secondary></indexterm>
+ The &smb.conf; file is constantly checked by the Samba daemons <command>smbd</command> and every instance of
+ itself that it spawns, <command>nmbd</command> and <command>winbindd</command>. It is good practice to
+ keep this file as small as possible. Many administrators prefer to document Samba configuration settings
+ and thus the need to keep this file small goes against good documentation wisdom. One solution that may
+ be adopted is to do all documentation and configuration in a file that has another name, such as
+ <filename>smb.conf.master</filename>. The <command>testparm</command> utility can be used to generate a
+ fully optimized &smb.conf; file from this master configuration and documtenation file as shown here:
+<screen>
+&rootprompt; testparm -s smb.conf.master > smb.conf
+</screen>
+ This administrative method makes it possible to maintain detailed configuration change records while at
+ the same time keeping the working &smb.conf; file size to the minimum necessary.
+ </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. If it is
+ necesaary to built SWAT please read the SWAT man page regarding compilation, installation, and
+ configuration of SWAT from the source code.
+ </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 because passwords will be sent over the wire in the clear.
+ </para>
+
+ <para>
+ More information about SWAT can be found in <link linkend="SWAT">The Samba Web Administration Tool</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 username 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:
+<screen>
+&dosprompt;<userinput>net use m: \\servername\service</userinput>
+</screen>
+ Where the drive letter m: is any available drive letter. It is important to double-check that the
+ service (share) name that you used does actually exist.
+ </para>
+
+ <para>
+ Try printing, for example,
+<screen>
+&dosprompt;<userinput>net use lpt1: \\servername\spoolservice</userinput>
+</screen>
+ The <literal>spoolservice</literal> is the name of the printer (actually the print queue) on the target
+ server. This will permit all print jobs that are captured by the lpt1: port on the Windows client to
+ be sent to the printer that owns the spoolservice that has been specified.
+ </para>
+
+<para>
+<screen>&dosprompt;<userinput>print filename</userinput>
+</screen></para>
+
+ <sect2>
+ <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>. 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>
+
+ <para>
+ If you are new to Samba, and particularly if you are new to Windows networking, or to UNIX/Linux,
+ the book <quote>Samba-3 by Example</quote> will help you to create a validated network environment.
+ Simply choose from the first five chapters the network design that most closely matches site needs,
+ then follow the simple step-by-step procedure to deploy it. Later, when you have a working network
+ you may well want to refer back to this book for further insight into opportunities for improvement.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Still Stuck?</title>
+
+ <para>
+ The best advice under the stress of abject frustration is to cool down! That may be challenging
+ of itself, but while you are angry or annoyed your ability to seek out a solution is somewhat
+ undermined. A cool head clears the way to finding the answer you are looking for. Just remember,
+ every problem has a solution &smbmdash; there is a good chance that someone else has found it
+ even though you can't right now. That will change with time, patience and learning.
+ </para>
+
+ <para>
+ Now that you have cooled down a bit, please refer to <link linkend="diagnosis">the Samba Checklist</link>
+ for a process that can be followed to identify the cause of your problem.
+ </para>
+
+ </sect2>
+
+</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 misconfigurations:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>You specified a nonexisting 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-xml/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml
new file mode 100644
index 0000000000..68b9d49b69
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Integrating-with-Windows.xml
@@ -0,0 +1,745 @@
+<?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 chapter 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 chapter may help you to resolve networking problems.
+</para>
+
+<note>
+<para>
+<indexterm><primary>NetBEUI</primary></indexterm>
+<indexterm><primary>LLC</primary></indexterm>
+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 that 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>
+<indexterm><primary>NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>UDP port 137</primary></indexterm>
+<indexterm><primary>TCP port 139</primary></indexterm>
+<indexterm><primary>TCP port 445</primary></indexterm>
+<indexterm><primary>UDP port 137</primary></indexterm>
+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 is
+used, and the UDP port 137 and TCP port 139 are 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>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>DDNS</primary></indexterm>
+<indexterm><primary>SRV RR</primary></indexterm>
+<indexterm><primary>IXFR</primary></indexterm>
+<indexterm><primary>DHCP</primary></indexterm>
+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>
+
+<indexterm><primary>/etc/hosts</primary></indexterm>
+<indexterm><primary>/etc/resolv.conf</primary></indexterm>
+<indexterm><primary>/etc/host.conf</primary></indexterm>
+<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+
+<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.
+<programlisting>
+127.0.0.1 localhost localhost.localdomain
+192.168.1.1 bigbox.quenya.org bigbox alias4box
+</programlisting>
+</para>
+
+<para>
+<indexterm><primary>/etc/hosts></primary></indexterm>
+<indexterm><primary>name resolution</primary></indexterm>
+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>
+<indexterm><primary>IP addresses</primary></indexterm>
+<indexterm><primary>MAC address</primary></indexterm>
+<indexterm><primary>physical network transport layer</primary></indexterm>
+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 decimal
+numbers that are separated by a dot (or period) &smbmdash; 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 Address Resolution Protocol (ARP) reply.
+</para>
+
+<para>
+<indexterm><primary>machine name</primary></indexterm>
+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>
+<indexterm><primary>ARP/RARP</primary></indexterm>
+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 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:
+<programlisting>
+order hosts,bind
+multi on
+</programlisting></para>
+
+<para>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:
+<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>
+<indexterm><primary>NetBIOS names</primary></indexterm>
+<indexterm><primary>make</primary></indexterm>
+<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+<indexterm><primary>wins</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>
+<indexterm><primary>computer name</primary></indexterm>
+<indexterm><primary>machine name</primary></indexterm>
+<indexterm><primary>NetBIOS name</primary></indexterm>
+<indexterm><primary>SMB name</primary></indexterm>
+MS Windows networking is predicated on 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> which 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 1-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&lt;00&gt;</entry><entry>Server Service is running on MACHINENAME</entry></row>
+<row><entry>MACHINENAME&lt;03&gt;</entry><entry>Generic machine name (NetBIOS name)</entry></row>
+<row><entry>MACHINENAME&lt;20&gt;</entry><entry>LanMan server service is running on MACHINENAME</entry></row>
+<row><entry>WORKGROUP&lt;1b&gt;</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&lt;03&gt;</entry><entry>Generic name registered by all members of WORKGROUP</entry></row>
+<row><entry>WORKGROUP&lt;1c&gt;</entry><entry>Domain cntrollers/netlogon servers</entry></row>
+<row><entry>WORKGROUP&lt;1d&gt;</entry><entry>Local master browsers</entry></row>
+<row><entry>WORKGROUP&lt;1e&gt;</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 <link linkend="uniqnetbiosnames">Unique NetBIOS names</link> and <link
+linkend="netbiosnamesgrp">group names</link>. This is in vast contrast to TCP/IP
+installations where the system administrator traditionally
+determines 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>
+<indexterm><primary>/etc/hosts</primary></indexterm>
+<indexterm><primary>NetBIOS name</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 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 *&lt;1C&gt;. 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>
+<indexterm><primary>domain</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+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 username and a matching password.
+</para>
+
+<para>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>Network Basic Input/Output System</primary><see>NetBIOS</see></indexterm>
+<indexterm><primary>Logical Link Control</primary><see>LLC</see></indexterm>
+<indexterm><primary>Network Basic Extended User Interface</primary><see>NetBEUI</see></indexterm>
+<indexterm><primary>Internetworking Packet Exchange</primary><see>IPX</see></indexterm>
+<indexterm><primary>NetWare</primary></indexterm>
+<indexterm><primary>NetBT</primary></indexterm>
+<indexterm><primary>NBT</primary></indexterm>
+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 (Internetworking 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>
+<indexterm><primary>n-memory buffer</primary></indexterm>
+<indexterm><primary>local cache</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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 to 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>
+<indexterm><primary>name lookup</primary></indexterm>
+If a machine whose name is in the local name cache is shut
+down before the name is expired and flushed from the cache, then
+an attempt to exchange a message with that machine will be subject
+to timeout 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>
+<indexterm><primary>NetBIOS</primary></indexterm>
+The MS Windows utility that allows examination of the NetBIOS
+name cache is called <quote>nbtstat.</quote> The Samba equivalent
+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:&lt;domain&gt;
+# #INCLUDE &lt;filename&gt;
+# #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 preloaded into the name cache. By default, entries are
+# not preloaded, but are parsed only after dynamic name resolution fails.
+#
+# Following an entry with the "#DOM:&lt;domain&gt;" tag will associate the
+# entry with the domain specified by &lt;domain&gt;. 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 &lt;domain&gt; is always pre-loaded although it will not
+# be shown when the name cache is viewed.
+#
+# Specifying "#INCLUDE &lt;filename&gt;" will force the RFC NetBIOS (NBT)
+# software to seek the specified &lt;filename&gt; and parse it as if it were
+# local. &lt;filename&gt; 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 dependent 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>
+<indexterm><primary>Windows Internet Name Server</primary><see>WINS</see></indexterm>
+<indexterm><primary>NetBIOS Name Server</primary><see>NBNS</see></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>
+<indexterm><primary>WINS</primary></indexterm>
+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 to forgetfulness to simple mistakes to
+carelessness. Of course, no one is ever deliberately careless!
+</para>
+
+ <sect2>
+ <title>Pinging Works Only 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>
+ 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 out 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, and now the Samba server cannot be
+ pinged by its new name from an MS Windows NT4 workstation, but it does still respond to pinging 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 or 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; &lt;03&gt; UNIQUE Registered
+ADMINISTRATOR &lt;03&gt; UNIQUE Registered
+&example.workstation.windows; &lt;00&gt; UNIQUE Registered
+SARDON &lt;00&gt; GROUP Registered
+&example.workstation.windows; &lt;20&gt; UNIQUE Registered
+&example.workstation.windows; &lt;1F&gt; UNIQUE Registered
+
+
+&dosprompt;nbtstat -c
+
+ NetBIOS Remote Cache Name Table
+
+ Name Type Host Address Life [sec]
+--------------------------------------------------------------
+&example.server.samba; &lt;20&gt; UNIQUE 192.168.1.1 240
+
+&dosprompt;
+</screen>
+ </para>
+
+ <para>
+ In this 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-xml/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml b/docs-xml/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml
new file mode 100644
index 0000000000..3ea527ba5e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-InterdomainTrusts.xml
@@ -0,0 +1,602 @@
+<?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>
+<indexterm><primary>NT4-style domain</primary></indexterm>
+<indexterm><primary>trust relationships</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>LDAP-based</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 chapter 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>
+<indexterm><primary>daemon</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+The use of interdomain trusts requires use of <command>winbind</command>, so the
+<command>winbindd</command> daemon must be running. Winbind operation in this mode is
+dependent on the specification of a valid UID range and a valid GID range in the &smb.conf; file.
+These are specified respectively using:
+<smbconfblock>
+<smbconfoption name="idmap uid">10000-20000</smbconfoption>
+<smbconfoption name="idmap gid">10000-20000</smbconfoption>
+</smbconfblock>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>POSIX user accounts</primary></indexterm>
+<indexterm><primary>maximum value</primary></indexterm>
+<indexterm><primary>4294967295</primary></indexterm>
+The range of values specified must not overlap values used by the host operating system and must
+not overlap values used in the passdb backend for POSIX user accounts. The maximum value is
+limited by the upper-most value permitted by the host operating system. This is a UNIX kernel
+limited parameter. Linux kernel 2.6-based systems support a maximum value of 4294967295
+(32-bit unsigned variable).
+</para>
+
+<note><para>
+<indexterm><primary>winbind</primary></indexterm>
+<indexterm><primary>trusting domain</primary></indexterm>
+<indexterm><primary>trusted domain</primary></indexterm>
+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>
+<indexterm><primary>scalability</primary></indexterm>
+<indexterm><primary>trust relationships</primary></indexterm>
+Samba-3 can participate in Samba-to-Samba as well as in Samba-to-MS Windows NT4-style
+trust relationships. This imparts to Samba scalability similar to that with MS Windows NT4.
+</para>
+
+<para>
+<indexterm><primary>scalable backend</primary></indexterm>
+<indexterm><primary>authentication database</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>interdomain trusts</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+Given that Samba-3 can 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 trusts
+function, this system 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>
+<indexterm><primary>security domains</primary></indexterm>
+<indexterm><primary>nonhierarchical</primary></indexterm>
+<indexterm><primary>security structure</primary></indexterm>
+<indexterm><primary>large organizations</primary></indexterm>
+<indexterm><primary>delegation</primary></indexterm>
+<indexterm><primary>administrative responsibilities</primary></indexterm>
+MS Windows NT3/4-type security domains employ a nonhierarchical 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>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>limitations</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+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, and so there remains an entrenched user base for whom there is no direct
+desire to go through a disruptive change to adopt ADS.
+</para>
+
+<para>
+<indexterm><primary>security domains</primary></indexterm>
+<indexterm><primary>access rights</primary></indexterm>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>trusts</primary></indexterm>
+<indexterm><primary>trusted domain</primary></indexterm>
+<indexterm><primary>trusting domain</primary></indexterm>
+<indexterm><primary>one direction</primary></indexterm>
+With Windows NT, Microsoft introduced the ability to allow different 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 can access 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,
+so 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>
+<indexterm><primary>security domain</primary></indexterm>
+<indexterm><primary>nontransitive</primary></indexterm>
+<indexterm><primary>trust relationship</primary></indexterm>
+<indexterm><primary>transitive</primary></indexterm>
+<indexterm><primary>explicit trust</primary></indexterm>
+Further, in an NT4-style MS security domain, all trusts are nontransitive. 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>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>security contexts</primary></indexterm>
+<indexterm><primary>trust relationships</primary></indexterm>
+<indexterm><primary>two-way trust</primary></indexterm>
+<indexterm><primary>Windows 2000</primary></indexterm>
+<indexterm><primary>security domains</primary></indexterm>
+<indexterm><primary>NT4-style domains</primary></indexterm>
+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, 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>
+<indexterm><primary>Interdomain Trusts</primary><secondary>creating</secondary></indexterm>
+<indexterm><primary>two-way trust</primary></indexterm>
+<indexterm><primary>security credentials</primary></indexterm>
+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.
+</para>
+
+
+<sect2>
+<title>Creating an NT4 Domain Trust</title>
+
+<para>
+<indexterm><primary>domain trust</primary></indexterm>
+<indexterm><primary>trust relationships</primary></indexterm>
+<indexterm><primary>>Domain User Manager</primary></indexterm>
+<indexterm><primary>remote domain</primary></indexterm>
+<indexterm><primary>standard confirmation</primary></indexterm>
+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>trust relationship</primary></indexterm>
+<indexterm><primary>trusting domain</primary></indexterm>
+<indexterm><primary>trusted domain</primary></indexterm>
+<indexterm><primary>remote domain</primary></indexterm>
+<indexterm><primary>password assigned</primary></indexterm>
+<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 launches the
+Domain User Manager from the menu selects <guilabel>Policies</guilabel>, then select
+<guilabel>Trust Relationships</guilabel>, and clicks on the <guibutton>Add</guibutton> button
+next to the box that is labeled <guilabel>Trusted Domains</guilabel>. A panel opens in which
+must be entered the name of the remote domain as well as the password assigned to that trust.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Interdomain Trust Facilities</title>
+
+
+<para>
+<indexterm><primary>two-way trust</primary></indexterm>
+<indexterm><primary>trust relationship</primary></indexterm>
+<indexterm><primary>trust established</primary></indexterm>
+<indexterm><primary>one-way trust</primary></indexterm>
+<indexterm><primary>Windows NT4 domains</primary></indexterm>
+<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>
+
+<figure id="trusts1">
+ <title>Trusts overview.</title>
+ <imagefile>trusts1</imagefile>
+</figure>
+
+<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 and 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>
+<indexterm><primary>interdomain trust</primary></indexterm>
+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>
+<indexterm><primary>peer domain</primary></indexterm>
+<indexterm><primary>trust relationship</primary></indexterm>
+<indexterm><primary>Windows NT4 Server</primary></indexterm>
+<indexterm><primary>between domains</primary></indexterm>
+Each of the procedures described next 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 in the following
+sections leads to trust between domains in a purely Samba environment.
+</para>
+
+<sect2 id="samba-trusted-domain">
+<title>Samba as the Trusted Domain</title>
+
+<para>
+<indexterm><primary>trusted party</primary></indexterm>
+<indexterm><primary>special account</primary></indexterm>
+<indexterm><primary>trusting party</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+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 to <quote>create this
+account with the Interdomain trust flag</quote>.
+</para>
+
+<para>
+<indexterm><primary>account name</primary></indexterm>
+<indexterm><primary>remote domain</primary></indexterm>
+<indexterm><primary>password database</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+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 previous step.
+</para>
+
+<para>
+<indexterm><primary>password</primary></indexterm>
+<indexterm><primary>new account</primary></indexterm>
+<indexterm><primary>confirm the trust</primary></indexterm>
+<indexterm><primary>Windows NT Server</primary></indexterm>
+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 7 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 the account's 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>
+<indexterm><primary>trusted domain name</primary></indexterm>
+<indexterm><primary>relationship password</primary></indexterm>
+<indexterm><primary>remote domain</primary></indexterm>
+<indexterm><primary>established</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>
+<indexterm><primary>NT-controlled domain</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+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>
+<indexterm><primary>trusted domain</primary></indexterm>
+<indexterm><primary>password</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>Trusting 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>
+<indexterm><primary>password</primary></indexterm>
+<indexterm><primary>confirm the password</primary></indexterm>
+The password can be arbitrarily chosen. It is easy to change the password from the Samba server whenever you
+want. After you confirm the password, your account is ready for use. Now its Samba's turn.
+</para>
+
+<para>
+Using your favorite shell while logged in as root, issue this command:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom establish</tertiary></indexterm>
+</para>
+
+<para>
+&rootprompt;<userinput>net rpc trustdom establish rumba</userinput>
+</para>
+
+<para>
+<indexterm><primary>password</primary></indexterm>
+<indexterm><primary>interdomain connection</primary></indexterm>
+<indexterm><primary>ordinary connection</primary></indexterm>
+You will be prompted for the password you just typed on your Windows NT4 Server box.
+An error message, <literal>"NT_STATUS_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT,"</literal>
+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 <literal>Success</literal> 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>
+<indexterm><primary>trust relationship</primary></indexterm>
+<indexterm><primary>Windows 2000 server</primary></indexterm>
+<indexterm><primary>NT4-style</primary></indexterm>
+<indexterm><primary>mixed mode</primary></indexterm>
+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>
+<indexterm><primary>interdomain trust</primary></indexterm>
+<indexterm><primary>trust account</primary></indexterm>
+<indexterm><primary>not transitive</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+After <link linkend="samba-trusted-domain">creating the interdomain trust account on the Samba server</link>
+as described previously, 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 <emphasis>OK</emphasis> 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>
+<emphasis>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:</emphasis>
+<screen>
+The system detected a possible attempt to compromise security. Please
+ensure that you can contact the server that authenticated you.
+</screen>
+</para>
+
+<para>
+<emphasis>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.</emphasis>
+</para>
+
+<para>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 unjoin 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 that has privileges to do this
+when you unjoin the machine, it is done; otherwise it is not done.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Problems with LDAP ldapsam and Older Versions of 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 <literal>[W ]</literal>, when it must have
+<literal>[I ]</literal> for interdomain trusts to work.
+</para>
+
+<para>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 domain controllers, Samba and NT must have the same WINS server; otherwise,
+the trust will never work.
+</para>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-IntroSMB.xml b/docs-xml/Samba3-HOWTO/TOSHARG-IntroSMB.xml
new file mode 100644
index 0000000000..dec4638e5b
--- /dev/null
+++ b/docs-xml/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>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>Reference Section</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-xml/Samba3-HOWTO/TOSHARG-LargeFile.xml b/docs-xml/Samba3-HOWTO/TOSHARG-LargeFile.xml
new file mode 100644
index 0000000000..5fdbe7a243
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-LargeFile.xml
@@ -0,0 +1,89 @@
+<?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>
+<indexterm><primary>performance degradation</primary></indexterm>
+<indexterm><primary>large numbers of files</primary></indexterm>
+<indexterm><primary>large directory</primary></indexterm>
+Samba-3.0.12 and later implements a solution for sites that have experienced performance degradation due to the
+problem of using Samba-3 with applications that need large numbers of files (100,000 or more) per directory.
+</para>
+
+<para>
+<indexterm><primary>read directory into memory</primary></indexterm>
+<indexterm><primary>strange delete semantics</primary></indexterm>
+The key was fixing the directory handling to read only the current list requested instead of the old
+(up to samba-3.0.11) behavior 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>
+<indexterm><primary>large directory</primary></indexterm>
+<indexterm><primary>performance</primary></indexterm>
+To set up an application that needs large numbers of files per directory in a way that does not
+damage performance unduly, follow these steps:
+</para>
+
+<para>
+<indexterm><primary>canonicalize files</primary></indexterm>
+First, you need to canonicalize all the files in the directory to have one case, upper or lower &smbmdash; take your
+pick (I chose upper because all my files were already uppercase names). Then set up a new custom share for the
+application as follows:
+<smbconfblock>
+<smbconfsection name="[bigshare]"/>
+<smbconfoption name="path">/data/manyfilesdir</smbconfoption>
+<smbconfoption name="read only">no</smbconfoption>
+<smbconfoption name="case sensitive">True</smbconfoption>
+<smbconfoption name="default case">upper</smbconfoption>
+<smbconfoption name="preserve case">no</smbconfoption>
+<smbconfoption name="short preserve case">no</smbconfoption>
+</smbconfblock>
+</para>
+
+<para>
+<indexterm><primary>case options</primary></indexterm>
+<indexterm><primary>match case</primary></indexterm>
+<indexterm><primary>uppercase</primary></indexterm>
+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 &smbmdash; any new files created in
+there and in any paths under it will be forced by smbd into uppercase, but smbd will no longer have to scan
+the directory for names: it knows that if a file does not exist in uppercase, then it doesn't exist at all.
+</para>
+
+<para>
+<indexterm><primary>case-insensitive</primary></indexterm>
+<indexterm><primary>consistent case</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+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 cannot 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>
+<indexterm><primary>uppercase</primary></indexterm>
+<indexterm><primary>stanza</primary></indexterm>
+<indexterm><primary>lowercase filenames</primary></indexterm>
+Remember, all files and directories under the <parameter>path</parameter> directory must be in uppercase
+with this &smb.conf; stanza because &smbd; will not be able to find lowercase filenames with these settings. Also
+note that this is done on a per-share basis, allowing this parameter to be set only for a share servicing an application with
+this problematic behavior (using large numbers of entries in a directory) &smbmdash; 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-xml/Samba3-HOWTO/TOSHARG-NT4Migration.xml b/docs-xml/Samba3-HOWTO/TOSHARG-NT4Migration.xml
new file mode 100644
index 0000000000..2688e060ac
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-NT4Migration.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="NT4Migration">
+<chapterinfo>
+ &author.jht;
+ <pubdate>April 3, 2003</pubdate>
+</chapterinfo>
+
+<title>Migration from NT4 PDC to Samba-3 PDC</title>
+
+<para>
+<indexterm><primary>migrate</primary></indexterm>
+<indexterm><primary>domain control</primary></indexterm>
+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>
+<indexterm><primary>show-stopper-type</primary></indexterm>
+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>
+<indexterm><primary>migration plan</primary></indexterm>
+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 underway.
+</para>
+
+<sect2>
+<title>Objectives</title>
+
+<para>
+<indexterm><primary>migration process</primary></indexterm>
+The key objective for most organizations is 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 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>
+<indexterm><primary>change motivations</primary></indexterm>
+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>
+
+<indexterm><primary>manageability</primary></indexterm>
+<indexterm><primary>functionality</primary></indexterm>
+<indexterm><primary>operating costs</primary></indexterm>
+<indexterm><primary>support exposure</primary></indexterm>
+<indexterm><primary>licensing</primary></indexterm>
+
+<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>
+<indexterm><primary>alternative solution</primary></indexterm>
+<indexterm><primary>advantages</primary></indexterm>
+<indexterm><primary>core values</primary></indexterm>
+<indexterm><primary>migration</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>without ADS</primary></indexterm>
+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>
+
+<indexterm><primary>Active Directory Server</primary></indexterm>
+<indexterm><primary>Group Policy Objects</primary></indexterm>
+<indexterm><primary>Machine Policy Objects</primary></indexterm>
+<indexterm><primary>Logon Scripts</primary></indexterm>
+<indexterm><primary>Access Controls</primary></indexterm>
+
+<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>
+
+<indexterm><primary>ownership cost</primary></indexterm>
+<indexterm><primary>Global support</primary></indexterm>
+<indexterm><primary>Dynamic SMB servers</primary></indexterm>
+<indexterm><primary>on-the-fly logon scripts</primary></indexterm>
+<indexterm><primary>on-the-fly policy files</primary></indexterm>
+<indexterm><primary>stability</primary></indexterm>
+<indexterm><primary>reliability</primary></indexterm>
+<indexterm><primary>performance</primary></indexterm>
+<indexterm><primary>availability</primary></indexterm>
+<indexterm><primary>Manageability</primary></indexterm>
+<indexterm><primary>backend authentication</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+<indexterm><primary>single-sign-on</primary></indexterm>
+<indexterm><primary>distribute authentication systems</primary></indexterm>
+
+<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 backend authentication technologies (tdbsam, ldapsam).</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>
+<indexterm><primary>successful migration</primary></indexterm>
+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 sections explain factors that will
+help ensure a successful migration.
+</para>
+
+<sect3>
+<title>Domain Layout</title>
+
+<para>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>backup domain controller</primary></indexterm>
+<indexterm><primary>secondary controller</primary></indexterm>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>standalone server</primary></indexterm>
+<indexterm><primary>network security</primary></indexterm>
+<indexterm><primary>domain context</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDCs</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>authentication backend</primary></indexterm>
+<indexterm><primary>complex organization</primary></indexterm>
+<indexterm><primary>LDAP database</primary></indexterm>
+<indexterm><primary>master server</primary></indexterm>
+<indexterm><primary>slave servers</primary></indexterm>
+<indexterm><primary>multiple domains</primary></indexterm>
+Samba-3 can be configured as a domain controller, a backup domain controller (probably best called
+a secondary controller), a domain member, or a standalone 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>
+<indexterm><primary>network bandwidth</primary></indexterm>
+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>
+<indexterm><primary>network segment</primary></indexterm>
+<indexterm><primary>multiple network segments</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>ping</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>remote segment</primary></indexterm>
+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 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>
+<indexterm><primary>Simplicity is king</primary></indexterm>
+<indexterm><primary>well-controlled network</primary></indexterm>
+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>
+<indexterm><primary>disk space</primary></indexterm>
+<indexterm><primary>backed up</primary></indexterm>
+<indexterm><primary>tape</primary></indexterm>
+<indexterm><primary>backup</primary></indexterm>
+<indexterm><primary>validate every backup</primary></indexterm>
+<indexterm><primary>disaster recovery</primary></indexterm>
+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>
+<indexterm><primary>access control needs</primary></indexterm>
+<indexterm><primary>group permissions</primary></indexterm>
+<indexterm><primary>sticky bit</primary></indexterm>
+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>
+<indexterm><primary>network administrators</primary></indexterm>
+<indexterm><primary>document design</primary></indexterm>
+<indexterm><primary>simple access controls</primary></indexterm>
+<indexterm><primary>obtuse complexity</primary></indexterm>
+<indexterm><primary>document design</primary></indexterm>
+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>
+<indexterm><primary>Logon scripts</primary></indexterm>
+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 effected 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>
+<indexterm><primary>kixstart</primary></indexterm>
+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>
+<indexterm><primary>NTuser.DAT</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>
+<indexterm><primary>migrate account settings</primary></indexterm>
+<indexterm><primary>migrate user</primary></indexterm>
+<indexterm><primary>migrate group</primary></indexterm>
+<indexterm><primary>map</primary></indexterm>
+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, you are 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>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>netlogon share</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+ Samba-3 is set up as a domain controller with netlogon share, profile share, and so on. Configure the &smb.conf; file
+ to function as a BDC: <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.
+ <emphasis>Samba must not be running.</emphasis>
+ </para></step>
+
+ <step><para>
+ <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
+ <userinput>net rpc join -S <replaceable>NT4PDC</replaceable> -w <replaceable>DOMNAME</replaceable> -U
+ Administrator%<replaceable>passwd</replaceable></userinput>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>vampire</tertiary></indexterm>
+ <userinput>net rpc vampire -S <replaceable>NT4PDC</replaceable> -U
+ administrator%<replaceable>passwd</replaceable></userinput>
+ </para></step>
+
+<indexterm><primary>pdbedit</primary></indexterm>
+ <step><para><userinput>pdbedit -L</userinput></para>
+ <para>Note: Did the users migrate?</para>
+ </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>)
+ <programlisting>
+#!/bin/bash
+#### Keep this as a shell script for future re-use
+
+# First assign well known domain global groups
+net groupmap add ntgroup="Domain Admins" unixgroup=root rid=512 type=d
+net groupmap add ntgroup="Domain Users" unixgroup=users rid=513 type=d
+net groupmap add ntgroup="Domain Guests" unixgroup=nobody rid=514 type=d
+
+# Now for our added domain global 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>
+ </para></step>
+
+ <step><para><userinput>net groupmap list</userinput></para>
+ <para>Check that all groups are recognized.
+ </para></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>&lt; 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 inhouse complexity.</para></entry></row>
+ <row><entry>&gt; 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 downstream 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 Install</entry><entry>Upgrade Decisions</entry><entry>Redesign Decisions</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>Improve on NT4 functionality, enhance management capabilities</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 autocreate home directories.</para></listitem>
+ <listitem><para> Samba-3 can use a local authentication backend: <parameter>smbpasswd</parameter>,
+ <parameter>tdbsam</parameter>, <parameter>ldapsam</parameter>
+ </para></listitem>
+ </itemizedlist></para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>Access Control Points</term><listitem>
+ <para>
+ Samba permits Access Control points to be set:
+ </para>
+
+<indexterm><primary>share ACLs</primary></indexterm>
+<indexterm><primary>UNIX permissions</primary></indexterm>
+<indexterm><primary>POSIX ACLS</primary></indexterm>
+<indexterm><primary>share stanza controls</primary></indexterm>
+
+ <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>
+<indexterm><primary>policies</primary></indexterm>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+ Exercise great caution when making registry changes; use the right tool and be aware
+ that changes made through NT4-style <filename>NTConfig.POL</filename> files can leave
+ permanent changes.
+<indexterm><primary>Group Policy Editor</primary></indexterm>
+<indexterm><primary>tattoo effect</primary></indexterm>
+<indexterm><primary>permanent changes</primary></indexterm>
+ </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>
+<indexterm><primary>NTUser.DAT</primary></indexterm>
+<indexterm><primary>SIDs</primary></indexterm>
+ 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 uppercase 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-xml/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml b/docs-xml/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml
new file mode 100644
index 0000000000..3c86438c2f
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-NetworkBrowsing.xml
@@ -0,0 +1,2218 @@
+<?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;
+ <author>
+ <firstname>Jonathan</firstname><surname>Johnson</surname>
+ <affiliation>
+ <orgname>Sutinen Consulting, Inc.</orgname>
+ <address><email>jon@sutinen.com</email></address>
+ </affiliation>
+ </author>
+ <pubdate>July 5, 1998</pubdate>
+ <pubdate>Updated: September 20, 2006</pubdate>
+</chapterinfo>
+
+<title>Network Browsing</title>
+
+<para>
+<indexterm><primary>browsing across subnets</primary></indexterm>
+<indexterm><primary>resolution of NetBIOS names</primary></indexterm>
+<indexterm><primary>browse list handling</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+This chapter 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; however, WINS is
+not involved in browse list handling except by way of name-to-address resolution.
+</para>
+
+<note><para>
+<indexterm><primary>WINS</primary></indexterm>
+What is WINS?
+</para>
+<para>
+WINS is a facility that provides resolution of a NetBIOS name to its IP address. WINS is like a
+Dynamic-DNS service for NetBIOS networking names.
+</para></note>
+
+<note><para>
+<indexterm><primary>Windows 2000</primary></indexterm>
+<indexterm><primary>NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+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>
+Charles Dickens 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>
+<indexterm><primary>NetBIOS networking</primary></indexterm>
+<indexterm><primary>fickle</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-19th
+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 7 years, and an
+ability to germinate at any time of year, given the right conditions, are some of the
+features that make it such a persistent weed.
+</para>
+
+<para>
+<indexterm><primary>Network Basic Input/Output System</primary><see>NetBIOS</see></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>TCP/IP</primary></indexterm>
+<indexterm><primary>Windows network clients</primary></indexterm>
+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>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>MS WINS</primary></indexterm>
+Samba provides the ability to implement a WINS (Windows Internetworking Name Server)
+and implements extensions to Microsoft's implementation of WINS. These extensions
+help Samba to effect stable WINS operations beyond the normal scope of MS WINS.
+</para>
+
+<para>
+<indexterm><primary>NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>NetBIOS disabled</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+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>
+<indexterm><primary>NetBIOS disabled</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+For those networks on which NetBIOS has been disabled (i.e., WINS is not required),
+the use of DNS is necessary for hostname resolution.
+</para>
+
+</sect1>
+
+<sect1>
+<title>What Is Browsing?</title>
+
+<para>
+<indexterm><primary>browsing</primary></indexterm>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+<indexterm><primary>shares</primary></indexterm>
+<indexterm><primary>printers available</primary></indexterm>
+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 machines on the network collate 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>
+<indexterm><primary>browse list management</primary></indexterm>
+<indexterm><primary>name resolution</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+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:
+</para>
+<itemizedlist>
+ <listitem><smbconfoption name="os level"/></listitem>
+ <listitem><smbconfoption name="lm announce"/></listitem>
+ <listitem><smbconfoption name="lm interval"/></listitem>
+ <listitem><smbconfoption name="preferred master"/>(*)</listitem>
+ <listitem><smbconfoption name="local master"/>(*)</listitem>
+ <listitem><smbconfoption name="domain master"/>(*)</listitem>
+ <listitem><smbconfoption name="browse list"/></listitem>
+ <listitem><smbconfoption name="enhanced browsing"/></listitem>
+</itemizedlist>
+
+<para>
+Name Resolution Method:
+</para>
+<itemizedlist>
+ <listitem><smbconfoption name="name resolve order"/>(*)</listitem>
+</itemizedlist>
+
+<para>
+WINS options:
+</para>
+<itemizedlist>
+ <listitem><smbconfoption name="dns proxy"/></listitem>
+ <listitem><smbconfoption name="wins proxy"/></listitem>
+ <listitem><smbconfoption name="wins server"/>(*)</listitem>
+ <listitem><smbconfoption name="wins support"/>(*)</listitem>
+ <listitem><smbconfoption name="wins hook"/></listitem>
+</itemizedlist>
+
+<para>
+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>
+
+<para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>WINS Server</primary></indexterm>
+<indexterm><primary>WINS Support</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>mutually exclusive options</primary></indexterm>
+For Samba, the WINS Server and WINS Support are mutually exclusive options. When <command>nmbd</command> is
+started it will fail to execute if both options are set in the &smb.conf; file. The <command>nmbd</command>
+understands that when it spawns an instance of itself to run as a WINS server that it has to use its own WINS
+server also.
+</para>
+
+</sect1>
+
+<sect1 id="netdiscuss">
+<title>Discussion</title>
+
+<para>
+<indexterm><primary>SMB-based messaging</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>phasing out 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.
+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 unicast 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 unicast UDP.
+Similarly, the <smbconfoption name="remote browse sync"/> parameter of &smb.conf; implements browse list
+collation using unicast 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 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>h-node</primary></indexterm>
+<indexterm><primary>hybrid</primary></indexterm>
+<indexterm><primary>enables NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>broadcast-based</primary></indexterm>
+<indexterm><primary>name resolution</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 (hybrid 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>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>cross-segment browsing</primary></indexterm>
+<indexterm><primary>network segment</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 multisegment 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. The delay is caused by the fact that this feature has
+not been of sufficient significance to inspire someone to pay a developer to complete it.
+</para>
+
+<para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>MS-WINS replication</primary></indexterm>
+<indexterm><primary>redundancy</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>NetBIOSless SMB over TCP/IP</primary></indexterm>
+<indexterm><primary>local names</primary></indexterm>
+<indexterm><primary>subnets</primary></indexterm>
+<indexterm><primary>multiple WINS servers</primary></indexterm>
+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). NetBIOS over TCP/IP is an ugly and difficult to manage
+protocol. Its replacement, NetBIOSless SMB over TCP/IP is not without its own manageability concerns. NetBIOS
+based networking is a life of compromise and trade-offs. WINS stores information that cannot be stored in
+DNS; consequently, DNS is a poor substitute for WINS given that when NetBIOS over TCP/IP is used, Windows
+clients are designed to use WINS.
+</para>
+
+<para>
+<indexterm><primary>broadcast messages</primary></indexterm>
+<indexterm><primary>repeated intervals</primary></indexterm>
+<indexterm><primary>across network segments</primary></indexterm>
+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>
+<indexterm><primary>Windows 200x/XP</primary></indexterm>
+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>
+
+<para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>name lookups</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+Given the nature of how the NetBIOS over TCP/IP protocol is implemented, only WINS is capable of resolving
+with any reliability name lookups for service-oriented names such as TEMPTATION&lt;1C&gt; &smbmdash; a NetBIOS
+name query that seeks to find network logon servers. DNS has no concept of service-oriented names such as
+this. In fact, the Microsoft ADS implementation specifically manages a whole range of extended
+service-oriented DNS entries. This type of facility is not implemented and is not supported for the NetBIOS
+over TCP/IP protocol namespace.
+</para>
+
+</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 hostname 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 hostname 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>
+<indexterm><primary>DDNS</primary></indexterm>
+<indexterm><primary>ipconfig</primary></indexterm>
+<indexterm><primary>Dynamic DNS</primary><see>DDNS</see></indexterm>
+Windows 200x/XP can register its hostname with a Dynamic DNS server (DDNS). It is possible to force register with a
+dynamic DNS server in Windows 200x/XP using <command>ipconfig /registerdns</command>.
+</para>
+
+<para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>severely impaired</primary></indexterm>
+With Active Directory, 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 network services consequently will be severely impaired.
+</para>
+
+<para>
+<indexterm><primary>raw SMB over TCP/IP</primary></indexterm>
+<indexterm><primary>No NetBIOS layer</primary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+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 to run Samba as a domain controller and at the same
+time <emphasis>not</emphasis> 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, however, if NetBIOS over TCP/IP is disabled, it is necessary to manually create
+appropriate DNS entries for the Samba DMS because they will not be automatically generated either by Samba, or
+by the ADS environment.
+</para>
+
+</sect2>
+
+<sect2 id="adsdnstech">
+<title>DNS and Active Directory</title>
+
+<para>
+<indexterm><primary>DNS</primary><secondary>Active Directory</secondary></indexterm>
+<indexterm><primary>DDNS</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>SRV records</primary></indexterm>
+<indexterm><primary>DNS</primary><secondary>SRV records</secondary></indexterm>
+Occasionally we hear from UNIX network administrators who want to use a UNIX-based DDNS server in place
+of the Microsoft DNS server. While this might be desirable to some, the MS Windows 200x DNS server is
+autoconfigured 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
+hostnames to locate essential network services. The following are some of the default service records that
+Active Directory requires:
+</para>
+
+<para>
+<indexterm><primary>DDNS</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>BIND9</primary></indexterm>
+The use of DDNS 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. Of course,
+when running ADS, it makes sense to use Microsoft's own DDNS server because of the natural affinity between ADS
+and MS DNS.
+</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 Microsoft Windows clients to locate the 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> include:
+ </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;lt;&gt;&gt; DiG 9.2.2 &lt;lt;&gt;&gt; @frodo -t any _ldap._tcp.dc._msdcs.quenya.org
+;; global options: printcmd
+;; Got answer:
+;; -&gt;&gt;HEADER&lt;&lt;- 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>
+<indexterm><primary>register NetBIOS names</primary></indexterm>
+<indexterm><primary>LMHOSTS</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>WINS server address</primary></indexterm>
+MS Windows machines register their NetBIOS names (i.e., the machine name for each service type in operation)
+on startup. 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,
+whether or not DNS for NetBIOS name resolution is enabled, and so on.
+</para>
+
+<para>
+<indexterm><primary>WINS server</primary></indexterm>
+<indexterm><primary>name lookups</primary></indexterm>
+<indexterm><primary>UDP</primary></indexterm>
+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>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>UDP unicast</primary></indexterm>
+<indexterm><primary>name resolution across routed networks</primary></indexterm>
+Where a WINS server is used, the MS Windows client will use UDP unicast to register with the WINS server. Such
+packets can be routed, and thus WINS allows name resolution to function across routed networks.
+</para>
+
+<para>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>local master browser</primary><see>LMB</see></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>LMHOSTS</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>browse list</primary></indexterm>
+<indexterm><primary>election</primary></indexterm>
+<indexterm><primary>election criteria</primary></indexterm>
+During the startup process, an election takes place to create a local master browser (LMB) if one does not
+already exist. On each NetBIOS network one machine will be elected to function as the domain master browser
+(DMB). This domain browsing has nothing to do with MS security Domain Control. Instead, the DMB serves the
+role of contacting each LMB (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 DMB.
+</para>
+
+<para>
+<indexterm><primary>WINS server</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>NetBIOS name type</primary></indexterm>
+<indexterm><primary>n security context</primary></indexterm>
+<indexterm><primary>network segment</primary></indexterm>
+<indexterm><primary>authoritive</primary></indexterm>
+<indexterm><primary>browse list maintainers</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+Where a WINS server is used, the DMB registers its IP address with the WINS server using the name of the
+domain and the NetBIOS name type 1B (e.g., DOMAIN&lt;1B&gt;). All LMBs register their IP addresses with the WINS
+server, also with the name of the domain and the NetBIOS name type of 1D. The 1B name is unique to one
+server within the domain security context, and only one 1D name is registered for each network segment.
+Machines that have registered the 1D name will be authoritive browse list maintainers for the network segment
+they are on. The DMB is responsible for synchronizing the browse lists it obtains from the LMBs.
+</para>
+
+<para>
+<indexterm><primary>name resolution</primary></indexterm>
+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 or addresses.
+</para>
+
+<para>
+<indexterm><primary>browsing intrinsics</primary></indexterm>
+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>
+<indexterm><primary>forced synchronization</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>bridges networks</primary></indexterm>
+<indexterm><primary>cross-subnet browsing</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>/etc/hosts</primary></indexterm>
+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
+LMB 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>
+<indexterm><primary>cross-subnet browsing</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>isolated workgroup</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+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 DMB (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 DMB is to collate the browse lists
+from LMB on all the subnets that have a machine participating in the workgroup. Without one machine configured
+as a DMB, each subnet would be an isolated workgroup unable to see any machines on another subnet. It is the
+presence of a DMB that makes cross-subnet browsing possible for a workgroup.
+</para>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+In a workgroup environment the DMB must be a Samba server, and there must only be one DMB per workgroup name.
+To set up a Samba server as a DMB, 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>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+The DMB should preferably be the LMB 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">Domain Master Browser smb.conf</link>
+</para>
+
+<example id="dmbexample">
+<title>Domain Master Browser smb.conf</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>WINS server</primary></indexterm>
+The DMB may be the same machine as the WINS server, if necessary.
+</para>
+
+<para>
+<indexterm><primary>subnets</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>rebooted</primary></indexterm>
+Next, you should ensure that each of the subnets contains a machine that can act as an LMB 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 them). To make a Samba server an LMB,
+set the following options in the <smbconfsection name="[global]"/> section of the &smb.conf; file as shown in
+<link linkend="lmbexample">Local master browser smb.conf</link>
+</para>
+
+<example id="lmbexample">
+<title>Local master browser smb.conf</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>LMB</primary></indexterm>
+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 LMB.
+</para>
+
+<para>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>browser election</primary></indexterm>
+The <smbconfoption name="local master"/> parameter allows Samba to act as a
+LMB. 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>
+<indexterm><primary>disable LMB</primary></indexterm>
+If you have an NT machine on the subnet that you wish to be the LMB, you can disable Samba from
+becoming an LMB by setting the following options in the <smbconfsection name="[global]"/> section of the
+&smb.conf; file as shown in <link linkend="nombexample">smb.conf for Not Being a Master Browser</link>.
+</para>
+
+<para>
+<example id="nombexample">
+<title>smb.conf for Not Being a Master Browser</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Domain Browsing Configuration</title>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>registers</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+If you are adding Samba servers to a Windows NT domain, then you must not set up a Samba server as a DMB. By
+default, a Windows NT PDC for a domain is also the DMB for that domain. Network browsing may break if a Samba
+server other than the PDC registers the DMB NetBIOS name (<replaceable>DOMAIN</replaceable>&lt;1B&gt;) with
+WINS.
+</para>
+
+<para>
+<indexterm><primary>Local Master Browser</primary></indexterm>
+For subnets other than the one containing the Windows NT PDC, you may set up Samba servers as LMBs 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">Local Master Browser
+smb.conf</link>
+</para>
+
+<example id="remsmb">
+<title>Local Master Browser smb.conf</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>election</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+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 LMBs if they are running. For more details on this, refer to <link
+linkend="browse-force-master">Forcing Samba to Be the Master</link>.
+</para>
+
+<para>
+<indexterm><primary>domain members</primary></indexterm>
+<indexterm><primary>browser elections</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+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 an LMB by
+setting the following options in the <smbconfsection name="[global]"/> section of the &smb.conf; file as shown
+in <link linkend="xremmb">&smb.conf; for Not Being a master browser</link>
+</para>
+
+<para>
+<example 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>
+</example>
+</para>
+
+</sect2>
+
+<sect2 id="browse-force-master">
+<title>Forcing Samba to Be the Master</title>
+
+<para>
+<indexterm><primary>master browser</primary></indexterm>
+<indexterm><primary>election process</primary></indexterm>
+<indexterm><primary>broadcasts</primary></indexterm>
+<indexterm><primary>election packet</primary></indexterm>
+<indexterm><primary>bias</primary></indexterm>
+<indexterm><primary>election</primary></indexterm>
+<indexterm><primary>precedence</primary></indexterm>
+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 over 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>
+<indexterm><primary>force an election</primary></indexterm>
+<indexterm><primary>potential master browsers</primary></indexterm>
+<indexterm><primary>local subnet</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+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, because 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 LMB.
+</para>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>LAN</primary></indexterm>
+<indexterm><primary>WAN</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>broadcast isolated subnet</primary></indexterm>
+If you want Samba to be a <emphasis>DMB</emphasis>, then it is recommended that you also set <smbconfoption
+name="preferred master"/> to <constant>yes</constant>, because Samba will not become a DMB for the whole of
+your LAN or WAN if it is not also a LMB on its own broadcast isolated subnet.
+</para>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>automatic redundancy</primary></indexterm>
+<indexterm><primary>UDP</primary></indexterm>
+<indexterm><primary>network bandwidth</primary></indexterm>
+<indexterm><primary>browser elections</primary></indexterm>
+It is possible to configure two Samba servers to attempt to become the DMB for a domain. The first server that
+comes up will be the DMB. All other Samba servers will attempt to become the DMB every 5 minutes. They will
+find that another Samba server is already the DMB and will fail. This provides automatic redundancy should the
+current DMB fail. The network bandwidth overhead of browser elections is relatively small, requiring
+approximately four UDP packets per machine per election. The maximum size of a UDP packet is 576 bytes.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Making Samba the Domain Master</title>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>collating</primary></indexterm>
+<indexterm><primary>browse lists</primary></indexterm>
+<indexterm><primary>browsing</primary></indexterm>
+The domain master browser 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 browser by setting <smbconfoption name="domain
+master">yes</smbconfoption> in &smb.conf;. By default it will not be a domain master browser.
+</para>
+
+<para>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>network browsing problems</primary></indexterm>
+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 12 minutes) from LMBs on other subnets and then contact them to synchronize browse lists.
+</para>
+
+<para>
+<indexterm><primary>win election</primary></indexterm>
+<indexterm><primary>force election</primary></indexterm>
+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>
+<indexterm><primary>WINS server</primary></indexterm>
+<indexterm><primary>resolve NetBIOS names</primary></indexterm>
+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>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+ LMBs will be unable to find a DMB because they will be looking only on the local subnet.
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+<indexterm><primary>domain-wide browse list</primary></indexterm>
+ 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>
+<indexterm><primary>WINS</primary></indexterm>
+If, however, both Samba and your clients are using a WINS server, then:
+</para>
+
+<orderedlist>
+<listitem>
+ <para>
+ LMBs will contact the WINS server and, as long as Samba has registered that it is a DMB with the WINS
+ server, the LMB will receive Samba's IP address as its DMB.
+ </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>
+<indexterm><primary>zero-based broadcast</primary></indexterm>
+If your network uses a zero-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>
+<indexterm><primary>multiple network interfaces</primary></indexterm>
+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. For example, the
+machine you are working with has 4 network interfaces; <literal>eth0</literal>, <literal>eth1</literal>,
+<literal>eth2</literal>, <literal>eth3</literal> and only interfaces <literal>eth1</literal> and
+<literal>eth4</literal> should be used by Samba. In this case, the following &smb.conf; file entries would
+permit that intent:
+<smbconfblock>
+<smbconfoption name="interfaces">eth1, eth4</smbconfoption>
+<smbconfoption name="bind interfaces only">Yes</smbconfoption>
+</smbconfblock>
+<indexterm><primary>port 135</primary></indexterm>
+<indexterm><primary>port 137</primary></indexterm>
+<indexterm><primary>port 138</primary></indexterm>
+<indexterm><primary>port 139</primary></indexterm>
+<indexterm><primary>port 445</primary></indexterm>
+<indexterm><primary>UDP</primary></indexterm>
+<indexterm><primary>TCP</primary></indexterm>
+The <smbconfoption name="bind interfaces only">Yes</smbconfoption> is necessary to exclude TCP/IP session
+services (ports 135, 139, and 445) over the interfaces that are not specified. Please be aware that
+<command>nmbd</command> will listen for incoming UDP port 137 packets on the unlisted interfaces, but it will
+not answer them. It will, however, send its broadcast packets over the unlisted interfaces. Total isolation of
+ethernet interface requires the use of a firewall to block ports 137 and 138 (UDP), and ports 135, 139, and
+445 (TCP) on all network interfaces that must not be able to access the Samba server.
+</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">192.168.12.23 [172.16.21.255] ...</smbconfoption>
+</smbconfblock>
+<emphasis>or</emphasis>
+<smbconfblock>
+<smbconfoption name="remote announce">192.168.12.23/MIDEARTH [172.16.21.255/ELVINDORF] ...</smbconfoption>
+</smbconfblock>
+
+where:
+<variablelist>
+ <varlistentry><term><replaceable>192.168.12.23</replaceable> and <replaceable>172.16.21.255</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 IP address or the broadcast address of the remote network.
+ That is, the LMB is at 192.168.1.23, or the address could be given as 172.16.21.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>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>synchronize</primary></indexterm>
+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>192.168.10.40</replaceable></smbconfoption>
+</smbconfblock>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>remote segment</primary></indexterm>
+where <replaceable>192.168.10.40</replaceable> is either the IP address of the
+remote LMB or the network broadcast address of the remote segment.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>WINS: The Windows Internetworking Name Server</title>
+
+<para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>name_type</primary></indexterm>
+<indexterm><primary>LanManager-compatible</primary></indexterm>
+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>
+<indexterm><primary>NetBIOS name length</primary></indexterm>
+<indexterm><primary>name_type</primary></indexterm>
+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>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>registered</primary></indexterm>
+<indexterm><primary>NetLogon service</primary></indexterm>
+<indexterm><primary>lmhosts</primary></indexterm>
+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>
+<indexterm><primary>synchronization</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>browse list</primary></indexterm>
+WINS also forces browse list synchronization by all LMBs. LMBs must synchronize their browse list with the
+DMB, and WINS helps the LMB to identify its DMB. By definition this will work only within a single workgroup.
+Note that the DMB has nothing to do with what is referred to as an MS Windows NT domain. The latter is a
+reference to a security environment, while the DMB refers to the master controller for browse list information
+only.
+</para>
+
+<para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>TCP/IP protocol stack</primary></indexterm>
+<indexterm><primary>WINS servers</primary></indexterm>
+<indexterm><primary>name-to-address</primary></indexterm>
+WINS will work correctly only if every client TCP/IP protocol stack
+is configured to use the WINS servers. Any client that is not
+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">10.0.0.18</smbconfoption> to your &smb.conf; file <smbconfsection name="[global]"/> section.
+</para>
+
+<important><para>
+Never use <smbconfoption name="wins support">yes</smbconfoption> together with <smbconfoption name="wins
+server">10.0.0.18</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>
+<indexterm><primary>WINS</primary></indexterm>
+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>
+<indexterm><primary>Samba 1.9.17</primary></indexterm>
+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>
+<indexterm><primary>only one WINS server</primary></indexterm>
+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 on a network.
+</para>
+
+<para>
+<indexterm><primary>replication</primary><secondary>WINS</secondary></indexterm>
+<indexterm><primary>Windows NT/200x</primary></indexterm>
+<indexterm><primary>WINS service</primary></indexterm>
+<indexterm><primary>replication protocols</primary></indexterm>
+<indexterm><primary>WINS server</primary></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. Because Microsoft refuses to document the replication
+protocols, Samba cannot currently participate in these replications. It is possible that a Samba-to-Samba WINS
+replication protocol may be defined in the future, 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>
+<indexterm><primary>WINS server</primary></indexterm>
+<indexterm><primary>Primary WINS Server</primary></indexterm>
+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:
+<smbconfblock>
+<smbconfoption name="wins server">&lt;name or IP address&gt;</smbconfoption>
+</smbconfblock>
+where &lt;name or IP address&gt; 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">&lt;name&gt;</smbconfoption> option then
+<command>nmbd</command> will fail to start.
+</para>
+
+<para>
+<indexterm><primary>cross-subnet browsing</primary></indexterm>
+<indexterm><primary>Windows 9x/Me</primary></indexterm>
+<indexterm><primary>Windows NT/200x</primary></indexterm>
+<indexterm><primary>not part of domain</primary></indexterm>
+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>
+<indexterm><primary>WINS replication</primary></indexterm>
+Samba-3 does not support native WINS replication. There was an approach to implement it, called
+<filename>wrepld</filename>, but it was never ready for action and the development is now discontinued.
+</para>
+<para>
+Meanwhile, there is a project named <filename>samba4WINS</filename>, which makes it possible to
+run the Samba-4 WINS server parallel to Samba-3 since version 3.0.21. More information about
+<filename>samba4WINS</filename> are available at http://ftp.sernet.de/pub/samba4WINS.
+
+</para>
+
+</sect2>
+<sect2>
+<title>Static WINS Entries</title>
+
+<para>
+<indexterm><primary>static WINS entries</primary></indexterm>
+<indexterm><primary>wins.dat</primary></indexterm>
+<indexterm><primary>/usr/local/samba/var/locks</primary></indexterm>
+<indexterm><primary>/var/run/samba</primary></indexterm>
+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>
+<indexterm><primary>TTL</primary></indexterm>
+<indexterm><primary>time-to-live</primary><see>TTL</see></indexterm>
+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>
+
+<note><para>
+A change that has been made to the <filename>wins.dat</filename> will not take effect until &nmbd; has been
+restarted. It should be noted that since the <filename>wins.dat</filename> file changes dynamically, &nmbd;
+should be stopped before editting this file. Do not forget to restart &nmbd; when this file has been editted.
+</para></note>
+
+<para>
+A typical dynamic entry looks like this:
+<programlisting>
+"MADMAN#03" 1155298378 192.168.1.2 66R
+</programlisting>
+To make a NetBIOS name static (permanent), simply set the TTL to 0, like this:
+<programlisting>
+"MADMAN#03" 0 192.168.1.2 66R
+</programlisting>
+</para>
+
+<para>
+<indexterm><primary>NetBIOS flags</primary></indexterm>
+<indexterm><primary>Broadcast node</primary></indexterm>
+<indexterm><primary>Peer node</primary></indexterm>
+<indexterm><primary>Meta node</primary></indexterm>
+<indexterm><primary>Hybrid node</primary></indexterm>
+<indexterm><primary>Permanent name</primary></indexterm>
+<indexterm><primary>nameserv.h</primary></indexterm>
+The NetBIOS flags may be interpreted as additive hexadecimal values: 00 - Broadcast node registration, 20 -
+Peer node registration, 40 - Meta node registration, 60 - Hybrid node registration, 02 - Permanent name, 04 -
+Active name, 80 - Group name. The 'R' indicates this is a registration record. Thus 66R means: Hybrid node
+active and permanent NetBIOS name. These values may be found in the <filename>nameserv.h</filename> header
+file from the Samba source code repository. These are the values for the NB flags.
+</para>
+
+<para>
+<indexterm><primary>WINS replication</primary></indexterm>
+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 because they are stumbling points
+for many new network administrators.
+</para>
+
+<sect2>
+<title>Windows Networking Protocols</title>
+
+<para>
+<indexterm><primary>browsing problems</primary></indexterm>
+<indexterm><primary>more than one protocol</primary></indexterm>
+A common cause of browsing problems results from the installation of 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>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+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>
+<indexterm><primary>NetBIOS network interface</primary></indexterm>
+<indexterm><primary>TCP/IP</primary></indexterm>
+<indexterm><primary>IPX</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>Windows 9x/Me</primary></indexterm>
+<indexterm><primary>TCP/IP-only</primary></indexterm>
+The election process is <emphasis>fought out, so to speak</emphasis> 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 because Windows 9x/Me will insist it knows who the LMB is. Samba will then
+cease to function as an LMB, and browse list operation on all TCP/IP-only machines will therefore fail.
+</para>
+
+<para>
+<indexterm><primary>Windows 9x/Me</primary></indexterm>
+<indexterm><primary>extended protocol</primary></indexterm>
+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>
+<indexterm><primary>NetBIOS names</primary></indexterm>
+<indexterm><primary>name_type</primary></indexterm>
+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 NetBIOS name_type information.</para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>restrict DNS</primary></indexterm>
+<indexterm><primary>name resolve order</primary></indexterm>
+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>
+<indexterm><primary>gethostbyname() function call</primary></indexterm>
+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>
+<indexterm><primary>SMB</primary></indexterm>
+SMB networking provides a mechanism by which clients can access a list
+of machines in a network 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. It therefore 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>
+<indexterm><primary>NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>DNS/LDAP/ADS</primary></indexterm>
+<indexterm><primary>name resolution</primary></indexterm>
+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>
+<indexterm><primary>NetBIOS</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+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>
+<indexterm><primary>browsing</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>domain logons</primary></indexterm>
+<indexterm><primary>scripts</primary></indexterm>
+Samba facilitates browsing. The browsing is supported by &nmbd;
+and is also controlled by options in the &smb.conf; file.
+Samba can act as an LMB for a workgroup, and the ability
+to support domain logons and scripts is now available.
+</para>
+
+<para>
+<indexterm><primary>DMB for a workgroup</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+Samba can also act as a DMB for a workgroup. This
+means that it will collate lists from LMBs 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>
+<indexterm><primary>domain master</primary></indexterm>
+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
+DMB per workgroup, regardless of whether it is NT, Samba,
+or any other type of domain master that is providing this service.
+</para>
+
+<note><para>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>WINS server</primary></indexterm>
+<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 WAN, 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>
+<indexterm><primary>nmbd</primary></indexterm>
+To get browsing to work, you need to run <command>nmbd</command> as usual, but must
+use the <smbconfoption name="workgroup"/> option in &smb.conf;
+to control what workgroup Samba becomes a part of.
+</para>
+
+<para>
+<indexterm><primary>browsing another subnet</primary></indexterm>
+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 used only 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>
+<indexterm><primary>log.nmbd</primary></indexterm>
+<indexterm><primary>browse.dat</primary></indexterm>
+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>
+<indexterm><primary>\\SERVER</primary></indexterm>
+<indexterm><primary>filemanager</primary></indexterm>
+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>
+<indexterm><primary>IPC$</primary></indexterm>
+<indexterm><primary>guest account</primary></indexterm>
+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 so you must have a valid guest account.
+</para>
+
+<note><para>
+<indexterm><primary>IPC$</primary></indexterm>
+<indexterm><primary>Windows Explorer</primary></indexterm>
+<indexterm><primary>browse resources</primary></indexterm>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+<indexterm><primary>My Network Places</primary></indexterm>
+The <literal>IPC$</literal> share is used by all SMB/CIFS clients to obtain the list of resources that is
+available on the server. This is the source of the list of shares and printers when browsing an SMB/CIFS
+server (also Windows machines) using the Windows Explorer to browse resources through the Windows Network
+Neighborhood (also called My Network Places) through to a Windows server. At this point, the client has opened
+a connection to the <literal>\\server\IPC4</literal> resource. Clicking on a share will then open up a
+connection to the <literal>\\server\share</literal>.
+</para></note>
+
+<para>
+<indexterm><primary>guest account</primary></indexterm>
+<indexterm><primary>anonymous access</primary></indexterm>
+<indexterm><primary>IPC$</primary></indexterm>
+<indexterm><primary>browse server resources</primary></indexterm>
+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>
+<indexterm><primary>broadcast address</primary></indexterm>
+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>
+<indexterm><primary>browse across subnet</primary></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>
+<indexterm><primary>browse lists</primary></indexterm>
+<indexterm><primary>broadcast traffic</primary></indexterm>
+<indexterm><primary>UDP</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>remote announce</primary></indexterm>
+<indexterm><primary>remote browse sync</primary></indexterm>
+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. The Samba hacks, <parameter>remote browse sync</parameter>, and <parameter>remote
+announce</parameter> are designed to get around the natural limitations that prevent UDP broadcast
+propagation. The hacks are not a universal solution and they should not be used in place of WINS, they are
+considered last resort methods.
+</para>
+
+<para>
+<indexterm><primary>DHCP</primary></indexterm>
+<indexterm><primary>browsing across subnets</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>Network settings</primary></indexterm>
+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>
+
+<para>
+<indexterm><primary>NetBIOS over TCP/IP</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+It is possible to operate Samba-3 without NetBIOS over TCP/IP. If you do this, be warned that if used outside
+of MS ADS, this will forgo network browsing support. ADS permits network browsing support through DNS,
+providing appropriate DNS records are inserted for all Samba servers.
+</para>
+
+<sect3>
+<title>Behavior of Cross-Subnet Browsing</title>
+
+<para>
+<indexterm><primary>cross-subnet browsing</primary></indexterm>
+<indexterm><primary>complicated</primary></indexterm>
+Cross-subnet browsing is a complicated dance, containing multiple moving parts. It has taken Microsoft several
+years to get the code that correctly achieves this, 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>
+
+<figure id="browsing1">
+ <title>Cross-Subnet Browsing Example.</title>
+ <imagefile scale="40">browsing1</imagefile>
+</figure>
+
+<para>
+<indexterm><primary>broadcasts</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+This consists of three 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, and 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 the DMB (i.e., it will collate the browse lists for the workgroup). Machine N2_D is
+configured as a WINS server, and all the other machines are configured to register their NetBIOS names with
+it.
+</para>
+
+<para>
+<indexterm><primary>master browsers</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+As these machines are booted up, elections for master browsers
+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 LMBs for
+their particular subnet. N1_C has an advantage in winning as the
+LMB on subnet 1 because it is set up as DMB.
+</para>
+
+<para>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>browse list</primary></indexterm>
+On each of the three networks, machines that are configured to offer sharing services will broadcast that they
+are offering these services. The LMB 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>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>authoritative</primary></indexterm>
+<indexterm><primary>verifiable</primary></indexterm>
+<indexterm><primary>trusted</primary></indexterm>
+<indexterm><primary>non-authoritative</primary></indexterm>
+For each network, the LMB on that network is
+considered <emphasis>authoritative</emphasis> for all the names it receives via
+local broadcast. This is because a machine seen by the LMB
+via a local broadcast must be on the same network as the
+Local Master Browser and thus is a <emphasis>trusted</emphasis>
+and <emphasis>verifiable</emphasis> resource. Machines on other networks that
+the LMBs learn about when collating their
+browse lists have not been directly seen. These records are
+called <emphasis>non-authoritative.</emphasis>
+</para>
+
+<para>
+<indexterm><primary>network neighborhood</primary></indexterm>
+At this point the browse lists appear as shown in <link linkend="browsubnet">Browse Subnet Example 1</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>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>synchronize</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+Now examine subnet 2 in <link linkend="brsbex">Browse Subnet Example 2</link>. As soon as N2_B has become the
+LMB, it looks for a DMB 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&lt;1B&gt;. This name was registered by
+the DMB (N1_C) with the WINS server as soon as it was started.
+</para>
+
+<para>
+<indexterm><primary>MasterAnnouncement</primary></indexterm>
+<indexterm><primary>NetServerEnum2</primary></indexterm>
+<indexterm><primary>synchronization</primary></indexterm>
+<indexterm><primary>browse lists</primary></indexterm>
+Once N2_B knows the address of the DMB, it tells it that is the LMB 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 DMB to send it all the server names it knows
+about. Once the DMB 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 like those in <link linkend="brsbex">Browse Subnet Example 2</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>
+<indexterm><primary>non-authoritative</primary></indexterm>
+Servers with an (*) after them are non-authoritative names.
+</para>
+
+<para>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+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 see only the servers on their own subnet.
+</para>
+
+<para>
+<indexterm><primary>DMB</primary></indexterm>
+The same sequence of events that occurred for N2_B now occurs for the LMB on subnet 3 (N3_D). When it
+synchronizes browse lists with the DMB (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">Browse Subnet Example 3</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 see only the servers on subnets 1 and 2, but not 3.
+</para>
+
+<para>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>browse lists</primary></indexterm>
+Finally, the LMB for subnet 2 (N2_B) will sync again
+with the DMB (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">Browse Subnet Example 4</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 DMB and LMBs
+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>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+ 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>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>NetBIOS name resolution</primary></indexterm>
+<indexterm><primary>DNS server</primary></indexterm>
+ 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 effect is similar to that of
+ losing access to a DNS server.
+ </para>
+</listitem>
+</orderedlist>
+</sect3>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+<indexterm><primary>browsing problems</primary></indexterm>
+<indexterm><primary>name resolution</primary></indexterm>
+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>Flushing the Samba NetBIOS Name Cache</title>
+
+<para>
+How Can One Flush the Samba NetBIOS Name Cache without Restarting Samba?
+</para>
+
+<para>
+<indexterm><primary>flush name cache</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>NetBIOS name cache</primary></indexterm>
+<indexterm><primary>rogue machine</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 reappear
+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 must 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 Cannot 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 LMB. Configure &nmbd;
+ or any other machine to serve as LMB.</para></listitem>
+ <listitem><para>You cannot log onto the machine that is the LMB.
+ Can you log on to it as a guest user? </para></listitem>
+ <listitem><para>There is no IP connectivity to the LMB.
+ 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 is 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.
+</quote>
+</para>
+
+<para><quote>
+<indexterm><primary>cmd</primary></indexterm>
+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>
+<indexterm><primary>defective hardware</primary></indexterm>
+<indexterm><primary>Bad networking hardware</primary></indexterm>
+<indexterm><primary>data corruption</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>
+<indexterm><primary>network browsing problems</primary></indexterm>
+ 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 because it is a simple solution &smbmdash; if it works.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Inconsistent WINS Configuration</term>
+ <listitem><para>
+<indexterm><primary>WINS Configuration</primary></indexterm>
+<indexterm><primary>WINS server</primary></indexterm>
+ 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. Alternatively,
+ this will happen if 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, nor should it be configured to use one.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Incorrect DNS Configuration</term>
+ <listitem><para>
+<indexterm><primary>DNS Configuration</primary></indexterm>
+<indexterm><primary>NetBIOS over TCP/IP disabled</primary></indexterm>
+ If use of NetBIOS over TCP/IP is disabled, Active Directory is in use and the DNS server
+ has been incorrectly configured. For further information refer to
+ <link linkend="adsdnstech">DNS and Active Directory</link>.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2>
+<title>Invalid Cached Share References Affects Network Browsing</title>
+<para>
+<indexterm><primary>cached references</primary></indexterm>
+<indexterm><primary>stale network links</primary></indexterm>
+Cached references on your MS Windows client (workstation or server) to shares or servers that no longer exist
+can cause MS Windows Explorer to appear unresponsive as it tries to connect to these shares. After a delay
+(can take a long time) it times out and browsing will appear to be mostly normal again.
+</para>
+
+<para>
+To eliminate the problem the stale cached references should be removed. This does not happen automatically and
+requires manual intervention. This is a design feature of MS Windows and not anything that Samba can change.
+To remove the stale shortcuts found in <emphasis>My Network Places</emphasis> which refer to what are now
+invalid shares or servers it is necessary to edit the Windows Registry under
+<literal>HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\</literal>. Edit the entry
+<literal>MountPoints2</literal> (on Windows XP and later, or <literal>MountPoints</literal> on Windows 2000
+and earlier). Remove all keys named <literal>\\server\share</literal> (where 'server' and 'share' refer to a
+non-existent server or share).
+</para>
+
+<note><para>
+Removal of stale network links needs to be done on a per-user basis. Alternately, you can delete the
+shortcuts from the MS Windows Explorer in <literal>My Network Places</literal> just by right-clicking them and
+selecting <emphasis>Delete.</emphasis>
+</para></note>
+
+<para>
+<indexterm><primary>slow network browsing</primary></indexterm>
+Samba users have reported that these stale references negatively affect network browsing with Windows, Samba,
+and Novell servers. It is suspected to be a universal problem not directly related to the Samba
+server. Samba users may experience this more often due to Samba being somewhat viewed as an experimenter's
+toolkit. This results from the fact that a user might go through several reconfigurations and incarnations of
+their Samba server, by different names, with different shares, increasing the chances for having stale
+(invalid) cached share references. Windows clients do not expire these references thus necessitating manual
+removal.
+</para>
+
+<para>
+It is common for <emphasis>Open</emphasis> dialog boxes (for example; in Word and Excel) to respond very
+slowly, as they attempt to locate all of the cached references, even if they are not in the current directory
+being accessed.
+</para>
+</sect2>
+</sect1>
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Other-Clients.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Other-Clients.xml
new file mode 100644
index 0000000000..94c3fcc81a
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Other-Clients.xml
@@ -0,0 +1,351 @@
+<?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>
+<indexterm><primary>DAVE</primary></indexterm>
+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 5.1. Please
+refer to Thursby's Web site for more information regarding this product.
+</para>
+
+<para>
+<indexterm><primary>Netatalk</primary></indexterm>
+<indexterm><primary>CAP</primary></indexterm>
+Alternatives include 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 IBM OS/2 Warp Web page</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 its TCP/IP 32-bit VxD drivers. The latest release can be
+found 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 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>
+<indexterm><primary>admincfg.exe</primary></indexterm>
+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, 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 id="speedimpr">
+<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 changes documented in
+<link linkend="speedimpr">Speed Improvement</link> will affect you once these
+updates have been installed.
+</para>
+
+<para>
+There are more updates than the ones mentioned here. Refer 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 that 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>
+
+<example id="minimalprofile">
+<title>Minimal Profile Share</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<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,
+<errorname>access denied</errorname> message.
+</para>
+
+<para>
+When the <smbconfoption name="nt acl support"/> parameter is disabled, 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-xml/Samba3-HOWTO/TOSHARG-PAM.xml b/docs-xml/Samba3-HOWTO/TOSHARG-PAM.xml
new file mode 100644
index 0000000000..072e88a5ba
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-PAM.xml
@@ -0,0 +1,1013 @@
+<?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>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Winbind-based authentication</primary></indexterm>
+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>
+<indexterm><primary>PAM management</primary></indexterm>
+<indexterm><primary>pam_smbpass.so</primary></indexterm>
+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>
+<indexterm><primary>Sun Solaris</primary></indexterm>
+<indexterm><primary>xxxxBSD</primary></indexterm>
+<indexterm><primary>Linux</primary></indexterm>
+<indexterm><primary>Pluggable Authentication Modules</primary><see>PAM</see></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>login</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+<indexterm><primary>chown</primary></indexterm>
+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>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>/etc/pam.d</primary></indexterm>
+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>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>dynamically loadable library modules</primary></indexterm>
+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>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>PAM modules</primary></indexterm>
+<indexterm><primary>pam_unix.so</primary></indexterm>
+<indexterm><primary>pam_unix2.so</primary></indexterm>
+<indexterm><primary>pam_pwdb.so</primary></indexterm>
+<indexterm><primary>pam_userdb.so</primary></indexterm>
+ 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>
+<indexterm><primary>pam_krb5.so</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>Heimdal</primary></indexterm>
+<indexterm><primary>MIT Kerberos</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+ 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>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>pam_ldap.so</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>Sun ONE iDentity server</primary></indexterm>
+<indexterm><primary>Novell eDirectory server</primary></indexterm>
+<indexterm><primary>Microsoft Active Directory</primary></indexterm>
+ 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, and Microsoft Active Directory.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term>NetWare Bindery</term><listitem>
+ <para>
+<indexterm><primary>NetWare Bindery</primary></indexterm>
+<indexterm><primary>pam_ncp_auth.so</primary></indexterm>
+<indexterm><primary>bindery-enabled</primary></indexterm>
+<indexterm><primary>NetWare Core Protocol-based server</primary></indexterm>
+ 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>
+<indexterm><primary>SMB Password</primary></indexterm>
+<indexterm><primary>pam_smbpass.so</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+ This module, called <filename>pam_smbpass.so</filename>, allows user authentication of
+ the passdb backend that is configured in the Samba &smb.conf; file.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term>SMB Server</term><listitem>
+ <para>
+<indexterm><primary>SMB Server</primary></indexterm>
+<indexterm><primary>pam_smb_auth.so</primary></indexterm>
+ 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>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+ 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>
+<indexterm><primary>Remote Access Dial-In User Service</primary><see>RADIUS</see></indexterm>
+ There is a PAM RADIUS (Remote Access Dial-In User Service) authentication
+ module. In most cases, administrators 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>
+<indexterm><primary>pam_smbpasswd.so</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+Of the modules listed, Samba provides the <filename>pam_smbpasswd.so</filename> and the
+<filename>pam_winbind.so</filename> modules alone.
+</para>
+
+<para>
+<indexterm><primary>wide-area network bandwidth</primary></indexterm>
+<indexterm><primary>efficient authentication</primary></indexterm>
+<indexterm><primary>PAM-capable</primary></indexterm>
+<indexterm><primary>centrally managed</primary></indexterm>
+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>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>privilege-granting applications</primary></indexterm>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary>/etc/pam.d/</primary></indexterm>
+PAM is designed to provide system administrators 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>
+<indexterm><primary>PAM-specific tokens</primary></indexterm>
+<indexterm><primary>case sensitivity</primary></indexterm>
+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>
+<indexterm><primary>PAM authentication module</primary></indexterm>
+<indexterm><primary>/lib/security</primary></indexterm>
+If the PAM authentication module (loadable link library file) is located in the
+default location, then it is not necessary to specify the path. In the case of
+Linux, the default location is <filename>/lib/security</filename>. If the module
+is located outside the default, then the path must be specified as:
+<programlisting>
+auth required /other_path/pam_strange_module.so
+</programlisting>
+</para>
+
+<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>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+A general configuration line of the <filename>/etc/pam.conf</filename> file has the following form:
+<programlisting>
+service-name module-type control-flag module-path args
+</programlisting>
+</para>
+
+<para>
+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 tokens, we describe this method.
+</para>
+
+<variablelist>
+ <varlistentry><term>service-name</term><listitem>
+ <para>
+<indexterm><primary>ftpd</primary></indexterm>
+<indexterm><primary>rlogind</primary></indexterm>
+<indexterm><primary>su</primary></indexterm>
+ The name of the service associated with this entry. Frequently, the service-name is the conventional
+ name of the given application &smbmdash; 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 uppercase 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>
+<indexterm><primary>auth</primary></indexterm>
+<indexterm><primary>/etc/groups</primary></indexterm>
+ <parameter>auth:</parameter> This module type provides two aspects of authenticating the user.
+ It establishes that the user is who he or she claims to be by instructing the application
+ to prompt the user for a password or other means of identification. Second, the module can
+ grant group membership (independently of the <filename>/etc/groups</filename> file)
+ or other privileges through its credential-granting properties.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>account</primary></indexterm>
+<indexterm><primary>non-authentication-based account management</primary></indexterm>
+ <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 user
+ login. For example, the <quote>root</quote> login may be permitted only on the console.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>session</primary></indexterm>
+ <parameter>session:</parameter> Primarily, this module is associated with doing things that need
+ to be done for the user before and after he or she can be given service. Such things include logging
+ information concerning the opening and closing of some data exchange with a user, mounting
+ directories, and so on.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>password</primary></indexterm>
+ <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> 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>
+<indexterm><primary>required</primary></indexterm>
+<indexterm><primary>requisite</primary></indexterm>
+<indexterm><primary>sufficient</primary></indexterm>
+<indexterm><primary>optional</primary></indexterm>
+ 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</parameter>, <parameter>requisite</parameter>,
+ <parameter>sufficient</parameter>, and <parameter>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, except that if 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</parameter>; <parameter>ok</parameter>; <parameter>done</parameter>;
+ <parameter>bad</parameter>; <parameter>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 module's
+ 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</parameter>; <parameter>requisite</parameter>;
+ <parameter>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 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 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 fail over into an alternative authentication
+ mode for legacy applications.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>module-path</term><listitem>
+ <para>
+ The pathname 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 previous notes).
+ </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>
+ <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>
+</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 containing the Microsoft MD4 encrypted password
+hashes. This database is stored either in
+<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>
+ <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></para>
+
+<para>
+The following is the PAM configuration file for a particular
+Linux system. The default condition uses <filename>pam_pwdb.so</filename>.
+</para>
+
+<para>
+ <programlisting>
+#%PAM-1.0
+# The PAM configuration file for the <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></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>
+ <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>
+</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 has 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>
+
+<blockquote>
+<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>
+</blockquote>
+
+</sect2>
+
+<sect2>
+<title>Remote CIFS Authentication Using <filename>winbindd.so</filename></title>
+
+<para>
+All operating systems depend on the provision of user 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 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) insofar 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 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>dDo 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 the 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>
+The following is 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. It is useful when an expired password might be changed by an
+application (such as <command>ssh</command>).
+</para>
+
+<para>
+ <programlisting>
+#%PAM-1.0
+# password-sync
+#
+auth requisite pam_nologin.so
+auth required pam_unix.so
+account required pam_unix.so
+password requisite pam_cracklib.so retry=3
+password requisite pam_unix.so shadow md5 use_authtok try_first_pass
+password required pam_smbpass.so nullok use_authtok try_first_pass
+session required pam_unix.so
+</programlisting></para>
+</sect3>
+
+<sect3>
+<title>Password Migration Configuration</title>
+
+<para>
+The following PAM configuration 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>
+ <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></para>
+</sect3>
+
+<sect3>
+<title>Mature Password Configuration</title>
+
+<para>
+The following is 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>
+<programlisting>
+#%PAM-1.0
+# password-mature
+#
+auth requisite pam_nologin.so
+auth required pam_unix.so
+account required pam_unix.so
+password requisite pam_cracklib.so retry=3
+password requisite pam_unix.so shadow md5 use_authtok try_first_pass
+password required pam_smbpass.so use_authtok use_first_pass
+session required pam_unix.so
+</programlisting></para>
+</sect3>
+
+<sect3>
+<title>Kerberos Password Integration Configuration</title>
+
+<para>
+The following is 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>
+ <programlisting>
+#%PAM-1.0
+# kdc-pdc
+#
+auth requisite pam_nologin.so
+auth requisite pam_krb5.so
+auth optional pam_smbpass.so migrate
+account required pam_krb5.so
+password requisite pam_cracklib.so retry=3
+password optional pam_smbpass.so nullok use_authtok try_first_pass
+password required pam_krb5.so use_authtok try_first_pass
+session required pam_krb5.so
+</programlisting></para>
+
+</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>
+
+ <sect2>
+ <title>pam_winbind Problem</title>
+
+ <para>
+ A user reported, <emphasis>I have the following PAM configuration</emphasis>:
+ </para>
+
+<para>
+<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>
+</para>
+
+ <para>
+ <emphasis>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.</emphasis>
+ </para>
+
+ <para>
+ The problem may lie with the 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. Alternatively, if you want all services to use
+ Winbind, you can put the Winbind-specific stuff in <filename>/etc/pam.d/system-auth</filename>.
+ </para>
+
+ </sect2>
+
+ <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>
+ 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-xml/Samba3-HOWTO/TOSHARG-PDC.xml b/docs-xml/Samba3-HOWTO/TOSHARG-PDC.xml
new file mode 100644
index 0000000000..d37edbe17f
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-PDC.xml
@@ -0,0 +1,1409 @@
+<?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 are well advised to become familiar with information
+that is already available.
+</para>
+
+<para>
+<indexterm><primary>domain</primary><secondary>controller</secondary></indexterm>
+You are advised not to tackle this section without having first understood
+and mastered some basics. MS Windows networking is not particularly forgiving of
+misconfiguration. 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 Example Domain Illustration</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>
+
+<figure id="domain-example">
+ <title>An Example Domain.</title>
+ <imagefile scale="40">domain</imagefile>
+</figure>
+
+<para>
+From the Samba mailing list we 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>
+<indexterm>single sign-on<primary></primary><see>SSO</see></indexterm>
+<indexterm><primary>trust</primary></indexterm>
+<indexterm><primary>account</primary></indexterm>
+<indexterm><primary>domain</primary><secondary>security</secondary><tertiary>protocols</tertiary></indexterm>
+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 contains their user account (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>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>relative identifier</primary><see>RID</see></indexterm>
+<indexterm><primary>security identifier</primary><see>SID</see></indexterm>
+<indexterm><primary>access control</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>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+A SID represents a security context. For example, every Windows machine has local accounts within the security
+context of the local machine which has a unique SID. Every domain (NT4, ADS, Samba) contains accounts that
+exist within the domain security context which is defined by the domain SID.
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+A domain member server will have a SID that differs from the domain SID. The domain member server can be
+configured to regard all domain users as local users. It can also be configured to recognize domain users and
+groups as non-local. SIDs are persistent. A typical domain of user SID looks like this:
+<screen>
+S-1-5-21-726309263-4128913605-1168186429
+</screen>
+Every account (user, group, machine, trust, etc.) is assigned a RID. This is done automatically as an account
+is created. Samba produces the RID algorithmically. The UNIX operating system uses a separate name space for
+user and group identifiers (the UID and GID) but Windows allocates the RID from a single name space. A Windows
+user and a Windows group can not have the same RID. Just as the UNIX user <literal>root</literal> has the
+UID=0, the Windows Administrator has the well-known RID=500. The RID is catenated to the Windows domain SID,
+so Administrator account for a domain that has the above SID will have the user SID
+<screen>
+S-1-5-21-726309263-4128913605-1168186429-500
+</screen>
+The result is that every account in the Windows networking world has a globally unique security identifier.
+</para>
+
+<note><para>
+<indexterm><primary>domain</primary><secondary>member</secondary></indexterm>
+<indexterm><primary>machine account</primary></indexterm>
+<indexterm><primary>domain</primary><secondary>trust account</secondary></indexterm>
+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>
+ <indexterm><primary>account</primary><secondary>backend</secondary></indexterm>
+ Samba-3 supports the use of a choice of backends that may be used in which user, group and machine
+ accounts may be stored. Multiple passwd backends can be used in combination, either as additive backend
+ data sets, or as fail-over data sets.
+ </para>
+
+ <para>
+ <indexterm><primary>LDAP</primary></indexterm>
+ <indexterm><primary>replicated</primary></indexterm>
+ <indexterm><primary>distributed</primary></indexterm>
+ <indexterm><primary>scalability</primary></indexterm>
+ <indexterm><primary>reliability</primary></indexterm>
+ An LDAP passdb backend confers the benefit that the account backend can be distributed and replicated,
+ which is of great value because it confers scalability and provides a high degree of reliability.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>interdomain</primary><secondary>trust</secondary><tertiary>account</tertiary></indexterm>
+ <indexterm><primary>trust account</primary><secondary>interdomain</secondary></indexterm>
+ <indexterm><primary>interoperability</primary></indexterm>
+ Windows NT4 domain trusts. Samba-3 supports workstation and server (machine) trust accounts. It also
+ supports Windows NT4 style interdomain trust accounts, which further assists in network scalability
+ and interoperability.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>NetBIOS</primary></indexterm>
+ <indexterm><primary>raw SMB</primary></indexterm>
+ <indexterm><primary>active directory</primary></indexterm>
+ <indexterm><primary>domain</primary><secondary>member server</secondary></indexterm>
+ <indexterm><primary>domain</primary><secondary>controller</secondary></indexterm>
+ <indexterm><primary>network</primary><secondary>browsing</secondary></indexterm>
+ Operation without NetBIOS over TCP/IP, rather using the raw SMB over TCP/IP. Note, this is feasible
+ only when operating as a Microsoft active directory domain member server. When acting as a Samba domain
+ controller the use of NetBIOS is necessary to provide network browsing support.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>WINS</primary></indexterm>
+ <indexterm><primary>TCP port</primary></indexterm>
+ <indexterm><primary>session services</primary></indexterm>
+ Samba-3 provides NetBIOS name services (WINS), NetBIOS over TCP/IP (TCP port 139) session services, SMB over
+ TCP/IP (TCP port 445) session services, and Microsoft compatible ONC DCE RPC services (TCP port 135)
+ services.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>Nexus.exe</primary></indexterm>
+ Management of users and groups 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>
+ 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 Windows NT PDC. Samba-3 can not
+ participate in replication of account data to Windows PDCs and BDCs.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>kerberos</primary></indexterm>
+ <indexterm><primary>active directory</primary></indexterm>
+ Acting as a Windows 2000 active directory 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.
+ Active directory domain control is one of the features that is being developed in Samba-4, the next
+ generation Samba release. At this time there are no plans to enable active directory domain control
+ support during the Samba-3 series life-cycle.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>MMC</primary></indexterm>
+ <indexterm><primary>SVRTOOLS.EXE</primary></indexterm>
+ <indexterm><primary>Microsoft management console</primary><see>MMC</see></indexterm>
+ The Windows 200x/XP Microsoft Management Console (MMC) cannot 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>
+<indexterm><primary>Windows XP Home edition</primary></indexterm>
+<indexterm><primary>LanMan</primary></indexterm>
+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>
+<indexterm><primary>group</primary><secondary>mapping</secondary></indexterm>
+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: MS
+Windows and UNIX</link>.
+</para>
+
+<para>
+<indexterm><primary>machine trust account</primary></indexterm>
+<indexterm><primary>trust account</primary><secondary>machine</secondary></indexterm>
+<indexterm><primary>machine account</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>Single Sign-On and Domain Security</title>
+
+<para>
+<indexterm><primary>single sign-on</primary><see>SSO</see></indexterm>
+<indexterm><primary>SSO</primary></indexterm>
+<indexterm><primary>active directory</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>validation</primary></indexterm>
+<indexterm><primary>password uniqueness</primary></indexterm>
+<indexterm><primary>password history</primary></indexterm>
+When network administrators are asked to describe the benefits of Windows NT4 and active directory networking
+the most often mentioned feature is that of single sign-on (SSO). Many companies have implemented SSO
+solutions. The mode of implementation of a single sign-on solution is an important factor in the practice of
+networking in general, and is critical in respect of Windows networking. A company may have a wide variety of
+information systems, each of which requires a form of user authentication and validation, thus it is not
+uncommon that users may need to remember more than ten login IDs and passwords. This problem is compounded
+when the password for each system must be changed at regular intervals, and particularly so where password
+uniqueness and history limits are applied.
+</para>
+
+<para>
+<indexterm><primary>management overheads</primary></indexterm>
+There is a broadly held perception that SSO is the answer to the problem of users having to deal with too many
+information system access credentials (username/password pairs). Many elaborate schemes have been devised to
+make it possible to deliver a user-friendly SSO solution. The trouble is that if this implementation is not
+done correctly, the site may end up paying dearly by way of complexity and management overheads. Simply put,
+many SSO solutions are an administrative nightmare.
+</para>
+
+<para>
+<indexterm><primary>identity management</primary></indexterm>
+<indexterm><primary>authentication system</primary></indexterm>
+<indexterm><primary>SSO</primary></indexterm>
+SSO implementations utilize centralization of all user account information. Depending on environmental
+complexity and the age of the systems over which a SSO solution is implemented, it may not be possible to
+change the solution architecture so as to accomodate a new identity management and user authentication system.
+Many SSO solutions involving legacy systems consist of a new super-structure that handles authentication on
+behalf of the user. The software that gets layered over the old system may simply implement a proxy
+authentication system. This means that the addition of SSO increases over-all information systems complexity.
+Ideally, the implementation of SSO should reduce complexity and reduce administative overheads.
+</para>
+
+<para>
+<indexterm><primary>centralized identity management</primary></indexterm>
+<indexterm><primary>identity management</primary><secondary>centralized</secondary></indexterm>
+<indexterm><primary>centralized</primary><secondary>authentication</secondary></indexterm>
+<indexterm><primary>legacy systems</primary></indexterm>
+<indexterm><primary>access control</primary></indexterm>
+The initial goal of many network administrators is often to create and use a centralized identity management
+system. It is often assumed that such a centralized system will use a single authentication infrastructure
+that can be used by all information systems. The Microsoft Windows NT4 security domain architecture and the
+Micrsoft active directory service are often put forward as the ideal foundation for such a system. It is
+conceptually simple to install an external authentication agent on each of the disparate infromation systems
+that can then use the Microsoft (NT4 domain or ads service) for user authentication and access control. The
+wonderful dream of a single centralized authentication service is commonly broken when realities are realized.
+The problem with legacy systems is often the inability to externalize the authentication and access control
+system it uses because its implementation will be excessively invasive from a re-engineering perspective, or
+because application software has built-in dependencies on particular elements of the way user authentication
+and access control were designed and built.
+</para>
+
+<para>
+<indexterm><primary>meta-directory</primary></indexterm>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>disparate information systems</primary></indexterm>
+<indexterm><primary>management procedures</primary></indexterm>
+<indexterm><primary>work-flow protocol</primary></indexterm>
+<indexterm><primary>rights</primary></indexterm>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>provisioned</primary></indexterm>
+Over the past decade an industry has been developed around the various methods that have been built to get
+around the key limitations of legacy information technology systems. One approach that is often used involves
+the use of a meta-directory. The meta-directory stores user credentials for all disparate information systems
+in the format that is particular to each system. An elaborate set of management procedures is coupled with a
+rigidly enforced work-flow protocol for managing user rights and privileges within the maze of systems that
+are provisioned by the new infrastructure makes possible user access to all systems using a single set of user
+credentials.
+</para>
+
+<para>
+<indexterm><primary>Organization for the Advancement of Structured Information Standards</primary><see>OASIS</see></indexterm>
+<indexterm><primary>Security Assertion Markup Language</primary><see>SAML</see></indexterm>
+<indexterm><primary>Federated Identity Management</primary><see>FIM</see></indexterm>
+<indexterm><primary>secure access</primary></indexterm>
+The Organization for the Advancement of Structured Information Standards (OASIS) has developed the Security
+Assertion Markup Language (SAML), a structured method for communication of authentication information. The
+over-all umbrella name for the technologies and methods that deploy SAML is called Federated Identity
+Management (FIM). FIM depends on each system in the complex maze of disparate information systems to
+authenticate their respective users and vouch for secure access to the services each provides.
+</para>
+
+<para>
+<indexterm><primary>Simple Object Access Protocol</primary><see>SOAP</see></indexterm>
+<indexterm><primary>federated organizations</primary></indexterm>
+<indexterm><primary>Liberty Alliance</primary></indexterm>
+<indexterm><primary>federated-identity</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+SAML documents can be wrapped in a Simple Object Access Protocol (SOAP) message for the computer-to-computer
+communications needed for Web services. Or they may be passed between Web servers of federated organizations
+that share live services. The Liberty Alliance, an industry group formed to promote federated-identity
+standards, has adopted SAML 1.1 as part of its application framework. Microsoft and IBM have proposed an
+alternative specification called WS-Security. Some believe that the competing technologies and methods may
+converge when the SAML 2.0 standard is introduced. A few Web access-management products support SAML today,
+but implemention of the technology mostly requires customization to integrate applications and develop user
+interfaces. In a nust-shell, that is why FIM is a big and growing industry.
+</para>
+
+<para>
+<indexterm><primary>interoperability</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>GSSAPI</primary></indexterm>
+<indexterm><primary>general security service application programming interface</primary><see>GSSAPI</see></indexterm>
+Ignoring the bigger picture, which is beyond the scope of this book, the migration of all user and group
+management to a centralized system is a step in the right direction. It is essential for interoperability
+reasons to locate the identity management system data in a directory such as Microsoft Active Directory
+Service (ADS), or any proprietary or open source system that provides a standard protocol for information
+access (such as LDAP) and that can be coupled with a flexible array of authentication mechanisms (such as
+kerberos) that use the protocols that are defined by the various general security service application
+programming interface (GSSAPI) services.
+</para>
+
+<para>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>authentication agents</primary></indexterm>
+A growing number of companies provide authentication agents for disparate legacy platforms to permit the use
+of LDAP systems. Thus the use of OpenLDAP, the dominant open source software implementation of the light
+weight directory access protocol standard. This fact, means that by providing support in Samba for the use of
+LDAP and Microsoft ADS make Samba a highly scalable and forward reaching organizational networking technology.
+</para>
+
+<para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>authentication architecture</primary></indexterm>
+<indexterm><primary>ntlm_auth</primary></indexterm>
+<indexterm><primary>SQUID</primary></indexterm>
+<indexterm><primary>FIM</primary></indexterm>
+Microsoft ADS provides purely proprietary services that, with limitation, can be extended to provide a
+centralized authentication infrastructure. Samba plus LDAP provides a similar opportunity for extension of a
+centralized authentication architecture, but it is the fact that the Samba Team are pro-active in introducing
+the extension of authentication services, using LDAP or otherwise, to applications such as SQUID (the open
+source proxy server) through tools such as the <command>ntlm_auth</command> utility, that does much to create
+sustainable choice and competition in the FIM market place.
+</para>
+
+<para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>identity information</primary></indexterm>
+Primary domain control, if it is to be scalable to meet the needs of large sites, must therefore be capable of
+using LDAP. The rapid adoption of OpenLDAP, and Samba configurations that use it, is ample proof that the era
+of the directory has started. Samba-3 does not demand the use of LDAP, but the demand for a mechanism by which
+user and group identity information can be distributed makes it an an unavoidable option.
+</para>
+
+<para>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>e-Directory</primary></indexterm>
+At this time, the use of Samba based BDCs, necessitates the use of LDAP. The most commonly used LDAP
+implementation used by Samba sites is OpenLDAP. It is possible to use any standards compliant LDAP server.
+Those known to work includes those manufactured by: IBM, CA, Novell (e-Directory), and others.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Basics of Domain Control</title>
+
+<para>
+<indexterm><primary>domain control</primary></indexterm>
+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>NT4 style Primary Domain Controller</para></listitem>
+ <listitem><para>NT4 style Backup Domain Controller</para></listitem>
+ <listitem><para>ADS Domain Controller</para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>powerful</primary></indexterm>
+<indexterm><primary>network</primary><secondary>performance</secondary></indexterm>
+<indexterm><primary>domain</primary><secondary>member</secondary><secondary>server</secondary></indexterm>
+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 standalone
+(domain member) servers than in the domain controllers.
+</para>
+
+<para>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>authenticatior</primary></indexterm>
+<indexterm><primary>synchronization</primary></indexterm>
+<indexterm><primary>Security Account Manager</primary><see>SAM</see></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 BDCs.
+</para>
+
+<para>
+<indexterm><primary>domain</primary><secondary>controller</secondary><tertiary>hierarchy</tertiary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm>account<primary></primary><secondary>backend</secondary></indexterm>
+<indexterm><primary>machine account</primary></indexterm>
+With MS Windows 200x Server-based Active Directory domains, one domain controller initiates a potential
+hierarchy of domain controllers, each with its own area of delegated control. The master domain
+controller has the ability to override any downstream controller, but a downline controller has
+control only over its downline. With Samba-3, this functionality can be implemented using an
+LDAP-based user and machine account backend.
+</para>
+
+<para>
+<indexterm><primary>backend database</primary></indexterm>
+<indexterm><primary>registry</primary></indexterm>
+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>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>netlogon</primary></indexterm>
+<indexterm><primary>name lookup</primary></indexterm>
+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). When a user logs onto a Windows domain member client the
+workstation will query the network to locate the nearest network logon server. Where a WINS server is used,
+this is done via a query to the WINS server. If a netlogon server can not be found from the WINS query, or in
+the absence of a WINS server, the workstation will perform a NetBIOS name lookup via a mailslot broadcast over
+the UDP broadcast protocol. This means that the netlogon server that the windows client will use is influenced
+by a number of variables, thus there is no simple determinant of whether a PDC or a BDC will serve a
+particular logon authentication request.
+</para>
+
+<para>
+<indexterm><primary>promote</primary></indexterm>
+<indexterm><primary>demote</primary></indexterm>
+A Windows NT4 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 other appropriate changes also need to be made.
+</para>
+
+<para>
+<indexterm><primary>domain</primary><secondary>controller</secondary><tertiary>convert</tertiary></indexterm>
+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 method Microsoft provide to convert a
+Windows NT4 domain controller to a domain member server or a standalone 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>Standalone Server</emphasis> &smbmdash; one that plays no part in SAM synchronization,
+ has its own authentication database, and plays no role in domain security.</para></listitem>
+</itemizedlist>
+
+<note><para>
+<indexterm><primary>promote</primary></indexterm>
+Algin Technology LLC provide a commercial tool that makes it possible to promote a Windows NT4 standalone
+server to a PDC or a BDC, and also permits this process to be reversed. Refer to the <ulink
+url="http://utools.com/UPromote.asp">Algin</ulink> web site for further information.
+</para></note>
+
+<para>
+<indexterm><primary>domain</primary><secondary>control</secondary><tertiary>role</tertiary></indexterm>
+<indexterm><primary>native member</primary></indexterm>
+Samba-3 servers can readily be converted to and from domain controller roles through simple changes to the
+&smb.conf; file. Samba-3 is capable of acting fully as a native member of a Windows 200x server Active
+Directory domain.
+</para>
+
+<para>
+<indexterm><primary>convert</primary><secondary>domain member server</secondary></indexterm>
+For the sake of providing a complete picture, MS Windows 2000 domain control configuration is done after the server has been
+installed. Please refer to Microsoft documentation for the procedures that should be followed to convert a
+domain member server to or from a domain control, and to install or remove active directory service support.
+</para>
+
+<para>
+<indexterm><primary>replication</primary><secondary>SAM</secondary></indexterm>
+<indexterm><primary>SAM</primary><secondary>replication</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>
+<indexterm><primary>ADS</primary></indexterm>
+At this time any appearance that Samba-3 is capable of acting as a <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 domain controller in a Windows 2000/XP
+environment. However, there are certain compromises:
+</para>
+
+<itemizedlist>
+ <listitem><para>No machine policy files.</para></listitem>
+ <listitem><para>No Group Policy Objects.</para></listitem>
+ <listitem><para>No synchronously executed Active Directory 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 Active Directory they do not leave
+ permanent changes in effect.</para></listitem>
+ <listitem><para>Without Active Directory you cannot perform the function of exporting specific
+ applications to specific users or groups.</para></listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Preparing for Domain Control</title>
+
+<para>
+<indexterm><primary>standalone</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>member</primary></indexterm>
+<indexterm><primary>security</primary></indexterm>
+There are two ways that MS Windows machines may interact with each other, with other servers,
+and with domain controllers: either as <emphasis>standalone</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>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>workgroup</primary><secondary>membership</secondary></indexterm>
+<indexterm><primary>machine trust account</primary></indexterm>
+It should be noted that workgroup 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>
+<indexterm><primary>domain membership</primary></indexterm>
+<indexterm><primary>machine trust account</primary><secondary>password</secondary></indexterm>
+<indexterm><primary>trigger</primary></indexterm>
+Domain member machines have a machine trust 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, creates the domain machine account (if it does
+not exist), and then initializes that account. When the client first logs onto the
+domain, a machine trust account password change will be automatically triggered.
+</para>
+
+<note><para>
+<indexterm><primary>domain member</primary></indexterm>
+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
+(standalone) machine. Please refer to <link linkend="domain-member">Domain Membership</link>, 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 NT4/2000 Professional and Windows XP Professional 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>
+<indexterm><primary>roaming profiles</primary></indexterm>
+<indexterm><primary>account policies</primary></indexterm>
+Roaming profiles and system/network policies are advanced network administration topics
+that are covered in <link linkend="ProfileMgmt">Desktop Profile Management</link> and
+<link linkend="PolicyMgmt">System and Account Policies</link> 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>
+ <indexterm><primary>NetBIOS</primary><secondary>brooadcast</secondary></indexterm>
+ <indexterm><primary>WINS</primary></indexterm>
+ <indexterm><primary>UDP</primary></indexterm>
+ <indexterm><primary>DNS</primary></indexterm>
+ <indexterm><primary>active directory</primary></indexterm>
+ 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 unicast, or via DNS and Active Directory).
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>NETLOGON</primary></indexterm>
+ <indexterm><primary>LanMan logon service</primary></indexterm>
+ 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>
+<indexterm><primary>domain</primary><secondary>master</secondary><tertiary>browser</tertiary></indexterm>
+<indexterm><primary>local</primary><secondary>master</secondary><tertiary>browser</tertiary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>LMB</primary></indexterm>
+<indexterm><primary>browse list</primary></indexterm>
+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 PDC to claim a domain-specific NetBIOS name that identifies
+it as a DMB for its given domain or workgroup. Local master browsers (LMBs) 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 then contact their LMB, 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: 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
+smb.conf file for an example PDC</link>.
+</para>
+
+<example id="pdc-example">
+<title>smb.conf for being a PDC</title>
+<smbconfblock>
+<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">auto</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>
+</smbconfblock>
+</example>
+
+<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>
+ <indexterm><primary>group</primary><secondary>account</secondary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>tdbsam</primary></indexterm>
+ <indexterm><primary>ldapsam</primary></indexterm>
+ <indexterm><primary>guest</primary></indexterm>
+ <indexterm><primary>default accounts</primary></indexterm>
+ 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>
+ <indexterm><primary>passdb backend</primary></indexterm>
+ <indexterm><primary>distributed</primary></indexterm>
+ <indexterm><primary>smbpasswd</primary></indexterm>
+ <indexterm><primary>tdbsam</primary></indexterm>
+ Where use of 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>
+ <indexterm><primary>os level</primary></indexterm>
+ <indexterm><primary>preferred master</primary></indexterm>
+ <indexterm><primary>domain master</primary></indexterm>
+ <indexterm><primary>network</primary><secondary>logon</secondary></indexterm>
+ The parameters <emphasis>os level, preferred master, domain master, security,
+ encrypt passwords</emphasis>, and <emphasis>domain logons</emphasis> play a central role in assuring domain
+ control and network logon support.
+ </para>
+
+ <para>
+ <indexterm><primary>DMB</primary></indexterm>
+ <indexterm><primary>encryped password</primary></indexterm>
+ The <emphasis>os level</emphasis> must be set at or above a value of 32. A domain controller
+ must be the DMB, 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>
+ <indexterm><primary>logon path</primary></indexterm>
+ <indexterm><primary>logon home</primary></indexterm>
+ <indexterm><primary>logon drive</primary></indexterm>
+ <indexterm><primary>logon script</primary></indexterm>
+ The parameters <emphasis>logon path, logon home, logon drive</emphasis>, and <emphasis>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>
+ <indexterm><primary>NETLOGON</primary></indexterm>
+ <indexterm><primary>logon processing</primary></indexterm>
+ <indexterm><primary>domain logon</primary></indexterm>
+ <indexterm><primary>domain membership</primary></indexterm>
+ <indexterm><primary>group policy</primary></indexterm>
+ <indexterm><primary>NTConfig.POL</primary></indexterm>
+ 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>
+ <indexterm><primary>desktop profile</primary></indexterm>
+ <indexterm><primary>VFS</primary></indexterm>
+ <indexterm><primary>fake_permissions</primary></indexterm>
+ <indexterm><primary>profile</primary></indexterm>
+ <indexterm><primary></primary></indexterm>
+ 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 functionality 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 in this section just make for
+a more complete explanation.
+</para></note>
+
+</sect1>
+
+<sect1>
+<title>Samba ADS Domain Control</title>
+
+<para>
+<indexterm><primary>active directory</primary></indexterm>
+Samba-3 is not, and cannot act as, an Active Directory server. It cannot truly function as an Active Directory
+PDC. 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
+someday or maybe never!
+</para>
+
+<para>
+<indexterm><primary>domain controllers</primary></indexterm>
+<indexterm><primary>active directory</primary></indexterm>
+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>
+<indexterm><primary>domain logon</primary></indexterm>
+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>
+<indexterm><primary>domain logon</primary></indexterm>
+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 PDC); on all BDCs set the parameter <smbconfoption name="domain master">No</smbconfoption>.
+</para>
+
+<sect3>
+<title>Example Configuration</title>
+
+<example id="PDC-config">
+<title>smb.conf for being a PDC</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+</sect3>
+<sect3>
+<title>The Special Case of MS Windows XP Home Edition</title>
+
+<para>
+<indexterm><primary>Windows XP Home edition</primary></indexterm>
+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>
+<indexterm><primary>domain</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>browsing</primary></indexterm>
+<indexterm><primary>rights</primary></indexterm>
+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>
+<indexterm><primary>browsing</primary></indexterm>
+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>
+<indexterm><primary>single-logon</primary></indexterm>
+<indexterm><primary>domain logons</primary></indexterm>
+<indexterm><primary>network logon</primary></indexterm>
+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>
+<indexterm><primary>broadcast request</primary></indexterm>
+When an SMB client in a domain wishes to log on, 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;
+that is, 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 log on 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>
+ <indexterm><primary>DOMAIN&lt;1C&gt;</primary></indexterm>
+ <indexterm><primary>logon server</primary></indexterm>
+ 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&lt;1C&gt; 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>. The <literal>1C</literal> name is the name
+ type that is registered by domain controllers (SMB/CIFS servers that provide
+ the netlogon service).
+ </para>
+</listitem>
+
+<listitem>
+ <para>
+ <indexterm><primary>IPC$</primary></indexterm>
+ <indexterm><primary>SMBsessetupX</primary></indexterm>
+ <indexterm><primary>SMBtconX</primary></indexterm>
+ 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>
+ <indexterm><primary>NetWkstaUserLogon</primary></indexterm>
+ 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>
+ <indexterm><primary>NetUserGetInfo</primary></indexterm>
+ <indexterm><primary>profile</primary></indexterm>
+ 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>
+ <indexterm><primary>profiles</primary></indexterm>
+ 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>
+ <indexterm><primary>CONFIG.POL</primary></indexterm>
+ 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>
+ <indexterm><primary>password</primary><secondary>plaintext</secondary></indexterm>
+ <indexterm><primary>plaintext password</primary></indexterm>
+ 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 plaintext
+ 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>
+ <indexterm><primary>machine trust account</primary></indexterm>
+ Windows 9x/Me clients do not require and do not use Machine Trust Accounts.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>network logon services</primary></indexterm>
+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>
+<indexterm><primary>sniffer</primary></indexterm>
+Use of plaintext 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>
+<indexterm><primary>security mode</primary></indexterm>
+<indexterm><primary>user-mode security</primary></indexterm>
+<indexterm><primary>share-mode security</primary></indexterm>
+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 that operates with security mode other than
+user-mode. 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>
+<indexterm><primary>DOMAIN&lt;1C&gt;</primary></indexterm>
+<indexterm><primary>DOMAIN&lt;1B&gt;</primary></indexterm>
+<indexterm><primary>DMB</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>NetBIOS name</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>election</primary></indexterm>
+Actually, this issue is also closely tied to the debate on whether Samba must be the DMB for its workgroup
+when operating as a domain controller. In a pure Microsoft Windows NT domain, the PDC wins the election to be
+the DMB, and then registers the DOMAIN&lt;1B&gt; NetBIOS name. This is not the name used by Windows clients
+to locate the domain controller, all domain controllers register the DOMAIN&lt;1C&gt; name and Windows clients
+locate a network logon server by seraching for the DOMAIN&lt;1C&gt; name. A DMB is a Domain Master Browser
+&smbmdash; see <link linkend="NetworkBrowsing">The Network Browsing Chapter</link>, <link
+linkend="DMB">Configuring WORKGROUP Browsing</link>; Microsoft PDCs expect to win the election to become the
+DMB, if it loses that election it will report a continuous and rapid sequence of warning messages to its
+Windows event logger complaining that it has lost the election to become a DMB. For this reason, in networks
+where a Samba server is the PDC it is wise to configure the Samba domain controller as the DMB.
+</para>
+
+<note><para>
+<indexterm><primary>DOMAIN&lt;1D&gt;</primary></indexterm>
+<indexterm><primary>synchronization</primary></indexterm>
+<indexterm><primary>domain control</primary></indexterm>
+<indexterm><primary>browse list management</primary></indexterm>
+<indexterm><primary>network</primary><secondary>logon</secondary><tertiary>service</tertiary></indexterm>
+SMB/CIFS servers that register the DOMAIN&lt;1C&gt; name do so because they provide the network logon
+service. Server that register the DOMAIN&lt;1B&gt; name are DMBs &smbmdash; meaning that they are responsible
+for browse list synchronization across all machines that have registered the DOMAIN&lt;1D&gt; name. The later
+are LMBs that have the responsibility to listen to all NetBIOS name registrations that occur locally to their
+own network segment. The network logon service (NETLOGON) is germane to domain control and has nothing to do
+with network browsing and browse list management. The 1C and 1B/1D name services are orthogonal to each
+other.
+</para></note>
+
+<para>
+Now back to the issue of configuring a Samba domain controller to use a mode other than <smbconfoption
+name="security">user</smbconfoption>. If a Samba host is configured to use another SMB server or domain
+controller 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 percent
+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 domain controller for a domain that already by definition has a
+PDC is asking for trouble. Therefore, you should always configure the Samba domain controller
+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>
+<indexterm><primary>BSD</primary></indexterm>
+<indexterm><primary>FreeBSD</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+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>
+<indexterm><primary>vipw</primary></indexterm>
+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.
+The use of vipw will ensure that shadow files (where used) will remain current with the passwd file. This is
+important for security reasons.
+</para></note>
+
+</sect2>
+
+<sect2>
+<title>Joining Domain Fails Because of Existing Machine Account</title>
+
+<para>
+<indexterm><primary>join domain</primary></indexterm>
+<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>
+This will break all network connections.
+</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 &smbmdash;
+it does not matter what &smbmdash; 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 rejoin
+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 the POSIX UNIX system account backend as well as in the
+SambaSAMAccount backend. The default backend for Samba-3 (i.e., the parameter <parameter>passdb
+backend</parameter> is not specified in the &smb.conf; file, or if specified is set to
+<literal>smbpasswd</literal>, are respectively the <filename>/etc/passwd</filename> and
+<filename>/etc/samba/smbpasswd</filename> (or <filename>/usr/local/samba/lib/private/smbpasswd</filename> if
+compiled using Samba Team default settings). The use of the <filename>/etc/passwd</filename> can be overridden
+by alternative settings in the NSS <filename>/etc/nsswitch.conf</filename> 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 log in 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 15 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</emphasis>, <emphasis>server schannel</emphasis>,
+<emphasis>client signing</emphasis>, <emphasis>server signing</emphasis> by executing:
+<screen>
+<command>testparm -v | grep channel</command> and looking for the value of these parameters.
+</screen>
+</para>
+
+<para>
+Also use the MMC &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-xml/Samba3-HOWTO/TOSHARG-Passdb.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Passdb.xml
new file mode 100644
index 0000000000..957abbfdad
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Passdb.xml
@@ -0,0 +1,2675 @@
+<?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>
+<indexterm><primary>account backends</primary></indexterm>
+<indexterm><primary>password backends</primary></indexterm>
+<indexterm><primary>scalability</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+Early releases of Samba-3 implemented new capability to work concurrently with multiple account backends. This
+capability was removed beginning with release of Samba 3.0.23. Commencing with Samba 3.0.23 it is possible to
+work with only one specified passwd backend.
+</para>
+
+<para>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>single repository</primary></indexterm>
+The three passdb backends that are fully maintained (actively supported) by the Samba Team are:
+<literal>smbpasswd</literal> (being obsoleted), <literal>tdbsam</literal> (a tdb-based binary file format),
+and <literal>ldapsam</literal> (LDAP directory). Of these, only the <literal>ldapsam</literal> backend
+stores both POSIX (UNIX) and Samba user and group account information in a single repository. The
+<literal>smbpasswd</literal> and <literal>tdbsam</literal> backends store only Samba user accounts.
+</para>
+
+<para>
+In a strict sense, there are three supported account storage and access systems. One of these is considered
+obsolete (smbpasswd). It is recommended to use the <literal>tdbsam</literal> method for all simple systems. Use
+<literal>ldapsam</literal> for larger and more complex networks.
+</para>
+
+<para>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>account storage mechanisms</primary></indexterm>
+<indexterm><primary>account storage system</primary></indexterm>
+<indexterm><primary>user and trust accounts</primary></indexterm>
+<indexterm><primary>machine trust accounts</primary></indexterm>
+<indexterm><primary>computer accounts</primary></indexterm>
+<indexterm><primary>interdomain trust accounts</primary></indexterm>
+In a strict and literal sense, the passdb backends are account storage mechanisms (or methods) alone. The choice
+of terminology can be misleading, however we are stuck with this choice of wording. This chapter documents the
+nature of the account storage system with a focus on user and trust accounts. Trust accounts have two forms,
+machine trust accounts (computer accounts) and interdomain trust accounts. These are all treated as user-like
+entities.
+</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>
+
+<sect2>
+ <title>Backward Compatibility Account Storage Systems</title>
+
+<variablelist>
+ <varlistentry><term>Plaintext</term>
+ <listitem>
+ <para>
+<indexterm><primary>plaintext</primary></indexterm>
+<indexterm><primary>plaintext authentication</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>/etc/shadow</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+ 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 plaintext
+ password usage.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>smbpasswd</term>
+ <listitem>
+ <para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>LanMan passwords</primary></indexterm>
+<indexterm><primary>NT-encrypted passwords</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+ 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
+ interoperation 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>
+<indexterm><primary>ldapsam_compat</primary></indexterm>
+<indexterm><primary>Samba-2.2.x LDAP schema</primary></indexterm>
+<indexterm><primary>OpenLDAP backend</primary></indexterm>
+ 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 Account Storage Systems</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>
+</para>
+
+<variablelist>
+ <varlistentry><term>tdbsam</term>
+ <listitem>
+ <para>
+<indexterm><primary>rich database backend</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+ 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>
+<indexterm><primary>extended SAM</primary></indexterm>
+<indexterm><primary>TDB</primary></indexterm>
+<indexterm><primary>binary format TDB</primary></indexterm>
+<indexterm><primary>trivial database</primary></indexterm>
+<indexterm><primary>system access controls</primary></indexterm>
+<indexterm><primary>MS Windows NT4/200x</primary></indexterm>
+ 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>
+<indexterm><primary>simple operation</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+ 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>
+<indexterm><primary>rich directory backend</primary></indexterm>
+<indexterm><primary>distributed account</primary></indexterm>
+ This provides a rich directory backend for distributed account installation.
+ </para>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>Samba schema</primary></indexterm>
+<indexterm><primary>schema file</primary></indexterm>
+<indexterm><primary>examples/LDAP</primary></indexterm>
+ 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>
+<indexterm><primary>expands control abilities</primary></indexterm>
+<indexterm><primary>profile</primary></indexterm>
+<indexterm><primary>home directories</primary></indexterm>
+<indexterm><primary>account access controls</primary></indexterm>
+<indexterm><primary>greater scalability</primary></indexterm>
+ 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 greater scalability.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="passdbtech">
+ <title>Technical Information</title>
+
+ <para>
+<indexterm><primary>plaintext passwords</primary></indexterm>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+ Old Windows clients send plaintext 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>
+<indexterm><primary>LanMan</primary></indexterm>
+<indexterm><primary>plaintext passwords</primary></indexterm>
+<indexterm><primary>registry</primary></indexterm>
+ Newer Windows clients send encrypted passwords (LanMan and NT hashes) instead of plaintext passwords over
+ the wire. The newest clients will send only encrypted passwords and refuse to send plaintext passwords unless
+ their registry is tweaked.
+ </para>
+
+ <para>
+<indexterm><primary>UNIX-style encrypted passwords</primary></indexterm>
+<indexterm><primary>converted</primary></indexterm>
+ Many people ask why Samba cannot simply use the UNIX password database. Windows requires
+ passwords that are encrypted in its own format. The UNIX 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>
+<indexterm><primary>differently encrypted passwords</primary></indexterm>
+<indexterm><primary>profile</primary></indexterm>
+<indexterm><primary>workstations</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+ 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,
+ tdbsam, and plain text file. For more information, see the man page for &smb.conf; regarding the
+ <smbconfoption name="passdb backend"/> parameter.
+ </para>
+
+
+ <figure id="idmap-sid2uid">
+ <title>IDMAP: Resolution of SIDs to UIDs.</title>
+ <imagefile scale="40">idmap-sid2uid</imagefile>
+ </figure>
+
+ <para>
+ <indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<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>
+
+ <figure id="idmap-uid2sid">
+ <title>IDMAP: Resolution of UIDs to SIDs.</title>
+ <imagefile scale="50">idmap-uid2sid</imagefile>
+ </figure>
+
+ <sect2>
+ <title>Important Notes About Security</title>
+
+ <para>
+<indexterm><primary>SMB password encryption</primary></indexterm>
+<indexterm><primary>clear-text passwords</primary></indexterm>
+<indexterm><primary>hashed password equivalent</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>secret</primary></indexterm>
+ 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 therefore treat the data stored in whatever passdb
+ backend you use (smbpasswd file, LDAP) 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>
+<indexterm><primary>password scheme</primary></indexterm>
+<indexterm><primary>plaintext passwords</primary></indexterm>
+<indexterm><primary>compatible</primary></indexterm>
+ Ideally, we would like a password scheme that involves neither plaintext passwords
+ on the network nor plaintext passwords on disk. Unfortunately, this is not available because Samba is stuck with
+ having to be compatible with other SMB systems (Windows NT, Windows for Workgroups, Windows 9x/Me).
+ </para>
+
+ <para>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+<indexterm><primary>plaintext passwords</primary></indexterm>
+ 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>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>domain environment</primary></indexterm>
+ 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>
+<indexterm><primary>Windows XP Home</primary></indexterm>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>domain logons</primary></indexterm>
+ 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>
+<indexterm><primary>SMB/CIFS</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>challenge/response mechanis</primary></indexterm>
+<indexterm><primary>clear-text</primary></indexterm>
+<indexterm><primary>encrypted</primary></indexterm>
+<indexterm><primary>negotiate</primary></indexterm>
+ 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 plaintext or encrypted password
+ handling.
+ </para>
+
+ <para>
+<indexterm><primary>cached encrypted password</primary></indexterm>
+<indexterm><primary>plaintext passwords</primary></indexterm>
+<indexterm><primary>registry change</primary></indexterm>
+<indexterm><primary>auto-reconnect</primary></indexterm>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+ MS Windows clients will cache the encrypted password alone. Where plaintext passwords
+ are re-enabled through the appropriate registry change, the plaintext 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>
+<indexterm><primary>passed across the network</primary></indexterm>
+<indexterm><primary>network sniffer</primary></indexterm>
+<indexterm><primary>SMB server</primary></indexterm>
+ 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>
+<indexterm><primary>not stored anywhere</primary></indexterm>
+<indexterm><primary>memory</primary></indexterm>
+<indexterm><primary>disk</primary></indexterm>
+ Plaintext passwords are not stored anywhere in memory or on disk.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+<indexterm><primary>user-level security</primary></indexterm>
+<indexterm><primary>password prompt</primary></indexterm>
+<indexterm><primary>SMB encryption</primary></indexterm>
+ 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 thing you can do to stop this is to use SMB
+ encryption.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>encrypted password</primary></indexterm>
+<indexterm><primary>automatic reconnects</primary></indexterm>
+ Encrypted password support allows automatic share (resource) reconnects.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+ Encrypted passwords are essential for PDC/BDC operation.
+ </para></listitem>
+ </itemizedlist>
+ </sect3>
+
+
+ <sect3>
+ <title>Advantages of Non-Encrypted Passwords</title>
+
+ <itemizedlist>
+ <listitem><para>
+<indexterm><primary>cached in memory</primary></indexterm>
+ Plaintext passwords are not kept on disk and are not cached in memory.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>Login</primary></indexterm>
+<indexterm><primary>FTP</primary></indexterm>
+ Plaintext passwords use the same password file as other UNIX services, such as Login and FTP.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>Telnet</primary></indexterm>
+<indexterm><primary>FTP</primary></indexterm>
+ Use of other services (such as Telnet and FTP) that send plaintext passwords over
+ the network makes sending them for SMB not such a big deal.
+ </para></listitem>
+ </itemizedlist>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Mapping User Identifiers between MS Windows and UNIX</title>
+
+ <para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>mapping</primary></indexterm>
+ 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>
+<indexterm><primary>Samba SAM</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>account information database</primary></indexterm>
+<indexterm><primary>local user account</primary></indexterm>
+ First, all Samba SAM 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>
+ <indexterm><primary>UID</primary></indexterm>
+ <indexterm><primary>SAM</primary></indexterm>
+ <indexterm><primary>foreign domain</primary></indexterm>
+ <indexterm><primary>non-member Windows client</primary></indexterm>
+ <indexterm><primary>SID</primary></indexterm>
+ The second way to map Windows SID to UNIX UID 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 (non-member Windows client
+ or a member of a foreign domain) SAM server.
+ </para>
+
+ </sect2>
+
+ <sect2 id="idmapbackend">
+ <title>Mapping Common UIDs/GIDs on Distributed Machines</title>
+
+ <para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>domain member servers</primary></indexterm>
+<indexterm><primary>NFS</primary></indexterm>
+<indexterm><primary>rsync</primary></indexterm>
+ 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>LDAP-based</primary></indexterm>
+<indexterm><primary>idmap backend</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>SAM backend</primary></indexterm>
+<indexterm><primary>LDAP idmap Backend</primary></indexterm>
+ <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.
+ <link linkend="idmapbackendexample">Example Configuration with the LDAP idmap Backend</link>
+ shows that configuration.
+ </para>
+
+<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
+<example id="idmapbackendexample">
+<title>Example Configuration with the LDAP idmap Backend</title>
+<smbconfblock>
+<smbconfsection name="[global]"/>
+<smbconfoption name="idmap backend">ldap:ldap://ldap-server.quenya.org:636</smbconfoption>
+<smbconfcomment>Alternatively, this could be specified as:</smbconfcomment>
+<smbconfoption name="idmap backend">ldap:ldaps://ldap-server.quenya.org</smbconfoption>
+</smbconfblock>
+</example>
+
+ <para>
+<indexterm><primary>LDAP backends</primary></indexterm>
+<indexterm><primary>PADL Software</primary></indexterm>
+ 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>
+<indexterm><primary>nss_ldap</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>AIX</primary></indexterm>
+<indexterm><primary>Linux</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+ <emphasis>nss_ldap:</emphasis> An LDAP name service switch (NSS) 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 and GIDs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<indexterm><primary>pam_ldap</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>access authentication</primary></indexterm>
+ <emphasis>pam_ldap:</emphasis> A PAM module that provides LDAP integration for UNIX/Linux
+ system access authentication.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+<indexterm><primary>idmap_ad</primary></indexterm>
+<indexterm><primary>IDMAP backend</primary></indexterm>
+<indexterm><primary>RFC 2307</primary></indexterm>
+<indexterm><primary>PADL</primary></indexterm>
+ <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>Comments Regarding LDAP</title>
+
+ <para>
+<indexterm><primary>LDAP</primary><secondary>directories</secondary></indexterm>
+<indexterm><primary>architecture</primary></indexterm>
+<indexterm><primary>FIM</primary></indexterm>
+<indexterm><primary>SSO</primary></indexterm>
+ There is much excitement and interest in LDAP directories in the information technology world
+ today. The LDAP architecture was designed to be highly scalable. It was also designed for
+ use across a huge number of potential areas of application encompassing a wide range of operating
+ systems and platforms. LDAP technologies are at the heart of the current generations of Federated
+ Identity Management (FIM) solutions that can underlie a corporate Single Sign-On (SSO) environment.
+ </para>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>eDirectory</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+ LDAP implementations have been built across a wide variety of platforms. It lies at the core of Microsoft
+ Windows Active Directory services (ADS), Novell's eDirectory, as well as many others. Implementation of the
+ directory services LDAP involves interaction with legacy as well as new generation applications, all of which
+ depend on some form of authentication services.
+ </para>
+
+ <para>
+<indexterm><primary>LDAP directory</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>access controls</primary></indexterm>
+<indexterm><primary>intermediate tools</primary></indexterm>
+<indexterm><primary>middle-ware</primary></indexterm>
+<indexterm><primary>central environment</primary></indexterm>
+<indexterm><primary>infrastructure</primary></indexterm>
+<indexterm><primary>login shells</primary></indexterm>
+<indexterm><primary>mail</primary></indexterm>
+<indexterm><primary>messaging systems</primary></indexterm>
+<indexterm><primary>quota controls</primary></indexterm>
+<indexterm><primary>printing systems</primary></indexterm>
+<indexterm><primary>DNS servers</primary></indexterm>
+<indexterm><primary>DHCP servers</primary></indexterm>
+ UNIX services can utilize LDAP directory information for authentication and access controls
+ through intermediate tools and utilities. The total environment that consists of the LDAP directory
+ and the middle-ware tools and utilities makes it possible for all user access to the UNIX platform
+ to be managed from a central environment and yet distributed to wherever the point of need may
+ be physically located. Applications that benefit from this infrastructure include: UNIX login
+ shells, mail and messaging systems, quota controls, printing systems, DNS servers, DHCP servers,
+ and also Samba.
+ </para>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>scalable</primary></indexterm>
+<indexterm><primary>SAM backend</primary></indexterm>
+<indexterm><primary>LDAP directory</primary></indexterm>
+<indexterm><primary>management costs</primary></indexterm>
+ Many sites are installing LDAP for the first time in order to provide a scalable passdb backend
+ for Samba. Others are faced with the need to adapt an existing LDAP directory to new uses such
+ as for the Samba SAM backend. Whatever your particular need and attraction to Samba may be,
+ decisions made in respect of the design of the LDAP directory structure and its implementation
+ are of a durable nature for the site. These have far-reaching implications that affect long-term
+ information systems management costs.
+ </para>
+
+ <para>
+<indexterm><primary>LDAP deployment</primary></indexterm>
+<indexterm><primary>Directory Information Tree</primary><see>DIT</see></indexterm>
+ Do not rush into an LDAP deployment. Take the time to understand how the design of the Directory
+ Information Tree (DIT) may impact current and future site needs, as well as the ability to meet
+ them. The way that Samba SAM information should be stored within the DIT varies from site to site
+ and with each implementation new experience is gained. It is well understood by LDAP veterans that
+ first implementations create awakening, second implementations of LDAP create fear, and
+ third-generation deployments bring peace and tranquility.
+ </para>
+
+ <sect3>
+ <title>Caution Regarding LDAP and Samba</title>
+
+ <para>
+<indexterm><primary>POSIX identity</primary></indexterm>
+<indexterm><primary>networking environment</primary></indexterm>
+<indexterm><primary>user accounts</primary></indexterm>
+<indexterm><primary>group accounts</primary></indexterm>
+<indexterm><primary>machine trust accounts</primary></indexterm>
+<indexterm><primary>interdomain trust accounts</primary></indexterm>
+<indexterm><primary>intermediate information</primary></indexterm>
+ Samba requires UNIX POSIX identity information as well as a place to store information that is
+ specific to Samba and the Windows networking environment. The most used information that must
+ be dealt with includes: user accounts, group accounts, machine trust accounts, interdomain
+ trust accounts, and intermediate information specific to Samba internals.
+ </para>
+
+ <para>
+<indexterm><primary>deployment guidelines</primary></indexterm>
+<indexterm><primary>HOWTO documents</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+ The example deployment guidelines in this book, as well as other books and HOWTO documents
+ available from the internet may not fit with established directory designs and implementations.
+ The existing DIT may not be able to accommodate the simple information layout proposed in common
+ sources. Additionally, you may find that the common scripts and tools that are used to provision
+ the LDAP directory for use with Samba may not suit your needs.
+ </para>
+
+ <para>
+<indexterm><primary>existing LDAP DIT</primary></indexterm>
+ It is not uncommon, for sites that have existing LDAP DITs to find necessity to generate a
+ set of site-specific scripts and utilities to make it possible to deploy Samba within the
+ scope of site operations. The way that user and group accounts are distributed throughout
+ the DIT may make this a challenging matter. The solution will, of course, be rewarding, but
+ the journey to it may be challenging. Take time to understand site needs and do not rush
+ into deployment.
+ </para>
+
+ <para>
+<indexterm><primary>scripts</primary></indexterm>
+<indexterm><primary>tools</primary></indexterm>
+ Above all, do not blindly use scripts and tools that are not suitable for your site. Check
+ and validate all scripts before you execute them to make sure that the existing infrastructure
+ will not be damaged by inadvertent use of an inappropriate tool.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2>
+ <title>LDAP Directories and Windows Computer Accounts</title>
+
+ <para>
+<indexterm><primary>turnkey solution</primary></indexterm>
+<indexterm><primary>LDAP.</primary></indexterm>
+<indexterm><primary>frustrating experience</primary></indexterm>
+ 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 a frustrating experience.
+ </para>
+
+ <para>
+<indexterm><primary>computer accounts</primary></indexterm>
+<indexterm><primary>machine accounts</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+ Computer (machine) accounts can be placed wherever you like in an LDAP directory subject
+ to some constraints that are described in this chapter.
+ </para>
+
+ <para>
+<indexterm><primary>POSIX</primary></indexterm>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>computer accounts</primary></indexterm>
+<indexterm><primary>machine accounts</primary></indexterm>
+<indexterm><primary>Windows NT4/200X</primary></indexterm>
+<indexterm><primary>user account</primary></indexterm>
+<indexterm><primary>trust accounts</primary></indexterm>
+ The POSIX and sambaSamAccount components of computer (machine) accounts are both used by Samba.
+ Thus, 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>
+<indexterm><primary>user</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>machine</primary></indexterm>
+<indexterm><primary>trust</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+ The need for Windows user, group, machine, trust, and other 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 or changed during the remaining life of the
+ Samba-3.x series.
+ </para>
+
+ <para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+ 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 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>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+<indexterm><primary>shadow</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+ 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 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>
+<indexterm><primary>PADL</primary></indexterm>
+<indexterm><primary>nss_ldap</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>documentation</primary></indexterm>
+ 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>
+<indexterm><primary>machine accounts</primary></indexterm>
+<indexterm><primary>management tools</primary></indexterm>
+Samba provides two tools for management of user and machine accounts:
+<command>smbpasswd</command> and <command>pdbedit</command>.
+</para>
+
+<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>password aging</primary></indexterm>
+<indexterm><primary>failed logins</primary></indexterm>
+The <command>pdbedit</command> can be used to manage account policies in addition to
+Samba user account information. The policy management capability is used to administer
+domain default settings for password aging and management controls to handle failed login
+attempts.
+</para>
+
+<para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>storage mechanism</primary></indexterm>
+<indexterm><primary>SambaSAMAccount</primary></indexterm>
+<indexterm><primary>net</primary></indexterm>
+Some people are confused when reference is made to <literal>smbpasswd</literal> because the
+name refers to a storage mechanism for SambaSAMAccount information, but it is also the name
+of a utility tool. That tool is destined to eventually be replaced by new functionality that
+is being added to the <command>net</command> toolset (see <link linkend="NetCommand">the Net Command</link>.
+</para>
+
+ <sect2>
+ <title>The <command>smbpasswd</command> Tool</title>
+
+ <para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+<indexterm><primary>yppasswd</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>storage methods</primary></indexterm>
+ The <command>smbpasswd</command> utility is similar to the <command>passwd</command>
+ and <command>yppasswd</command> programs. It maintains the two 32 byte password
+ fields in the passdb backend. This utility operates independently of the actual
+ account and password storage methods used (as specified by the <parameter>passdb
+ backend</parameter> in the &smb.conf; file.
+ </para>
+
+ <para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>client-server mode</primary></indexterm>
+ <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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>change passwords</primary></indexterm>
+ <command>smbpasswd</command> has the capability to change passwords on Windows NT
+ servers (this only works when the request is sent to the NT PDC if changing an NT
+ domain user's password).
+ </para>
+
+ <para>
+ <indexterm><primary>user management</primary></indexterm>
+ <indexterm><primary>user account</primary><secondary>Adding/Deleting</secondary></indexterm>
+ <command>smbpasswd</command> can be used to:
+ </para>
+
+ <itemizedlist>
+ <listitem><para><emphasis>add</emphasis> user or machine accounts.</para></listitem>
+ <listitem><para><emphasis>delete</emphasis> user or machine accounts.</para></listitem>
+ <listitem><para><emphasis>enable</emphasis> user or machine accounts.</para></listitem>
+ <listitem><para><emphasis>disable</emphasis> user or machine accounts.</para></listitem>
+ <listitem><para><emphasis>set to NULL</emphasis> user passwords.</para></listitem>
+ <listitem><para><emphasis>manage</emphasis> interdomain trust accounts.</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 the 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>
+<indexterm><primary>SMB password</primary></indexterm>
+ When invoked by an ordinary user, the command will allow only the user to change his or her own
+ SMB password.
+ </para>
+
+ <para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>SMB password</primary></indexterm>
+ When run by root, <command>smbpasswd</command> may take an optional argument specifying
+ the username 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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+<indexterm><primary>yppasswd</primary></indexterm>
+<indexterm><primary>change capabilities</primary></indexterm>
+ <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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+ For more details on using <command>smbpasswd</command>, refer to the man page (the
+ definitive reference).
+ </para>
+ </sect2>
+
+ <sect2 id="pdbeditthing">
+ <title>The <command>pdbedit</command> Tool</title>
+
+ <para>
+ <indexterm><primary>pdbedit</primary></indexterm>
+ <indexterm><primary>User Management</primary></indexterm>
+ <indexterm><primary>account policy</primary></indexterm>
+ <indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm>
+ <command>pdbedit</command> is a tool that can be used only by root. It is used to
+ manage the passdb backend, as well as domain-wide account policy settings. <command>pdbedit</command>
+ can be used to:
+ </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>
+ <listitem><para>migrate group accounts.</para></listitem>
+ <listitem><para>manage account policies.</para></listitem>
+ <listitem><para>manage domain access policy settings.</para></listitem>
+ </itemizedlist>
+
+ <para>
+ <indexterm><primary>Sarbanes-Oxley</primary></indexterm>
+ Under the terms of the Sarbanes-Oxley Act of 2002, American businesses and organizations are mandated to
+ implement a series of <literal>internal controls</literal> and procedures to communicate, store,
+ and protect financial data. The Sarbanes-Oxley Act has far reaching implications in respect of:
+ </para>
+
+ <orderedlist>
+ <listitem><para>Who has access to information systems that store financial data.</para></listitem>
+ <listitem><para>How personal and financial information is treated among employees and business
+ partners.</para></listitem>
+ <listitem><para>How security vulnerabilities are managed.</para></listitem>
+ <listitem><para>Security and patch level maintenance for all information systems.</para></listitem>
+ <listitem><para>How information systems changes are documented and tracked.</para></listitem>
+ <listitem><para>How information access controls are implemented and managed.</para></listitem>
+ <listitem><para>Auditability of all information systems in respect of change and security.</para></listitem>
+ <listitem><para>Disciplinary procedures and controls to ensure privacy.</para></listitem>
+ </orderedlist>
+
+ <para>
+ <indexterm><primary>accountability</primary></indexterm>
+ <indexterm><primary>compliance</primary></indexterm>
+ In short, the Sarbanes-Oxley Act of 2002 is an instrument that enforces accountability in respect of
+ business related information systems so as to ensure the compliance of all information systems that
+ are used to store personal information and particularly for financial records processing. Similar
+ accountabilities are being demanded around the world.
+ </para>
+
+ <para>
+ <indexterm><primary>laws</primary></indexterm>
+ <indexterm><primary>regulations</primary></indexterm>
+ <indexterm><primary>pdbedit</primary></indexterm>
+ <indexterm><primary>access controls</primary></indexterm>
+ <indexterm><primary>manage accounts</primary></indexterm>
+ The need to be familiar with the Samba tools and facilities that permit information systems operation
+ in compliance with government laws and regulations is clear to all. The <command>pdbedit</command> is
+ currently the only Samba tool that provides the capacity to manage account and systems access controls
+ and policies. During the remaining life-cycle of the Samba-3 series it is possible the new tools may
+ be implemented to aid in this important area.
+ </para>
+
+ <para>
+ Domain global policy controls available in Windows NT4 compared with Samba
+ is shown in <link linkend="policycontrols">NT4 Domain v's Samba Policy Controls</link>.
+ </para>
+
+ <table id="policycontrols">
+ <title>NT4 Domain v's Samba Policy Controls</title>
+ <tgroup cols="5">
+ <colspec align="left" colwidth="2*"/>
+ <colspec align="left" colwidth="2*"/>
+ <colspec align="center" colwidth="1*"/>
+ <colspec align="center" colwidth="1*"/>
+ <colspec align="center" colwidth="1*"/>
+ <thead>
+ <row>
+ <entry><para>NT4 policy Name</para></entry>
+ <entry><para>Samba Policy Name</para></entry>
+ <entry><para>NT4 Range</para></entry>
+ <entry><para>Samba Range</para></entry>
+ <entry><para>Samba Default</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Maximum Password Age</para></entry>
+ <entry><para>maximum password age</para></entry>
+ <entry><para>0 - 999 (days)</para></entry>
+ <entry><para>0 - 4294967295 (sec)</para></entry>
+ <entry><para>4294967295</para></entry>
+ </row>
+ <row>
+ <entry><para>Minimum Password Age</para></entry>
+ <entry><para>minimum password age</para></entry>
+ <entry><para>0 - 999 (days)</para></entry>
+ <entry><para>0 - 4294967295 (sec)</para></entry>
+ <entry><para>0</para></entry>
+ </row>
+ <row>
+ <entry><para>Mimimum Password Length</para></entry>
+ <entry><para>min password length</para></entry>
+ <entry><para>1 - 14 (Chars)</para></entry>
+ <entry><para>0 - 4294967295 (Chars)</para></entry>
+ <entry><para>5</para></entry>
+ </row>
+ <row>
+ <entry><para>Password Uniqueness</para></entry>
+ <entry><para>password history</para></entry>
+ <entry><para>0 - 23 (#)</para></entry>
+ <entry><para>0 - 4294967295 (#)</para></entry>
+ <entry><para>0</para></entry>
+ </row>
+ <row>
+ <entry><para>Account Lockout - Reset count after</para></entry>
+ <entry><para>reset count minutes</para></entry>
+ <entry><para>1 - 99998 (min)</para></entry>
+ <entry><para>0 - 4294967295 (min)</para></entry>
+ <entry><para>30</para></entry>
+ </row>
+ <row>
+ <entry><para>Lockout after bad logon attempts</para></entry>
+ <entry><para>bad lockout attempt</para></entry>
+ <entry><para>0 - 998 (#)</para></entry>
+ <entry><para>0 - 4294967295 (#)</para></entry>
+ <entry><para>0</para></entry>
+ </row>
+ <row>
+ <entry><para>*** Not Known ***</para></entry>
+ <entry><para>disconnect time</para></entry>
+ <entry><para>TBA</para></entry>
+ <entry><para>0 - 4294967295</para></entry>
+ <entry><para>0</para></entry>
+ </row>
+ <row>
+ <entry><para>Lockout Duration</para></entry>
+ <entry><para>lockout duration</para></entry>
+ <entry><para>1 - 99998 (min)</para></entry>
+ <entry><para>0 - 4294967295 (min)</para></entry>
+ <entry><para>30</para></entry>
+ </row>
+ <row>
+ <entry><para>Users must log on in order to change password</para></entry>
+ <entry><para>user must logon to change password</para></entry>
+ <entry><para>0/1</para></entry>
+ <entry><para>0 - 4294967295</para></entry>
+ <entry><para>0</para></entry>
+ </row>
+ <row>
+ <entry><para>*** Registry Setting ***</para></entry>
+ <entry><para>refuse machine password change</para></entry>
+ <entry><para>0/1</para></entry>
+ <entry><para>0 - 4294967295</para></entry>
+ <entry><para>0</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>policy settings</primary></indexterm>
+<indexterm><primary>account security</primary></indexterm>
+<indexterm><primary>smbpasswd</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 superset of them.
+ </para>
+
+ <para>
+ <indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>account import/export</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+ One particularly important purpose of the <command>pdbedit</command> is to allow
+ the import/export of account information from one passdb backend to another.
+ </para>
+
+ <sect3>
+ <title>User Account Management</title>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>system accounts</primary></indexterm>
+<indexterm><primary>user account</primary></indexterm>
+<indexterm><primary>domain user manager</primary></indexterm>
+<indexterm><primary>add user script</primary></indexterm>
+<indexterm><primary>interface scripts</primary></indexterm>
+ The <command>pdbedit</command> tool, like the <command>smbpasswd</command> tool, requires
+ that a POSIX user account already exists in the UNIX/Linux system accounts database (backend).
+ Neither tool will call out to the operating system to create a user account because this is
+ considered to be the responsibility of the system administrator. When the Windows NT4 domain
+ user manager is used to add an account, Samba will implement the <literal>add user script</literal>
+ (as well as the other interface scripts) to ensure that user, group and machine accounts are
+ correctly created and changed. The use of the <command>pdbedit</command> tool does not
+ make use of these interface scripts.
+ </para>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>POSIX account</primary></indexterm>
+ Before attempting to use the <command>pdbedit</command> tool to manage user and machine
+ accounts, make certain that a system (POSIX) account has already been created.
+ </para>
+
+ <sect4>
+ <title>Listing User and Machine Accounts</title>
+
+ <para>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>password backend</primary></indexterm>
+ The following is an example of the user account information that is stored in
+ a tdbsam password backend. This listing was produced by running:
+<screen>
+&prompt;<userinput>pdbedit -Lv met</userinput>
+UNIX username: met
+NT username: met
+Account Flags: [U ]
+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>
+
+ <para>
+<indexterm><primary>smbpasswd format</primary></indexterm>
+ Accounts can also be listed in the older <literal>smbpasswd</literal> format:
+<screen>
+&rootprompt;<userinput>pdbedit -Lw</userinput>
+root:0:84B0D8E14D158FF8417EAF50CFAC29C3:
+ AF6DD3FD4E2EA8BDE1695A3F05EFBF52:[U ]:LCT-42681AB8:
+jht:1000:6BBC4159020A52741486235A2333E4D2:
+ CC099521AD554A3C3CF2556274DBCFBC:[U ]:LCT-40D75B5B:
+rcg:1002:E95D4331A6F23AF8AAD3B435B51404EE:
+ BB0F2C39B04CA6100F0E535DF8314B43:[U ]:LCT-40D7C5A3:
+afw:1003:1AAFA7F9F6DC1DEAAAD3B435B51404EE:
+ CE92C2F9471594CDC4E7860CA6BC62DB:[T ]:LCT-40DA501F:
+met:1004:A2848CB7E076B435AAD3B435B51404EE:
+ F25F5D3405085C555236B80B7B22C0D2:[U ]:LCT-4244FAB8:
+aurora$:1005:060DE593EA638B8ACC4A19F14D2FF2BB:
+ 060DE593EA638B8ACC4A19F14D2FF2BB:[W ]:LCT-4173E5CC:
+temptation$:1006:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
+ A96703C014E404E33D4049F706C45EE9:[W ]:LCT-42BF0C57:
+vaioboss$:1001:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
+ 88A30A095160072784C88F811E89F98A:[W ]:LCT-41C3878D:
+frodo$:1008:15891DC6B843ECA41249940C814E316B:
+ B68EADCCD18E17503D3DAD3E6B0B9A75:[W ]:LCT-42B7979F:
+marvel$:1011:BF709959C3C94E0B3958B7B84A3BB6F3:
+ C610EFE9A385A3E8AA46ADFD576E6881:[W ]:LCT-40F07A4
+</screen>
+<indexterm><primary>login id</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>LanManger password</primary></indexterm>
+<indexterm><primary>NT password</primary></indexterm>
+<indexterm><primary>Account Flags</primary></indexterm>
+<indexterm><primary>LCT</primary><see>last change time</see></indexterm>
+ The account information that was returned by this command in order from left to right
+ consists of the following colon separated data:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>Login ID.</para></listitem>
+ <listitem><para>UNIX UID.</para></listitem>
+ <listitem>
+ <para>Microsoft LanManager password hash (password converted to upper-case then hashed.</para>
+ </listitem>
+ <listitem><para>Microsoft NT password hash (hash of the case-preserved password).</para></listitem>
+ <listitem><para>Samba SAM Account Flags.</para></listitem>
+ <listitem><para>The LCT data (password last change time).</para></listitem>
+ </itemizedlist>
+
+ <para>
+<indexterm><primary>Account Flags</primary></indexterm>
+<indexterm><primary>pdbedit</primary></indexterm>
+ The Account Flags parameters are documented in the <command>pdbedit</command> man page, and are
+ briefly documented in <link linkend="TOSHARG-acctflags">the Account Flags Management section</link>.
+ </para>
+
+ <para>
+<indexterm><primary>last change time</primary></indexterm>
+ The LCT data consists of 8 hexadecimal characters representing the time since January 1, 1970, of
+ the time when the password was last changed.
+ </para>
+
+ </sect4>
+
+ <sect4>
+ <title>Adding User Accounts</title>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>add a user account</primary></indexterm>
+<indexterm><primary>standalone server</primary></indexterm>
+<indexterm><primary>domain</primary></indexterm>
+<indexterm><primary>SambaSAMAccount</primary></indexterm>
+ The <command>pdbedit</command> can be used to add a user account to a standalone server
+ or to a domain. In the example shown here the account for the user <literal>vlaan</literal>
+ has been created before attempting to add the SambaSAMAccount.
+<screen>
+&rootprompt; pdbedit -a vlaan
+new password: secretpw
+retype new password: secretpw
+Unix username: vlaan
+NT username: vlaan
+Account Flags: [U ]
+User SID: S-1-5-21-726309263-4128913605-1168186429-3014
+Primary Group SID: S-1-5-21-726309263-4128913605-1168186429-513
+Full Name: Victor Laan
+Home Directory: \\frodo\vlaan
+HomeDir Drive: H:
+Logon Script: scripts\logon.bat
+Profile Path: \\frodo\profiles\vlaan
+Domain: &example.workgroup;
+Account desc: Guest User
+Workstations:
+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: Wed, 29 Jun 2005 19:35:12 GMT
+Password can change: Wed, 29 Jun 2005 19:35:12 GMT
+Password must change: Mon, 18 Jan 2038 20:14:07 GMT
+Last bad password : 0
+Bad password count : 0
+Logon hours : FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
+</screen>
+ </para>
+
+ </sect4>
+
+ <sect4>
+ <title>Deleting Accounts</title>
+
+ <para>
+<indexterm><primary>account deleted</primary></indexterm>
+<indexterm><primary>SambaSAMAccount</primary></indexterm>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+ An account can be deleted from the SambaSAMAccount database
+<screen>
+&rootprompt; pdbedit -x vlaan
+</screen>
+ The account is removed without further screen output. The account is removed only from the
+ SambaSAMAccount (passdb backend) database, it is not removed from the UNIX account backend.
+ </para>
+
+ <para>
+<indexterm><primary>delete user script</primary></indexterm>
+<indexterm><primary>pdbedit</primary></indexterm>
+ The use of the NT4 domain user manager to delete an account will trigger the <parameter>delete user
+ script</parameter>, but not the <command>pdbedit</command> tool.
+ </para>
+
+ </sect4>
+
+ <sect4>
+ <title>Changing User Accounts</title>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+ Refer to the <command>pdbedit</command> man page for a full synopsis of all operations
+ that are available with this tool.
+ </para>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+ An example of a simple change in the user account information is the change of the full name
+ information shown here:
+<screen>
+&rootprompt; pdbedit -r --fullname="Victor Aluicious Laan" vlaan
+...
+Primary Group SID: S-1-5-21-726309263-4128913605-1168186429-513
+Full Name: Victor Aluicious Laan
+Home Directory: \\frodo\vlaan
+...
+</screen>
+ </para>
+
+ <para>
+<indexterm><primary>grace time</primary></indexterm>
+<indexterm><primary>password expired</primary></indexterm>
+<indexterm><primary>expired password</primary></indexterm>
+ Let us assume for a moment that a user's password has expired and the user is unable to
+ change the password at this time. It may be necessary to give the user additional grace time
+ so that it is possible to continue to work with the account and the original password. This
+ demonstrates how the password expiration settings may be updated
+<screen>
+&rootprompt; pdbedit -Lv vlaan
+...
+Password last set: Sun, 09 Sep 2001 22:21:40 GMT
+Password can change: Thu, 03 Jan 2002 15:08:35 GMT
+Password must change: Thu, 03 Jan 2002 15:08:35 GMT
+Last bad password : Thu, 03 Jan 2002 15:08:35 GMT
+Bad password count : 2
+...
+</screen>
+<indexterm><primary>bad logon attempts</primary></indexterm>
+<indexterm><primary>lock the account</primary></indexterm>
+ The user has recorded 2 bad logon attempts and the next will lock the account, but the
+ password is also expired. Here is how this account can be reset:
+<screen>
+&rootprompt; pdbedit -z vlaan
+...
+Password last set: Sun, 09 Sep 2001 22:21:40 GMT
+Password can change: Thu, 03 Jan 2002 15:08:35 GMT
+Password must change: Thu, 03 Jan 2002 15:08:35 GMT
+Last bad password : 0
+Bad password count : 0
+...
+</screen>
+ The <literal>Password must change:</literal> parameter can be reset like this:
+<screen>
+&rootprompt; pdbedit --pwd-must-change-time=1200000000 vlaan
+...
+Password last set: Sun, 09 Sep 2001 22:21:40 GMT
+Password can change: Thu, 03 Jan 2002 15:08:35 GMT
+Password must change: Thu, 10 Jan 2008 14:20:00 GMT
+...
+</screen>
+ Another way to use this tools is to set the date like this:
+<screen>
+&rootprompt; pdbedit --pwd-must-change-time="2010-01-01" \
+ --time-format="%Y-%m-%d" vlaan
+...
+Password last set: Sun, 09 Sep 2001 22:21:40 GMT
+Password can change: Thu, 03 Jan 2002 15:08:35 GMT
+Password must change: Fri, 01 Jan 2010 00:00:00 GMT
+...
+</screen>
+<indexterm><primary>strptime</primary></indexterm>
+<indexterm><primary>time format</primary></indexterm>
+ Refer to the strptime man page for specific time format information.
+ </para>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>SambaSAMAccount</primary></indexterm>
+ Please refer to the pdbedit man page for further information relating to SambaSAMAccount
+ management.
+ </para>
+
+ <sect5 id="TOSHARG-acctflags">
+ <title>Account Flags Management</title>
+
+ <para>
+<indexterm><primary>Samba SAM account flags</primary></indexterm>
+<indexterm><primary>account control block</primary><see>ACB</see></indexterm>
+<indexterm><primary>account encode_bits</primary></indexterm>
+<indexterm><primary>account control flags</primary></indexterm>
+ The Samba SAM account flags are properly called the ACB (account control block) within
+ the Samba source code. In some parts of the Samba source code they are referred to as the
+ account encode_bits, and also as the account control flags.
+ </para>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>user account</primary></indexterm>
+<indexterm><primary>machine account</primary></indexterm>
+<indexterm><primary>trust account</primary></indexterm>
+<indexterm><primary>damaged data</primary></indexterm>
+ The manual adjustment of user, machine (workstation or server) or an inter-domain trust
+ account account flgas should not be necessary under normal conditions of use of Samba. On the other hand,
+ where this information becomes corrupted for some reason, the ability to correct the damaged data is certainly
+ useful. The tool of choice by which such correction can be affected is the <command>pdbedit</command> utility.
+ </para>
+
+ <para>
+<indexterm><primary>account flags</primary></indexterm>
+<indexterm><primary>LDAP directory</primary></indexterm>
+ There have been a few requests for information regarding the account flags from developers
+ who are creating their own Samba management tools. An example of a need for information regarding
+ the proper management of the account flags is evident when developing scripts that will be used
+ to manage an LDAP directory.
+ </para>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>account flag order</primary></indexterm>
+ The account flag field can contain up to 16 characters. Presently, only 11 are in use.
+ These are listed in <link linkend="accountflags">Samba SAM Account Control Block Flags</link>.
+ The order in which the flags are specified to the <command>pdbedit</command> command is not important.
+ In fact, they can be set without problem in any order in the SambaAcctFlags record in the LDAP directory.
+ </para>
+
+ <table frame="all" id="accountflags">
+ <title>Samba SAM Account Control Block Flags</title>
+ <tgroup cols="2" align="center">
+ <thead>
+ <row><entry align="center">Flag</entry><entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry align="center">D</entry>
+ <entry align="left">Account is disabled.</entry>
+ </row>
+ <row>
+ <entry align="center">H</entry>
+ <entry align="left">A home directory is required.</entry>
+ </row>
+ <row>
+ <entry align="center">I</entry>
+ <entry align="left">An inter-domain trust account.</entry>
+ </row>
+ <row>
+ <entry align="center">L</entry>
+ <entry align="left">Account has been auto-locked.</entry>
+ </row>
+ <row>
+ <entry align="center">M</entry>
+ <entry align="left">An MNS (Microsoft network service) logon account.</entry>
+ </row>
+ <row>
+ <entry align="center">N</entry>
+ <entry align="left">Password not required.</entry>
+ </row>
+ <row>
+ <entry align="center">S</entry>
+ <entry align="left">A server trust account.</entry>
+ </row>
+ <row>
+ <entry align="center">T</entry>
+ <entry align="left">Temporary duplicate account entry.</entry>
+ </row>
+ <row>
+ <entry align="center">U</entry>
+ <entry align="left">A normal user account.</entry>
+ </row>
+ <row>
+ <entry align="center">W</entry>
+ <entry align="left">A workstation trust account.</entry>
+ </row>
+ <row>
+ <entry align="center">X</entry>
+ <entry align="left">Password does not expire.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>account control flags</primary></indexterm>
+ An example of use of the <command>pdbedit</command> utility to set the account control flags
+ is shown here:
+<screen>
+&rootprompt; pdbedit -r -c "[DLX]" jht
+Unix username: jht
+NT username: jht
+Account Flags: [DHULX ]
+User SID: S-1-5-21-729263-4123605-1186429-3000
+Primary Group SID: S-1-5-21-729263-4123605-1186429-513
+Full Name: John H Terpstra,Utah Office
+Home Directory: \\aurora\jht
+HomeDir Drive: H:
+Logon Script: scripts\logon.bat
+Profile Path: \\aurora\profiles\jht
+Domain: MIDEARTH
+Account desc: BluntObject
+Workstations:
+Logon time: 0
+Logoff time: Mon, 18 Jan 2038 20:14:07 GMT
+Kickoff time: 0
+Password last set: Sun, 03 Jul 2005 23:19:18 GMT
+Password can change: Sun, 03 Jul 2005 23:19:18 GMT
+Password must change: Mon, 18 Jan 2038 20:14:07 GMT
+Last bad password : 0
+Bad password count : 0
+Logon hours : FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
+</screen>
+<indexterm><primary>default settings</primary></indexterm>
+ The flags can be reset to the default settings by executing:
+<screen>
+&rootprompt; pdbedit -r -c "[]" jht
+Unix username: jht
+NT username: jht
+Account Flags: [U ]
+User SID: S-1-5-21-729263-4123605-1186429-3000
+Primary Group SID: S-1-5-21-729263-4123605-1186429-513
+Full Name: John H Terpstra,Utah Office
+Home Directory: \\aurora\jht
+HomeDir Drive: H:
+Logon Script: scripts\logon.bat
+Profile Path: \\aurora\profiles\jht
+Domain: MIDEARTH
+Account desc: BluntObject
+Workstations:
+Logon time: 0
+Logoff time: Mon, 18 Jan 2038 20:14:07 GMT
+Kickoff time: 0
+Password last set: Sun, 03 Jul 2005 23:19:18 GMT
+Password can change: Sun, 03 Jul 2005 23:19:18 GMT
+Password must change: Mon, 18 Jan 2038 20:14:07 GMT
+Last bad password : 0
+Bad password count : 0
+Logon hours : FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
+</screen>
+ </para>
+
+ </sect5>
+
+ </sect4>
+
+ <sect4>
+ <title>Domain Account Policy Managment</title>
+
+ <para>
+<indexterm><primary>domain account access policies</primary></indexterm>
+<indexterm><primary>access policies</primary></indexterm>
+ To view the domain account access policies that may be configured execute:
+<screen>
+&rootprompt; pdbedit -P ?
+No account policy by that name
+Account policy names are :
+min password length
+password history
+user must logon to change password
+maximum password age
+minimum password age
+lockout duration
+reset count minutes
+bad lockout attempt
+disconnect time
+refuse machine password change
+</screen>
+ </para>
+
+ <para>
+ Commands will be executed to establish controls for our domain as follows:
+ </para>
+
+ <orderedlist>
+ <listitem><para>min password length = 8 characters.</para></listitem>
+ <listitem><para>password history = last 4 passwords.</para></listitem>
+ <listitem><para>maximum password age = 90 days.</para></listitem>
+ <listitem><para>minimum password age = 7 days.</para></listitem>
+ <listitem><para>bad lockout attempt = 8 bad logon attempts.</para></listitem>
+ <listitem><para>lockout duration = forever, account must be manually reenabled.</para></listitem>
+ </orderedlist>
+
+ <para>
+ The following command execution will achieve these settings:
+<screen>
+&rootprompt; pdbedit -P "min password length" -C 8
+account policy value for min password length was 5
+account policy value for min password length is now 8
+&rootprompt; pdbedit -P "password history" -C 4
+account policy value for password history was 0
+account policy value for password history is now 4
+&rootprompt; pdbedit -P "maximum password age" -C 7776000
+account policy value for maximum password age was 4294967295
+account policy value for maximum password age is now 7776000
+&rootprompt; pdbedit -P "minimum password age" -C 7
+account policy value for minimum password age was 0
+account policy value for minimum password age is now 7
+&rootprompt; pdbedit -P "bad lockout attempt" -C 8
+account policy value for bad lockout attempt was 0
+account policy value for bad lockout attempt is now 8
+&rootprompt; pdbedit -P "lockout duration" -C -1
+account policy value for lockout duration was 30
+account policy value for lockout duration is now 4294967295
+</screen>
+ </para>
+
+<note><para>
+To set the maximum (infinite) lockout time use the value of -1.
+</para></note>
+
+<warning><para>
+Account policies must be set individually on each PDC and BDC. At this time (Samba 3.0.11 to Samba 3.0.14a)
+account policies are not replicated automatically. This may be fixed before Samba 3.0.20 ships or some
+time there after. Please check the WHATSNEW.txt file in the Samba-3 tarball for specific update notiations
+regarding this facility.
+</para></warning>
+
+ </sect4>
+
+ </sect3>
+
+ <sect3>
+ <title>Account Import/Export</title>
+
+ <para>
+ <indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>account import/export</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+ The <command>pdbedit</command> tool allows import/export of authentication (account)
+ databases from one backend to another. For example, to import/export accounts from an
+ old <filename>smbpasswd</filename> database to a <parameter>tdbsam</parameter>
+ backend:
+ </para>
+
+ <procedure>
+ <step><para>
+<indexterm><primary>pdbedit</primary></indexterm>
+<screen>
+&rootprompt;<userinput>pdbedit -i smbpasswd -e tdbsam</userinput>
+</screen>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+ Replace the <parameter>smbpasswd</parameter> with <parameter>tdbsam</parameter> in the
+ <parameter>passdb backend</parameter> configuration in &smb.conf;.
+ </para></step>
+ </procedure>
+
+ </sect3>
+ </sect2>
+</sect1>
+
+<sect1>
+<title>Password Backends</title>
+
+<para>
+<indexterm><primary>account database</primary></indexterm>
+<indexterm><primary>SMB/CIFS server</primary></indexterm>
+Samba offers flexibility in backend account database design. The flexibility is immediately obvious as one
+begins to explore this capability. Recent changes to Samba (since 3.0.23) have removed the mulitple backend
+feature in order to simplify problems that broke some installations. This removal has made the internal
+operation of Samba-3 more consistent and predictable.
+</para>
+
+<para>
+<indexterm><primary>multiple backends</primary></indexterm>
+<indexterm><primary>tdbsam databases</primary></indexterm>
+Beginning with Samba 3.0.23 it is no longer possible to specify use of mulitple passdb backends. Earlier
+versions of Samba-3 made it possible to specify multiple password backends, and even multiple
+backends of the same type. The multiple passdb backend capability caused many problems with name to SID and
+SID to name ID resolution. The Samba team wrestled with the challenges and decided that this feature needed
+to be removed.
+</para>
+
+ <sect2>
+ <title>Plaintext</title>
+
+ <para>
+<indexterm><primary>user database</primary></indexterm>
+<indexterm><primary>/etc/samba/smbpasswd</primary></indexterm>
+<indexterm><primary>/etc/smbpasswd</primary></indexterm>
+<indexterm><primary>password encryption</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+ 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.
+ On most Linux systems, for example, all user and group resolution is done via PAM.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>smbpasswd: Encrypted Password Database</title>
+
+ <para>
+ <indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm>
+<indexterm><primary>user account</primary></indexterm>
+<indexterm><primary>LM/NT password hashes</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></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>
+<indexterm><primary>lookups</primary></indexterm>
+ The first problem is that all lookups must be performed sequentially. Given that
+ there are approximately two lookups per domain logon (one during intial logon validation
+ and one for a session connection setup, 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 that used in databases.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>replicate</primary></indexterm>
+<indexterm><primary>rsync</primary></indexterm>
+<indexterm><primary>ssh</primary></indexterm>
+<indexterm><primary>custom scripts</primary></indexterm>
+ The second problem is that administrators who desire to replicate an smbpasswd file
+ to more than one Samba server are left to use external tools such as
+ <command>rsync(1)</command> and <command>ssh(1)</command> and write custom,
+ in-house scripts.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>home directory</primary></indexterm>
+<indexterm><primary>password expiration</primary></indexterm>
+<indexterm><primary>relative identifier</primary></indexterm>
+<indexterm><primary>relative identifier</primary><see>RID</see></indexterm>
+ 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>
+<indexterm><primary>user attributes</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>API</primary></indexterm>
+<indexterm><primary>samdb interface</primary></indexterm>
+ As a result of these deficiencies, a more robust means of storing user attributes
+ used by smbd was developed. The API that 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 source code trees).
+ </para>
+
+ <para>
+<indexterm><primary>passdb backends</primary></indexterm>
+<indexterm><primary>smbpasswd plaintext database</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+<indexterm><primary>enterprise</primary></indexterm>
+ Samba provides an enhanced set of passdb backends that overcome the deficiencies
+ of the smbpasswd plaintext database. These are tdbsam and ldapsam.
+ 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>
+<indexterm><primary>trivial database</primary><see>TDB</see></indexterm>
+<indexterm><primary>machine account</primary></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>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>scalability</primary></indexterm>
+ 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>
+<indexterm><primary>250-user limit</primary></indexterm>
+<indexterm><primary>performance-based</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+ 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>
+
+ <para>
+<indexterm><primary>4,500 user accounts</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>SambaSAMAccount</primary></indexterm>
+ There are sites that have thousands of users and yet require only one server.
+ One site recently reported having 4,500 user accounts on one UNIX system and
+ reported excellent performance with the <literal>tdbsam</literal> passdb backend.
+ The limitation of where the <literal>tdbsam</literal> passdb backend can be used
+ is not one pertaining to a limitation in the TDB storage system, it is based
+ only on the need for a reliable distribution mechanism for the SambaSAMAccount
+ backend.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>ldapsam</title>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+ <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
+ a Windows 200x Active Directory server.</para></listitem>
+ <listitem><para>A means of replacing /etc/passwd.</para></listitem>
+ </itemizedlist>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>LGPL</primary></indexterm>
+ 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 in <ulink url="http://safari.oreilly.com/?XmlId=1-56592-491-6">
+ <emphasis>LDAP, System Administration</emphasis> by Gerald Carter, Chapter 6, Replacing NIS"</ulink>.
+ </para>
+
+ <para>
+<indexterm><primary>LDAP directory</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>directory server</primary></indexterm>
+ 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://www.sun.com/software/products/directory_srvr_ee/index.xml">
+ Sun One Directory Server</ulink></para></listitem>
+ <listitem><para><ulink url="http://www.novell.com/products/edirectory/">Novell eDirectory</ulink></para></listitem>
+ <listitem><para><ulink url="http://www-306.ibm.com/software/tivoli/products/directory-server/">IBM
+ Tivoli Directory Server</ulink></para></listitem>
+ <listitem><para><ulink url="http://www.redhat.com/software/rha/directory/">Red Hat Directory
+ Server</ulink></para></listitem>
+ <listitem><para><ulink url="http://www.linuxsecurity.com/content/view/119229">Fedora Directory
+ Server</ulink></para></listitem>
+ </itemizedlist>
+
+ <para>
+ Two additional Samba resources that may prove to be helpful are:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+<indexterm><primary>Samba-PDC-LDAP-HOWTO</primary></indexterm>
+ 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>
+<indexterm><primary>IDEALX</primary></indexterm>
+<indexterm><primary>NT migration scripts</primary></indexterm>
+<indexterm><primary>smbldap-tools</primary></indexterm>
+ The NT migration scripts from <ulink url="http://samba.idealx.org/">IDEALX</ulink> that are
+ geared to manage users and groups in such a Samba-LDAP domain controller configuration.
+ Idealx also produced the smbldap-tools and the Interactive Console Management tool.
+ </para></listitem>
+ </itemizedlist>
+
+ <sect3>
+ <title>Supported LDAP Servers</title>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>Netscape's Directory Server</primary></indexterm>
+ The LDAP ldapsam code was developed and tested using the OpenLDAP 2.x 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>.
+ </para>
+
+ <para>
+ Samba is capable of working with any standards-compliant LDAP server.
+ </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.x in the
+ <filename>examples/LDAP/samba.schema</filename> directory of the source code distribution
+ tarball. The schema entry for the sambaSamAccount ObjectClass is shown here:
+<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>
+<indexterm><primary>samba.schema</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>OID</primary></indexterm>
+ 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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>AUXILIARY</primary></indexterm>
+<indexterm><primary>ObjectClass</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>RFC 2307.</primary></indexterm>
+ 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 an
+ <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 RFC 2307. This is by design.
+ </para>
+
+ <para>
+<indexterm><primary>account information</primary></indexterm>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>posixAccount</primary></indexterm>
+<indexterm><primary>ObjectClasses</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>getpwnam</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>NIS</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+ In order to store all user account information (UNIX and Samba) in the directory,
+ it is necessary to use the sambaSamAccount and posixAccount ObjectClasses in
+ combination. However, <command>smbd</command> will still obtain the user's UNIX account
+ information via the standard C library calls, such as getpwnam().
+ 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>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>slapd</primary></indexterm>
+<indexterm><primary>samba.schema</primary></indexterm>
+ 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.
+<screen>
+&rootprompt;<userinput>cp samba.schema /etc/openldap/schema/</userinput>
+</screen>
+ </para>
+
+ <para>
+<indexterm><primary>samba.schema</primary></indexterm>
+<indexterm><primary>slapd.conf</primary></indexterm>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>cosine.schema</primary></indexterm>
+<indexterm><primary>uid</primary></indexterm>
+<indexterm><primary>inetorgperson.schema</primary></indexterm>
+<indexterm><primary>displayName</primary></indexterm>
+<indexterm><primary>attribute</primary></indexterm>
+ 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.
+<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>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>posixAccount</primary></indexterm>
+<indexterm><primary>posixGroup</primary></indexterm>
+<indexterm><primary>ObjectClasses</primary></indexterm>
+ 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:
+<screen>
+&rootprompt;./sbin/slapindex -f slapd.conf
+</screen>
+ </para>
+
+ <para>
+ Remember to restart slapd after making these changes:
+<screen>
+&rootprompt;<userinput>/etc/init.d/slapd restart</userinput>
+</screen>
+ </para>
+
+ </sect3>
+
+ <sect3>
+ <title>Initialize the LDAP Database</title>
+
+ <para>
+<indexterm><primary>LDAP database</primary></indexterm>
+<indexterm><primary>account containers</primary></indexterm>
+<indexterm><primary>LDIF file</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+ 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):
+<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 OU
+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>
+ </para>
+
+ <para>
+<indexterm><primary>userPassword</primary></indexterm>
+<indexterm><primary>slappasswd</primary></indexterm>
+ The userPassword shown above should be generated using <command>slappasswd</command>.
+ </para>
+
+ <para>
+<indexterm><primary>LDIF</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+ The following command will then load the contents of the LDIF file into the LDAP
+ database.
+<indexterm><primary>slapadd</primary></indexterm>
+<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>
+<indexterm><primary>secrets.tdb</primary></indexterm>
+ Before Samba can access the LDAP server, you need to store the LDAP admin password
+ in the Samba-3 <filename>secrets.tdb</filename> database by:
+<indexterm><primary>smbpasswd</primary></indexterm>
+<screen>
+&rootprompt;<userinput>smbpasswd -w <replaceable>secret</replaceable></userinput>
+</screen>
+ </para></note>
+
+ </sect3>
+
+ <sect3>
+ <title>Configuring Samba</title>
+
+ <para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+ 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. The
+ best method to verify that Samba was built with LDAP support is:
+<screen>
+&rootprompt; smbd -b | grep LDAP
+ HAVE_LDAP_H
+ HAVE_LDAP
+ HAVE_LDAP_DOMAIN2HOSTLIST
+ HAVE_LDAP_INIT
+ HAVE_LDAP_INITIALIZE
+ HAVE_LDAP_SET_REBIND_PROC
+ HAVE_LIBLDAP
+ LDAP_SET_REBIND_PROC_ARGS
+</screen>
+ If the build of the <command>smbd</command> command you are using does not produce output
+ that includes <literal>HAVE_LDAP_H</literal> it is necessary to discover why the LDAP headers
+ and libraries were not found during compilation.
+ </para>
+
+ <para>LDAP-related smb.conf options include these:
+ <smbconfblock>
+ <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"/>
+ <smbconfoption name="ldap replication sleep"/>
+ <smbconfoption name="ldap timeout"/>
+ <smbconfoption name="ldap page size"/>
+ </smbconfblock>
+ </para>
+
+ <para>
+ These are described in the &smb.conf; man page and so are not repeated here. However, an example
+ for use with an LDAP directory is shown in <link linkend="confldapex">the Configuration with LDAP.</link>
+ </para>
+
+<example id="confldapex">
+<title>Configuration with LDAP</title>
+<smbconfblock>
+<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 used when binding to the LDAP servers.</smbconfcomment>
+<smbconfcomment>The password for this DN is not stored in smb.conf</smbconfcomment>
+<smbconfcomment>Set it using 'smbpasswd -w secret' to store the</smbconfcomment>
+<smbconfcomment>passphrase in the secrets.tdb file.</smbconfcomment>
+<smbconfcomment>If the "ldap admin dn" value changes, it must be reset.</smbconfcomment>
+<smbconfoption name="ldap admin dn">"cn=Manager,dc=quenya,dc=org"</smbconfoption>
+
+<smbconfcomment>SSL directory connections can be configured by:</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 are 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>
+</smbconfblock>
+</example>
+
+ </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>
+ Because user accounts are managed through the sambaSamAccount ObjectClass, you should
+ modify your existing administration tools to deal with sambaSamAccount attributes.
+ </para>
+
+ <para>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>/etc/openldap/sldap.conf</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+ Machine accounts are managed with the sambaSamAccount ObjectClass, just
+ like user 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>
+<indexterm><primary>POSIX</primary></indexterm>
+<indexterm><primary>posixGroup</primary></indexterm>
+<indexterm><primary>Domain Groups</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+ 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>
+<indexterm><primary>sambaSAMAccount</primary></indexterm>
+ 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
+<indexterm><primary>SambaNTPassword</primary></indexterm>
+ 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>
+<indexterm><primary>clear-text</primary></indexterm>
+<indexterm><primary>impersonate</primary></indexterm>
+<indexterm><primary>LM/NT password hashes</primary></indexterm>
+ 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 <link linkend="passdb">the
+ Account Information Database section</link>.
+ </para>
+
+ <para>
+<indexterm><primary>encrypted session</primary></indexterm>
+<indexterm><primary>StartTLS</primary></indexterm>
+<indexterm><primary>LDAPS</primary></indexterm>
+<indexterm><primary>secure communications</primary></indexterm>
+ 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 encouraged to use secure communications protocols
+ (so do not set <smbconfoption name="ldap ssl">off</smbconfoption>).
+ </para>
+
+ <para>
+<indexterm><primary>LDAPS</primary></indexterm>
+<indexterm><primary>StartTLS</primary></indexterm>
+<indexterm><primary>LDAPv3</primary></indexterm>
+ 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>
+<indexterm><primary>harvesting password hashes</primary></indexterm>
+<indexterm><primary>ACL</primary></indexterm>
+<indexterm><primary>slapd.conf</primary></indexterm>
+ 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>
+
+ <table frame="all" id="attribobjclPartA">
+ <title>Attributes in the sambaSamAccount ObjectClass (LDAP), 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 16-byte hash 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.
+ Using 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)
+ after which the user is allowed to change his password. If this 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) 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>
+
+
+ <table frame="all" id="attribobjclPartB">
+ <title>Attributes in the sambaSamAccount ObjectClass (LDAP), 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 a 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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+ 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 PDC). The following four attributes
+ are only stored with the sambaSamAccount entry if the values are non-default values:
+ </para>
+
+ <itemizedlist>
+<indexterm><primary>sambaHomePath</primary></indexterm>
+<indexterm><primary>sambaLogonScript</primary></indexterm>
+<indexterm><primary>sambaProfilePath</primary></indexterm>
+<indexterm><primary>sambaHomeDrive</primary></indexterm>
+ <listitem><para>sambaHomePath</para></listitem>
+ <listitem><para>sambaLogonScript</para></listitem>
+ <listitem><para>sambaProfilePath</para></listitem>
+ <listitem><para>sambaHomeDrive</para></listitem>
+ </itemizedlist>
+
+ <para>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>smbHome</primary></indexterm>
+ 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> logs on 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:
+<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>
+ </para>
+
+ <para>
+ The following is an LDIF entry for using both the sambaSamAccount and
+ posixAccount ObjectClasses:
+<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>
+ </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">Possible <emphasis>ldap passwd sync</emphasis> Values</link>.</para>
+
+ <table frame="all" id="ldappwsync">
+ <title>Possible <parameter>ldap passwd sync</parameter> 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 and
+ 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>
+
+ <sect3>
+ <title>Using OpenLDAP Overlay for Password Syncronization</title>
+
+ <para>
+ Howard Chu has written a special overlay called <command>smbk5pwd</command>. This tool modifies the
+ <literal>SambaNTPassword</literal>, <literal>SambaLMPassword</literal> and <literal>Heimdal</literal>
+ hashes in an OpenLDAP entry when an LDAP_EXOP_X_MODIFY_PASSWD operation is performed.
+ </para>
+
+ <para>
+ The overlay is shipped with OpenLDAP-2.3 and can be found in the
+ <filename>contrib/slapd-modules/smbk5pwd</filename> subdirectory. This module can also be used with
+ OpenLDAP-2.2.
+ </para>
+
+ </sect3>
+
+ </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 <link linkend="acctmgmttools">Account Management Tools,</link> for details.</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 &smbmdash;
+ for example, <smbconfoption name="auth methods">guest sam</smbconfoption>.
+ </para>
+
+ </sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml b/docs-xml/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml
new file mode 100644
index 0000000000..0e8b1ef229
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-PolicyMgmt.xml
@@ -0,0 +1,607 @@
+<?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>
+<indexterm><primary>validation</primary></indexterm>
+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>
+<indexterm><primary>Group Policies</primary></indexterm>
+<indexterm><primary>users</primary></indexterm>
+<indexterm><primary>groups</primary></indexterm>
+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>Group Policy Objects</primary><see>GPO</see></indexterm>
+<indexterm><primary>GPOs</primary></indexterm>
+<indexterm><primary>ADS</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 back in 2000 and 2001 when there were few postings regarding GPOs and
+how to replicate them in a Samba environment.
+</para>
+
+<para>
+<indexterm><primary>exploit opportunities</primary></indexterm>
+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>
+
+</sect1>
+
+<sect1>
+<title>Creating and Managing System Policies</title>
+
+<para>
+<indexterm><primary>NETLOGON</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>registry</primary></indexterm>
+<indexterm><primary>affect users</primary></indexterm>
+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>
+<indexterm><primary>poledit.exe</primary></indexterm>
+<indexterm><primary>policy editor</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-ROM, but
+disappeared again with the introduction of MS Windows Me. 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>
+<indexterm><primary>MMC</primary></indexterm>
+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>
+<indexterm><primary>network policies</primary></indexterm>
+<indexterm><primary>system policies</primary></indexterm>
+<indexterm><primary>Profiles</primary></indexterm>
+<indexterm><primary>Policies</primary></indexterm>
+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>.
+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>
+<indexterm><primary>Group Policy Editor</primary></indexterm>
+<indexterm><primary>tools\reskit\netadmin\poledit</primary></indexterm>
+ 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-ROM 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>
+<indexterm><primary>Config.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>
+<indexterm><primary>registry</primary></indexterm>
+ 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 backup
+ 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>
+<indexterm><primary>grouppol.inf</primary></indexterm>
+<indexterm><primary>Group Policy</primary></indexterm>
+ Install the Group Policy handler for Windows 9x/Me to pick up Group Policies. Look on the
+ Windows 98 CD-ROM 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>
+<indexterm><primary>ntconfig.pol</primary></indexterm>
+<indexterm><primary>poledit.exe</primary></indexterm>
+<indexterm><primary>Policy Editor</primary></indexterm>
+<indexterm><primary>domain policies</primary></indexterm>
+ 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>
+<indexterm><primary>poledit.exe</primary></indexterm>
+<indexterm><primary>common.adm</primary></indexterm>
+<indexterm><primary>winnt.adm</primary></indexterm>
+<indexterm><primary>c:\winnt\inf</primary></indexterm>
+ 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>
+<indexterm><primary>Policy Editor</primary></indexterm>
+<indexterm><primary>Nt4sp6ai.exe</primary></indexterm>
+<indexterm><primary>poledit.exe</primary></indexterm>
+<indexterm><primary>Zero Administration Kit</primary></indexterm>
+ 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>
+ &smbmdash; 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 download 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>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+<indexterm><primary>HKEY_LOCAL_MACHINE</primary></indexterm>
+ 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>
+<indexterm><primary>registry</primary></indexterm>
+ 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>
+<indexterm><primary>Administrative Templates</primary></indexterm>
+ The older NT4-style registry-based policies are known as <emphasis>Administrative Templates</emphasis>
+ in MS Windows 2000/XP 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, 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>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+<indexterm><primary>NETLOGON</primary></indexterm>
+<indexterm><primary>local registry values</primary></indexterm>
+ 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 and 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>
+<indexterm><primary>SYSVOL</primary></indexterm>
+<indexterm><primary>NETLOGON</primary></indexterm>
+<indexterm><primary>replicated</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>domain controllers</primary></indexterm>
+<indexterm><primary>Group Policy Container</primary><see>GPC</see></indexterm>
+<indexterm><primary>Group Policy Template</primary><see>GPT</see></indexterm>
+<indexterm><primary>replicated SYSVOL</primary></indexterm>
+ 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>
+<indexterm><primary>GPOs</primary></indexterm>
+ 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>
+<indexterm><primary>poledit.exe</primary></indexterm>
+<indexterm><primary>MMC snap-in</primary></indexterm>
+<indexterm><primary>Poledit</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>
+<indexterm><primary>organizational unit</primary><see>OU</see></indexterm>
+ 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,
+ refer to the Microsoft Windows Resource Kit for your particular
+ version of MS Windows.
+ </para>
+
+ <note>
+ <para>
+<indexterm><primary>gpolmig.exe</primary></indexterm>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+<indexterm><primary>resource kit</primary></indexterm>
+ The MS Windows 2000 Resource Kit contains a tool called <command>gpolmig.exe</command>. This tool can be used
+ to migrate an NT4 <filename>NTConfig.POL</filename> 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>
+
+ <sect3>
+ <title>Custom System Policy Templates</title>
+
+ <para>
+ Over the past year, there has been a bit of talk regarding the creation of customized
+ templates for the Windows Sytem Policy Editor. A recent announcement on the Samba mailing
+ list is worthy of mention.
+ </para>
+
+ <para>
+ Mike Petersen has announced the availability of a template file he has created. This custom System Policy
+ Editor Template will allow you to successfully control Microsoft Windows workstations from an SMB server, such
+ as Samba. This template has been tested on a few networks, although if you find any problems with any of these
+ policies, or have any ideas for additional policies, let me know at mailto:mgpeter@pcc-services.com. This
+ Template includes many policies for Windows XP to allow it to behave better in a professional environment.
+ </para>
+
+ <para>
+ For further information please see the <ulink
+ url="http://www.pcc-services.com/custom_poledit.html">Petersen</ulink> Computer Consulting web site. There is
+ a download link for the template file.
+ </para>
+
+ </sect3>
+ </sect2>
+</sect1>
+
+<sect1>
+<title>Managing Account/User Policies</title>
+
+<para>
+<indexterm><primary>Policies</primary></indexterm>
+<indexterm><primary>policy file </primary></indexterm>
+<indexterm><primary>registry settings</primary></indexterm>
+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>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+<indexterm><primary>NETLOGON</primary></indexterm>
+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 <filename>NTConfig.POL</filename> 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>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+<indexterm><primary>NT4 style policy updates</primary></indexterm>
+MS Windows 200x/XP clients that log onto an MS Windows Active Directory security domain may additionally
+acquire policy settings through GPOs that are defined and stored in Active Directory
+itself. The key benefit of using AD 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>
+<indexterm><primary>account restrictions</primary></indexterm>
+<indexterm><primary>Common restrictions</primary></indexterm>
+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>
+<indexterm><primary>Domain User Manager</primary></indexterm>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+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 Toolset</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>
+<indexterm><primary>regedt32.exe</primary></indexterm>
+<indexterm><primary>Group Policy Editor</primary></indexterm>
+<indexterm><primary>MMC</primary></indexterm>
+ 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 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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>NET</primary></indexterm>
+<indexterm><primary>rpcclient</primary></indexterm>
+ 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>, and <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>
+<indexterm><primary>Remote Procedure Call System Service</primary><see>RPCSS</see></indexterm>
+<indexterm><primary>multiple universal naming convention provider</primary><see>MUP</see></indexterm>
+ Network starts, then Remote Procedure Call System Service (RPCSS) and multiple universal naming
+ convention provider (MUP) start.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>GPOs</primary></indexterm>
+ Where Active Directory is involved, an ordered list of 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 startup 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 GPOs
+ (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 startup; 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-xml/Samba3-HOWTO/TOSHARG-Portability.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Portability.xml
new file mode 100644
index 0000000000..533ad5c9bb
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Portability.xml
@@ -0,0 +1,270 @@
+<?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>
+<indexterm><primary>platforms</primary></indexterm>
+<indexterm><primary>compatible</primary></indexterm>
+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>
+<indexterm><primary>/etc/logingroup</primary></indexterm>
+<indexterm><primary>/etc/group</primary></indexterm>
+Hewlett-Packard's implementation of supplementary groups is nonstandard (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
+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>
+<indexterm><primary>gcc</primary></indexterm>
+<indexterm><primary>ANSI compiler</primary></indexterm>
+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 files, you then assemble them using
+</para>
+
+<screen>
+&prompt;<userinput>as seteuid.s</userinput>
+&prompt;<userinput>as setegid.s</userinput>
+</screen>
+
+<para>
+which should produce the files <filename>seteuid.o</filename> and
+<filename>setegid.o</filename>.
+</para>
+
+<para>
+Next you need to add these to the LIBSM line in the DNIX section of
+the Samba Makefile. Your LIBSM line will 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>
+<indexterm><primary>loopback interface</primary></indexterm>
+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: Sequential Read Ahead</title>
+<!-- From an email by William Jojo <jojowil@hvcc.edu> -->
+<para>
+Disabling sequential read ahead can improve Samba performance significantly
+when there is a relatively high level of multiprogramming (many smbd processes
+or mixed with another workload), not an abundance of physical memory or slower
+disk technology. These can cause AIX to have a higher WAIT values. Disabling
+sequential read-ahead can also have an adverse affect on other workloads in the
+system so you will need to evaluate other applications for impact.
+</para>
+
+<para>
+It is recommended to use the defaults provided by IBM, but if you experience a
+high amount of wait time, try disabling read-ahead with the following commands:
+</para>
+
+<para>
+For AIX 5.1 and earlier: <userinput>vmtune -r 0</userinput>
+</para>
+
+<para>
+For AIX 5.2 and later jfs filesystems: <userinput>ioo -o minpgahead=0</userinput>
+</para>
+
+<para>
+For AIX 5.2 and later jfs2 filesystems: <userinput>ioo -o j2_minPageReadAhead=0</userinput>
+</para>
+
+<para>
+If you have a mix of jfs and jfs2 filesystems on the same host, simply use both
+ioo commands.
+</para>
+</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. The visible manifestation of this was a handful of
+processes stealing all of the CPU, and when they were trussed, they would
+be stuck in F_SETLKW64 loops.
+</para>
+
+<para>
+Please check with Sun support for current patches needed to fix this bug.
+The patch revision for 2.6 is 105181-34, for 8 is 108528-19, and for 9 is 112233-04.
+After the installation 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/search/advsearch.do?collection=PATCH&amp;type=collections&amp;max=50&amp;language=en&amp;queryKey5=112960;rev=14&amp;toDocument=yes">112960-14</ulink>.
+</para>
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Printing.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Printing.xml
new file mode 100644
index 0000000000..1cf35fb7c4
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Printing.xml
@@ -0,0 +1,3273 @@
+<?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="classicalprinting">
+
+<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>
+<indexterm><primary>mission-critical</primary></indexterm>
+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>
+<indexterm><primary>print service</primary></indexterm>
+<indexterm><primary>domain member server</primary></indexterm>
+<indexterm><primary>standalone server</primary></indexterm>
+<indexterm><primary>file serving</primary></indexterm>
+<indexterm><primary>dedicated print server</primary></indexterm>
+<indexterm><primary>print server</primary></indexterm>
+<indexterm><primary>printing support</primary></indexterm>
+<indexterm><primary>Point'n'Print</primary></indexterm>
+<indexterm><primary>Add Printer Wizard</primary></indexterm>
+<indexterm><primary>upload drivers</primary></indexterm>
+<indexterm><primary>manage drivers</primary></indexterm>
+<indexterm><primary>install drivers</primary></indexterm>
+<indexterm><primary>print accounting</primary></indexterm>
+<indexterm><primary>Common UNIX Printing System</primary><see>CUPS</see></indexterm>
+A Samba print service may be run on a standalone or domain member server, side by side with file serving
+functions, or on a dedicated print server. It can be made as tightly 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 <literal>Point'n'Print</literal> mechanism. Printer
+installations executed by <literal>Logon Scripts</literal> are no problem. Administrators can upload and manage
+drivers to be used by clients through the familiar <literal>Add Printer Wizard</literal>. 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>
+<indexterm><primary>BSD</primary></indexterm>
+<indexterm><primary>CUPS</primary></indexterm>
+This chapter outlines the fundamentals of Samba printing as implemented by the more traditional UNIX
+BSD- and System V-style printing systems. Much of the information in this chapter applies 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. For further information refer to <link linkend="CUPS-printing">CUPS Printing Support</link>.
+</para>
+
+<note>
+<para>
+<indexterm><primary>Windows XP Professional</primary></indexterm>
+<indexterm><primary>Windows 200x/XP</primary></indexterm>
+<indexterm><primary>Windows NT4</primary></indexterm>
+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 NT4 is somewhat different again.
+</para>
+</note>
+
+</sect1>
+
+<sect1>
+<title>Technical Introduction</title>
+
+<para>
+<indexterm><primary>printing support</primary></indexterm>
+<indexterm><primary>print subsystem</primary></indexterm>
+<indexterm><primary>printing system</primary></indexterm>
+Samba's printing support always relies on the installed print subsystem of the UNIX OS it runs on. Samba is a
+<literal>middleman.</literal> 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>
+<indexterm><primary>UNIX printing</primary></indexterm>
+<indexterm><primary>CUPS</primary></indexterm>
+This chapter deals with the traditional way of UNIX printing. The next chapter covers in great detail the more
+modern CUPS.
+</para>
+
+<important><para>
+<indexterm><primary>CUPS</primary></indexterm>
+CUPS users, be warned: do not just jump on to the next chapter. You might miss important information only found here!
+</para></important>
+
+<para>
+<indexterm><primary>print configuration</primary></indexterm>
+<indexterm><primary>problematic print</primary></indexterm>
+<indexterm><primary>print processing</primary></indexterm>
+<indexterm><primary>print filtering</primary></indexterm>
+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>
+<indexterm><primary>data stream</primary></indexterm>
+<indexterm><primary>local spool area</primary></indexterm>
+<indexterm><primary>spooled file</primary></indexterm>
+<indexterm><primary>local system printing</primary></indexterm>
+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>
+<indexterm><primary>global-level</primary></indexterm>
+<indexterm><primary>service-level</primary></indexterm>
+<indexterm><primary>printing behavior</primary></indexterm>
+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>
+<indexterm><primary>BSD Printing</primary></indexterm>
+<indexterm><primary>simple printing</primary></indexterm>
+<indexterm><primary>enables clients to print</primary></indexterm>
+<indexterm><primary>print environment</primary></indexterm>
+<link linkend="simpleprc">Simple Configuration with BSD Printing</link> shows a simple printing configuration.
+If you compare this with your own, you may find additional parameters that have been preconfigured by your OS
+vendor. Following 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>
+
+<example id="simpleprc">
+<title>Simple Configuration with BSD Printing</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>testparm</primary></indexterm>
+<indexterm><primary>misconfigured settings</primary></indexterm>
+<indexterm><primary>pager program</primary></indexterm>
+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
+settings, both default as well as &smb.conf; file settings. <command>Testparm</command> gives warnings for all
+misconfigured settings. The complete output is easily 360 lines and more, so you may want to pipe it through a
+pager program.
+</para>
+
+<para>
+<indexterm><primary>configuration syntax</primary></indexterm>
+<indexterm><primary>syntax tolerates spelling errors</primary></indexterm>
+<indexterm><primary>case-insensitive</primary></indexterm>
+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 book, Samba tolerates some spelling errors (such as
+<smbconfoption name="browseable"/> instead of <smbconfoption name="browsable"/>), 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>
+<indexterm><primary>printing-related settings</primary></indexterm>
+<indexterm><primary>lp</primary></indexterm>
+<indexterm><primary>print</primary></indexterm>
+<indexterm><primary>spool</primary></indexterm>
+<indexterm><primary>driver</primary></indexterm>
+<indexterm><primary>ports</primary></indexterm>
+<indexterm><primary>testparm</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>print configuration</primary></indexterm>
+<indexterm><primary>printer shares </primary></indexterm>
+<indexterm><primary>spooling path</primary></indexterm>
+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</constant>,
+<constant>print</constant>, <constant>spool</constant>, <constant>driver</constant>,
+<constant>ports</constant>, and <constant>[</constant> in <command>testparm</command>'s 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>:
+<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 = 139 445
+ 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>
+The <command>testparm</command> 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>
+<indexterm><primary>troubleshoot</primary></indexterm>
+<indexterm><primary>testparm</primary></indexterm>
+<indexterm><primary>parameters</primary></indexterm>
+<indexterm><primary>verify</primary></indexterm>
+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>
+<indexterm><primary>commenting out setting</primary></indexterm>
+<indexterm><primary>publishing printers</primary></indexterm>
+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.
+<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>
+<indexterm><primary>explicitly set</primary></indexterm>
+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>
+<indexterm><primary>testparm</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+This example should show that you can use <command>testparm</command> 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 restart smbd!
+This is not the case. Samba rereads 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:
+<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>
+<command>testparm</command> 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>
+<indexterm><primary>compile-time options</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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: <literal>Internal whitespace in a parameter value is retained verbatim.</literal> This means
+that a line consisting of, for example,
+<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 <literal>=</literal> 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>
+<indexterm><primary>Extended BSD Printing</primary></indexterm>
+<indexterm><primary>BSD-style printing</primary></indexterm>
+<indexterm><primary>CUPS</primary></indexterm>
+<indexterm><primary>testparm</primary></indexterm>
+<link linkend="extbsdpr">Extended BSD Printing Configuration</link> shows a more verbose 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, or 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>
+
+<example id="extbsdpr">
+<title>Extended BSD Printing Configuration</title>
+<smbconfblock>
+<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>
+</smbconfblock></example>
+
+<para>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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 misconfigured settings.
+</para>
+
+<sect2>
+<title>Detailed Explanation Settings</title>
+
+<para>
+The following is a discussion of the settings from <link linkend="extbsdpr">Extended BSD Printing
+Configuration</link> <link linkend="extbsdpr">Extended BSD Printing Configuration</link>.
+</para>
+
+<sect3>
+<title>The [global] Section</title>
+
+<para>
+<indexterm><primary>global section</primary></indexterm>
+<indexterm><primary>special sections</primary></indexterm>
+<indexterm><primary>individual section</primary></indexterm>
+<indexterm><primary>share</primary></indexterm>
+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 that 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 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>
+<indexterm><primary>default print commands</primary></indexterm>
+<indexterm><primary>RFC 1179</primary></indexterm>
+<indexterm><primary>printing</primary></indexterm>
+<indexterm><primary>CUPS</primary></indexterm>
+<indexterm><primary>LPD</primary></indexterm>
+<indexterm><primary>LPRNG</primary></indexterm>
+<indexterm><primary>SYSV</primary></indexterm>
+<indexterm><primary>HPUX</primary></indexterm>
+<indexterm><primary>AIX</primary></indexterm>
+<indexterm><primary>QNX</primary></indexterm>
+<indexterm><primary>PLP</primary></indexterm>
+<indexterm><primary>queue control</primary></indexterm>
+ 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>
+<indexterm><primary>service-level</primary></indexterm>
+<indexterm><primary>SOFTQ printing system</primary></indexterm>
+ 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>
+<indexterm><primary>printer shares</primary></indexterm>
+<indexterm><primary>printcap</primary></indexterm>
+<indexterm><primary>separate shares</primary></indexterm>
+<indexterm><primary>UNIX printer</primary></indexterm>
+ 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>
+<indexterm><primary>Add Printer Wizard</primary></indexterm>
+<indexterm><primary>Printers</primary></indexterm>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+<indexterm><primary>net view</primary></indexterm>
+<indexterm><primary>uploaded driver</primary></indexterm>
+ 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 a printer driver 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 for any other previously uploaded driver.
+ </para>
+ </listitem></varlistentry>
+
+ <varlistentry><term><smbconfoption name="max print jobs">100 </smbconfoption></term>
+ <listitem><para>
+<indexterm><primary>print jobs</primary></indexterm>
+ 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 "no more space available on server" 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>
+<indexterm><primary>CUPS</primary></indexterm>
+<indexterm><primary>available printerd</primary></indexterm>
+<indexterm><primary>printcap</primary></indexterm>
+ 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>
+<indexterm><primary>add drivers</primary></indexterm>
+<indexterm><primary>/etc/group</primary></indexterm>
+<indexterm><primary>printer share</primary></indexterm>
+<indexterm><primary>set printer properties</primary></indexterm>
+ 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 <literal>@</literal> 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 <link linkend="cups-msrpc">Printing Developments Since
+ Samba-2.2</link>). 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>
+<indexterm><primary>lpq command</primary></indexterm>
+<indexterm><primary>lpq cache time</primary></indexterm>
+ 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>
+<indexterm><primary>Windows NT/200x/XP</primary></indexterm>
+ 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>
+<indexterm><primary>printers section</primary></indexterm>
+<indexterm><primary>printcap</primary></indexterm>
+The printers section 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 convenient 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 <emphasis>sticky</emphasis> 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 "nobody." 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 that the
+ last one encountered by Samba wins. <command>testparm</command> 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 <emphasis>printable</emphasis> 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>
+<indexterm><primary>loading printer drivers</primary></indexterm>
+<indexterm><primary>name conflict</primary></indexterm>
+If a <parameter>[my_printer_name]</parameter> section appears in the &smb.conf; file, which includes the
+parameter <smbconfoption name="printable">yes</smbconfoption> Samba will 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>
+
+<?latex \newpage ?>
+<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">Section 20.4.1.2</link>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term><smbconfoption name="writable">no </smbconfoption></term>
+ <listitem><para>
+ See <link linkend="ptrsect">Section 20.4.1.2</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>
+<indexterm><primary>print command</primary></indexterm>
+<indexterm><primary>print subsystem</primary></indexterm>
+<indexterm><primary>temporary location</primary></indexterm>
+<indexterm><primary>shell scripts</primary></indexterm>
+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>
+<indexterm><primary>default print command</primary></indexterm>
+You learned earlier 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 in <link linkend="printOptions">Default Printing Settings</link> , 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 in <link linkend="printOptions">Default Printing Settings</link> presents an overview
+of key printing options but excludes the special case of CUPS, 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>
+<indexterm><primary>CUPS API</primary></indexterm>
+<indexterm><primary>cupsd.conf</primary></indexterm>
+<indexterm><primary>autogenerated printcap</primary></indexterm>
+<indexterm><primary>libcups</primary></indexterm>
+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 autogenerated printcap file to an unusual place).
+Otherwise, Samba maps to the System V printing commands with the -oraw option for printing; that is, 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>
+<indexterm><primary>print job</primary></indexterm>
+<indexterm><primary>spooling</primary></indexterm>
+After a print job has finished spooling to a service, the <smbconfoption name="print command"/> will be used
+by Samba via a system() 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>
+<indexterm><primary>traditional printing</primary></indexterm>
+<indexterm><primary>customized print commands</primary></indexterm>
+<indexterm><primary>built-in commands</primary></indexterm>
+<indexterm><primary>macros</primary></indexterm>
+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 <link linkend="printOptions">Default Printing
+Settings</link>). 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 placeholders 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>
+<indexterm><primary>default printer</primary></indexterm>
+The print command must contain at least one occurrence of <parameter>%s</parameter> or
+<parameter>%f</parameter>. The <parameter>%p</parameter> is optional. If no printer name is supplied,
+the <parameter>%p</parameter> will be silently removed from the print command. In this case, the job is
+sent to the default printer.
+</para>
+
+<para>
+<indexterm><primary>global print command</primary></indexterm>
+<indexterm><primary>spool files</primary></indexterm>
+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>
+<indexterm><primary>nobody account</primary></indexterm>
+<indexterm><primary>guest account</primary></indexterm>
+Printing may fail on some UNIX systems when using the <emphasis>nobody</emphasis> 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>
+<indexterm><primary>environment variables</primary></indexterm>
+<indexterm><primary>print commands</primary></indexterm>
+<indexterm><primary>print job</primary></indexterm>
+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 &gt;&gt; /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 id="cups-msrpc">
+<title>Printing Developments Since Samba-2.2</title>
+
+<para>
+<indexterm><primary>LanMan</primary></indexterm>
+<indexterm><primary>MS-RPC</primary></indexterm>
+<indexterm><primary>SPOOLSS</primary></indexterm>
+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> (Remote Procedure Calls).
+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>
+<indexterm><primary>Point'n'Print</primary></indexterm>
+ Support for downloading printer driver files to Windows 95/98/NT/2000 clients upon
+ demand (<emphasis>Point'n'Print</emphasis>).
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>Add Printer Wizard</primary></indexterm>
+ 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>
+<indexterm><primary>MS-RPC</primary></indexterm>
+<indexterm><primary>printing calls</primary></indexterm>
+<indexterm><primary>StartDocPrinter</primary></indexterm>
+<indexterm><primary>EnumJobs()</primary></indexterm>
+<indexterm><primary>Win32 printing API</primary></indexterm>
+ 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>
+<indexterm><primary>ACL</primary></indexterm>
+<indexterm><primary>printer objects</primary></indexterm>
+ Support for NT Access Control Lists (ACL) on printer objects.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>printer queue</primary></indexterm>
+ 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>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+A benefit of updating is that Samba-3 is able to publish its printers to Active Directory (or LDAP).
+</para>
+
+<para>
+<indexterm><primary>publish printers</primary></indexterm>
+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>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>MS-RPC</primary></indexterm>
+<indexterm><primary>Everyone group</primary></indexterm>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>printer default permissions</primary></indexterm>
+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>
+<indexterm><primary>printer drivers</primary></indexterm>
+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>
+<indexterm><primary>install drivers</primary></indexterm>
+<indexterm><primary>print queue</primary></indexterm>
+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 bug 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>
+<indexterm><primary>printer drivers</primary></indexterm>
+<indexterm><primary>uploading</primary></indexterm>
+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> toolset.
+ </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>
+<indexterm><primary>uploaded drivers</primary></indexterm>
+<indexterm><primary>Point'n'Print</primary></indexterm>
+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>
+<indexterm><primary>printer$ share</primary></indexterm>
+<indexterm><primary>printer driver</primary></indexterm>
+ 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>
+<indexterm><primary>printer driver file</primary></indexterm>
+<indexterm><primary>read-write access</primary></indexterm>
+<indexterm><primary>ACLs</primary></indexterm>
+ 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 downloadable 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>
+<indexterm><primary>printer driver</primary></indexterm>
+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">[print\$] Example</link>.
+</para>
+
+<example id="prtdollar">
+<title>[print$] Example</title>
+<smbconfblock>
+<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>
+<smbconfcomment>...</smbconfcomment>
+
+<smbconfsection name="[printers]"/>
+<smbconfcomment>...</smbconfcomment>
+
+<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>
+</smbconfblock>
+</example>
+
+<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$] Stanza Parameters</title>
+
+<para>
+<indexterm><primary>special section</primary></indexterm>
+<indexterm><primary>special stanza</primary></indexterm>
+<indexterm><primary>potential printer</primary></indexterm>
+<indexterm><primary>driver download</primary></indexterm>
+<indexterm><primary>local print driver</primary></indexterm>
+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>
+ 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>. By excuting from a <command>cmd</command> shell:
+<screen>
+&dosprompt; <command>net use g:\\sambaserver\print$</command>
+</screen>
+ you can still mount it from any client. This can also be done from 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 log on 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 are 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 name only 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:
+<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 you forced
+Samba to reread 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 printers initially listed 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 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: <quote> 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?</quote>
+</para>
+
+<para>
+Do <emphasis>not</emphasis> click on <guibutton>Yes</guibutton>! Instead, click on <guibutton>No</guibutton>
+in the error dialog. Now you will be presented with the printer properties window. From here, the way to
+assign a driver to a printer is open. 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, set up 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 information 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>
+<indexterm><primary>driver files</primary></indexterm>
+<indexterm><primary>driver CDROM</primary></indexterm>
+<indexterm><primary>inf file</primary></indexterm>
+To find out about the driver files, you have two options. You can check the contents of the driver
+CDROM that came with your printer. Study the <filename>*.inf</filename> files located on the CD-ROM. 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>
+<indexterm><primary>W32X86</primary></indexterm>
+Then you have the second option. Install the driver locally on a Windows client and
+investigate which filenames 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>
+<indexterm><primary>driver files</primary></indexterm>
+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) <guilabel>Dependent Driver Files</guilabel>
+(this may vary slightly for Windows NT). You need to note all filenames for the next steps.
+</para>
+
+<para>
+<indexterm><primary>rpcclient</primary></indexterm>
+<indexterm><primary>enumdrivers</primary></indexterm>
+<indexterm><primary>getdriver</primary></indexterm>
+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 for you. 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 use if you
+want to create scripts to automate the procedure for a large number of printers and drivers. Note the
+different quotation marks used to overcome the different spaces 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>
+<indexterm><primary>Driver File</primary></indexterm>
+<indexterm><primary>Driver Path</primary></indexterm>
+<indexterm><primary>WIN40</primary></indexterm>
+<indexterm><primary>W32X86</primary></indexterm>
+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 NT 2000/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>
+<indexterm><primary>UNC notation</primary></indexterm>
+<indexterm><primary>Windows Explorer</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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 is <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 purpose. 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:
+<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 semicolons.
+This ensures that all commands are executed in sequence on the remote Windows server before
+<command>smbclient</command> exits again.
+</para>
+
+<para>
+<indexterm><primary>WIN40</primary></indexterm>
+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 &smb.conf; file. You also have created
+subdirectories for the different Windows client types you want to support. If, for example, 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, <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, <filename>/etc/samba/drivers/WIN40/</filename> but not
+ (yet) into the <filename>0</filename> subdirectory.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>smbclient</primary></indexterm>
+<indexterm><primary>getdriver</primary></indexterm>
+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.
+<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>
+<indexterm><primary>PPD</primary></indexterm>
+<indexterm><primary>PostScript driver</primary></indexterm>
+<indexterm><primary>adddriver</primary></indexterm>
+Whew &smbmdash; that was a lot of typing! Most drivers are a lot smaller &smbmdash; many have only 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>
+<indexterm><primary>smbclient</primary></indexterm>
+<indexterm><primary>SSH</primary></indexterm>
+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>
+<indexterm><primary>Point'n'Print</primary></indexterm>
+<indexterm><primary>printer driver files</primary></indexterm>
+<indexterm><primary>print queue</primary></indexterm>
+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 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 that 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>
+<indexterm><primary>adddriver</primary></indexterm>
+<indexterm><primary>register driver files</primary></indexterm>
+<indexterm><primary>TDB database</primary></indexterm>
+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 for readability:
+<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>
+<indexterm><primary>NT_STATUS_UNSUCCESSFUL</primary></indexterm>
+<indexterm><primary>error message</primary></indexterm>
+<indexterm><primary>adddriver</primary></indexterm>
+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.
+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>:
+<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>
+<indexterm><primary>registered</primary></indexterm>
+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>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+<indexterm><primary>Printers and Faxes</primary></indexterm>
+<indexterm><primary>printer icon</primary></indexterm>
+<indexterm><primary>Windows95/98/ME</primary></indexterm>
+<indexterm><primary>Windows NT/2000/XP</primary></indexterm>
+ 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
+ see only its 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>
+<indexterm><primary>Network Neighborhood</primary></indexterm>
+ From a Windows 200x/XP client (not Windows NT) browse <guiicon>Network Neighborhood</guiicon>,
+ search for the Samba server, open the server's <guiicon>Printers</guiicon> folder,
+ and 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>):
+ <screen>
+ <userinput>rundll32 printui.dll,PrintUIEntry /s /t2 /n\\<replaceable>SAMBA-CUPS</replaceable></userinput>
+ </screen>
+ </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:
+ <screen>
+ <userinput>rpcclient -U'root%xxxx' -c 'enumdrivers' <replaceable>SAMBA-CUPS</replaceable></userinput>
+ </screen>
+ </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?
+ 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>
+<indexterm><primary>adddriver</primary></indexterm>
+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:
+<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>
+<indexterm><primary>print queue</primary></indexterm>
+<indexterm><primary>rpcclient</primary></indexterm>
+<indexterm><primary>adddriver</primary></indexterm>
+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 <command>setdriver</command></title>
+
+<para>
+<indexterm><primary>mapping printer driver</primary></indexterm>
+<indexterm><primary>TDB</primary></indexterm>
+Samba needs to know which printer owns which driver. Create a mapping of the driver to a printer, and
+store this information in Samba's memory, the TDB files. The <command>rpcclient setdriver</command> command
+achieves exactly this:
+<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:
+<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 set up and shouldn't need further
+attention. What follows is a description for the recommended first procedure. You now work from a client
+workstation. You should check 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/200x, you can force a logoff from all smb/cifs connections by restarting the
+<emphasis>workstation</emphasis> service. You can try to close all Windows file explorers 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>
+<indexterm><primary>print test page</primary></indexterm>
+Most likely you are 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 "<literal>Unable to print Test Page</literal>." 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 id="prt-modeset">
+<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>
+<indexterm><primary>device mode</primary></indexterm>
+ 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>
+<indexterm><primary>printer driver data</primary></indexterm>
+ A complete set of <emphasis>printer driver data</emphasis> generated by the driver.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>ntprinters.tdb</primary></indexterm>
+<indexterm><primary>ntdrivers.tdb</primary></indexterm>
+<indexterm><primary>printing.tdb</primary></indexterm>
+<indexterm><primary>ntforms.tdb</primary></indexterm>
+<indexterm><primary>TDB database files</primary></indexterm>
+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>
+The device mode and the set of printer driver data are basically collections
+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 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 be correctly set only 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>
+<title>Procedure to Initialize the Printer Driver Settings</title>
+ <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.
+ </para></step>
+</procedure>
+
+<para>
+This procedure executes the printer driver program on the client platform and feeds back the correct
+device mode to Samba, which now stores 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>
+<indexterm><primary>default devmode</primary></indexterm>
+Samba includes a service-level parameter name <parameter>default devmode</parameter> for generating a default
+device mode for a printer. Some drivers 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>
+<indexterm><primary>additional driver</primary></indexterm>
+Every additional driver may be installed in the same way as just described. Browse <command>Network
+Neighborhood</command>, 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:
+<screen>
+<userinput>rundll32 shell32.dll,SHHelpShortcuts_RunDLL PrintersFolder</userinput>
+</screen>
+or this command on Windows NT 4.0 workstations:
+<indexterm><primary>rundll32</primary></indexterm>
+<screen>
+<userinput>rundll32 shell32.dll,Control_RunDLL MAIN.CPL @2</userinput>
+</screen>
+</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 <link
+ linkend="prt-modeset">Setting Device Modes on New Printers</link>) 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>
+<indexterm><primary>runas</primary></indexterm>
+To connect as root to a Samba printer, try this command from a Windows 200x/XP DOS box command prompt:
+<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 <constant>root</constant>'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. Alternatively, 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 (using
+<literal>Point'n'Print</literal>) 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 on 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 multitabbed 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 definitive 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 when you compare 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 C.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"/>) 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
+identical-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 identical-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):
+<indexterm><primary>rundll32</primary></indexterm>
+</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 that does not set systemwide 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 for this task 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 can 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 two commas in the description field). After the <command>setdriver</command> command
+succeeds, 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 reparse 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>Cannot connect under a different Name</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>
+<indexterm><primary>net use</primary></indexterm>
+ 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
+ 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 also disconnect all mapped drives 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 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 lowercase 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>
+<indexterm><primary>LPT1:</primary></indexterm>
+<indexterm><primary>COM1:</primary></indexterm>
+<indexterm><primary>FILE:</primary></indexterm>
+<indexterm><primary>available port</primary></indexterm>
+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>
+<indexterm><primary>Printer Pooling</primary></indexterm>
+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 failover.
+</para>
+
+<para>
+If you require multiple ports to be defined for some reason or another (my users and my boss should not know
+that they are working with Samba), configure the <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 Misconfiguration</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 <link linkend="CUPS-printing">CUPS Printing
+Chapter</link>, <link linkend="cups-avoidps1">Avoiding Critical PostScript Driver Settings on the
+Client</link>.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>The Imprints Toolset</title>
+
+<para>
+<indexterm><primary>Imprints</primary></indexterm>
+The Imprints tool set provides a UNIX equivalent of the Windows NT APW. 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 provides only a brief introduction
+to the features of Imprints.
+</para>
+
+<para>
+Unfortunately, the Imprints toolset is no longer maintained. As of December 2000, the project is in
+need of a new maintainer. The most important skill to have is 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 toolset is still in usable form, but only for a series of older printer models where
+there are prepared packages to use. Packages for more up-to-date print devices are needed if Imprints
+should have a future. Information regarding the Imprints toolset can be obtained from the <ulink
+url="http://imprints.sourceforge.net/">Imprints</ulink> home page.
+</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,
+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 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: Issues 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 namespace 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 because 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">Microsoft KB 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 Windows 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 prevents 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 autodownloaded 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 restart 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 is 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 to 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
+by executing the <command>lpadmin</command> command on more modern systems) and create the associated share,
+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 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 on the <ulink noescape="1"
+ url="http://imprints.sourceforge.net/">Imprints</ulink> web site for example. See also the discussion of
+ rpcclient usage in <link linkend="CUPS-printing">CUPS Printing</link>.
+ </para></listitem>
+</itemizedlist>
+</sect1>
+
+<sect1>
+<title>Publishing Printer Information in Active Directory or LDAP</title>
+
+<para>
+This topic has also been addressed in <link linkend="NetCommand">Remote and Local Management &smbmdash; The
+Net Command</link>. If you wish to volunteer your services to help document this further, 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:
+<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. The UNIX/Linux
+system print spool directory (e.g., <filename>/var/spool/cups</filename>) is typically owned by a
+non-privileged user such as <literal>cups</literal> or <literal>lp</literal>. Additionally. the permissions on
+the spool directory are typically restrictive to the owner and/or group. On the other hand, the Samba
+spool directory must be world writable, and should have the 't' bit set to ensure that only a temporary
+spool file owner can change or delete the file.
+</para>
+
+<para>
+Depending on the type of print spooling system in use on the UNIX/Linux host, files that the spool
+management application finds and that are not currently part of job queue that it is managing can be deleted.
+This may explain the observation that jobs are spooled (by Samba) into this directory and just disappear.
+</para>
+
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Problems.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Problems.xml
new file mode 100644
index 0000000000..8f1d3c1849
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Problems.xml
@@ -0,0 +1,329 @@
+<?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>
+<indexterm><primary>RFCs</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>documentation</primary></indexterm>
+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>
+<indexterm><primary>sniffer</primary></indexterm>
+<indexterm><primary>LAN</primary></indexterm>
+<indexterm><primary>analyzes data</primary></indexterm>
+<indexterm><primary>SMB networking</primary></indexterm>
+<indexterm><primary>network analyzer</primary></indexterm>
+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>
+<indexterm><primary>diagnostic tools</primary></indexterm>
+<indexterm><primary>debugging problems</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>debugging passwords</primary></indexterm>
+<indexterm><primary>debug level</primary></indexterm>
+<indexterm><primary>log level</primary></indexterm>
+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 (log level) can range from 1 (the default) to 10 (100 for debugging passwords).
+</para>
+
+<para>
+<indexterm><primary>debugging</primary></indexterm>
+<indexterm><primary>gcc</primary></indexterm>
+<indexterm><primary>gdb</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>LsaEnumTrustedDomains</primary></indexterm>
+<indexterm><primary>attach gdb</primary></indexterm>
+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 <command>gdb</command> 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:
+<indexterm><primary>testparm</primary></indexterm>
+<indexterm><primary>smbclient</primary></indexterm>
+<screen>
+&prompt;<userinput>testparm | more</userinput>
+&prompt;<userinput>smbclient -L //{netbios name of server}</userinput>
+</screen>
+</para>
+
+</sect2>
+
+<sect2>
+ <title>Tcpdump</title>
+
+<para>
+<indexterm><primary>tcpdump</primary></indexterm>
+<indexterm><primary>tethereal</primary></indexterm>
+<indexterm><primary>ethereal</primary></indexterm>
+<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>
+<indexterm><primary>ethereal</primary></indexterm>
+<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. For details on the use of <command>ethereal</command>, read
+the well-written Ethereal User Guide.
+</para>
+
+<figure id="ethereal1"><title>Starting a Capture.</title><imagefile>ethereal1</imagefile></figure>
+
+<para>
+<indexterm><primary>ports</primary></indexterm>
+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>
+
+<figure id="ethereal2"><title>Main Ethereal Data Window.</title><imagefile>ethereal2</imagefile></figure>
+
+</sect2>
+
+<sect2>
+<title>The Windows Network Monitor</title>
+
+<para>
+<indexterm><primary>Network Monitor</primary></indexterm>
+<indexterm><primary>Netmon</primary></indexterm>
+<indexterm><primary>Microsoft Developer Network CDs</primary></indexterm>
+<indexterm><primary>SMS</primary></indexterm>
+<indexterm><primary>promiscuous mode</primary></indexterm>
+<indexterm><primary>ethereal</primary></indexterm>
+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>
+<indexterm><primary>Netmon.</primary></indexterm>
+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>
+<indexterm><primary>Network Monitor Tools and Agent</primary></indexterm>
+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 included 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>. 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
+mainstream Samba lists.</para>
+
+<para>
+If you do post a message to one of the lists, please observe the following guidelines:
+</para>
+
+<itemizedlist>
+
+ <listitem><para>
+<indexterm><primary>volunteers</primary></indexterm>
+ 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>
+<indexterm><primary>PDC</primary></indexterm>
+ 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 to 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 holiday</quote> things when
+ you are away, make sure its configured to not answer mailing list traffic. Autoresponses
+ to mailing lists really irritate the thousands of people who end up having to deal
+ with such bad netiquet bahavior.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>cross post</primary></indexterm>
+ 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 who thinks a message 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 log 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-xml/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml b/docs-xml/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml
new file mode 100644
index 0000000000..571ca323ce
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-ProfileMgmt.xml
@@ -0,0 +1,1320 @@
+<?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>
+<indexterm><primary>roaming profiles</primary></indexterm>
+Roaming profiles are feared by some, hated by a few, loved by many, and a godsend for
+some administrators.
+</para>
+
+<para>
+<indexterm><primary>manage roaming profiles</primary></indexterm>
+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>
+<indexterm><primary>local profiles</primary></indexterm>
+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>
+<indexterm><primary>NetUserGetInfo</primary></indexterm>
+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>
+<indexterm><primary>NetSAMLogon</primary></indexterm>
+<indexterm><primary>RPC</primary></indexterm>
+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>
+
+<smbconfblock>
+ <smbconfoption name="logon path"> \\profileserver\profileshare\profilepath\%U\moreprofilepath</smbconfoption>
+</smbconfblock>
+
+<para>
+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 username.
+</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; regarding the different
+semantics of <quote>%L</quote> and <quote>%N</quote>, as well as <quote>%U</quote> and <quote>%u</quote>.
+</para>
+
+<note><para>
+<indexterm><primary>logons</primary></indexterm>
+<indexterm><primary>disconnect a connection</primary></indexterm>
+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"/> metaservice name as part of the profile share path.
+</para></note>
+</sect3>
+
+<sect3>
+<title>Windows 9x/Me User Profiles</title>
+
+<para>
+<indexterm><primary>net use /home</primary></indexterm>
+<indexterm><primary>logon home</primary></indexterm>
+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 <parameter>logon home</parameter> parameter.
+</para>
+
+<para>
+<indexterm><primary>logon home</primary></indexterm>
+<indexterm><primary>\\%L\%U\.profiles</primary></indexterm>
+<indexterm><primary>.profiles</primary></indexterm>
+By using the <parameter>logon home</parameter> 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:
+<smbconfblock>
+<smbconfoption name="logon home">\\%L\%U\.profiles</smbconfoption>
+</smbconfblock>
+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>
+<indexterm><primary>net use /home</primary></indexterm>
+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 Windows 9x/Me and 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>
+
+<para>
+<indexterm><primary>mixed profile</primary></indexterm>
+Windows 9x/Me and NT4 and later profiles should not be stored in the same location because
+Windows NT4 and later will experience problems with mixed profile environments.
+</para>
+
+</sect3>
+<sect3>
+<title>Disabling Roaming Profile Support</title>
+
+<para>
+<indexterm><primary>disable roaming profiles</primary></indexterm>
+The 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:
+</para>
+
+<indexterm><primary>windows registry settings</primary><secondary>roaming profiles</secondary></indexterm>
+
+<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>
+<indexterm><primary>MMC</primary></indexterm>
+<indexterm><primary>local profile</primary></indexterm>
+ Use the Microsoft Management Console (MMC) <command>gpedit.msc</command> 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>
+<indexterm><primary>Profile Type</primary></indexterm>
+ <listitem><para>From the start menu right-click on the <guiicon>My Computer</guiicon> icon,
+ 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>
+<indexterm><primary>Windows Resource Kit</primary></indexterm>
+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>
+<indexterm><primary>user.DAT</primary></indexterm>
+<indexterm><primary>user.MAN</primary></indexterm>
+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>
+<indexterm><primary>Primary Logon</primary></indexterm>
+<indexterm><primary>Client for Novell Networks</primary></indexterm>
+<indexterm><primary>Novell</primary></indexterm>
+<indexterm><primary>Windows Logon</primary></indexterm>
+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>
+<indexterm><primary>domain logon server</primary></indexterm>
+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 informs you that
+<computeroutput>The user has not logged on before</computeroutput> and asks <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>
+<indexterm><primary>cached locally</primary></indexterm>
+<indexterm><primary>shortcuts</primary></indexterm>
+<indexterm><primary>profile directory</primary></indexterm>
+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
+shortcuts, 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>
+<indexterm><primary>local profile</primary></indexterm>
+<indexterm><primary>remote profile</primary></indexterm>
+<indexterm><primary>ownership rights</primary></indexterm>
+<indexterm><primary>profile directory</primary></indexterm>
+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>
+<indexterm><primary>windows registry settings</primary></indexterm>
+<indexterm><primary>profile path</primary></indexterm>
+<indexterm><primary>user profiles</primary></indexterm>
+<indexterm><primary>desktop cache</primary></indexterm>
+<indexterm><primary>windows registry settings</primary><secondary>profile path</secondary></indexterm>
+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>.
+</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>
+<indexterm><primary>ProfilePath</primary></indexterm>
+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 whether the owner has
+any important files stored on his or her desktop or 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>
+<indexterm><primary>log level</primary></indexterm>
+<indexterm><primary>packet sniffer</primary></indexterm>
+<indexterm><primary>ethereal</primary></indexterm>
+<indexterm><primary>netmon.exe</primary></indexterm>
+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>
+<indexterm><primary>roaming profiles</primary></indexterm>
+<indexterm><primary>packet trace</primary></indexterm>
+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>
+<indexterm><primary>.PDS extension</primary></indexterm>
+<indexterm><primary>profile path</primary></indexterm>
+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>
+<indexterm><primary>NTuser.DAT</primary></indexterm>
+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>
+<indexterm><primary>NTuser.DAT</primary></indexterm>
+<indexterm><primary>NTuser.MAN</primary></indexterm>
+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, and 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:
+<screen>
+Computer Configuration\Administrative Templates\System\User Profiles\
+ Do not check for user ownership of Roaming Profile Folders
+</screen>
+ </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:
+ </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 are 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, a special service was created. The application
+<command>UPHClean</command> (User Profile Hive Cleanup) can be installed as a service on Windows NT4/2000/XP Professional
+and Windows 2003.
+</para>
+
+<para>
+The UPHClean software package can be downloaded from the User Profile Hive Cleanup
+Service<footnote>http://www.microsoft.com/downloads/details.aspx?FamilyID=1B286E6D-8912-4E18-B570-42470E2F3582&amp;displaylang=en</footnote>
+web site.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Sharing Profiles between Windows 9x/Me and NT4/200x/XP Workstations</title>
+
+<para>
+<indexterm><primary>profile sharing</primary></indexterm>
+<indexterm><primary>profile contents</primary></indexterm>
+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 and Desktop with Windows 9x/Me, you must 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>
+<indexterm><primary>user.DAT</primary></indexterm>
+<indexterm><primary>NTuser.DAT</primary></indexterm>
+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>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+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 id="profilemigrn">
+<title>Windows NT4 Profile Management Tools</title>
+
+<para>
+<indexterm><primary>resource kit</primary></indexterm>
+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>
+<title>Profile Migration Procedure</title>
+
+ <step><para> On your NT4 domain controller, right-click on <guiicon>My Computer</guiicon>, then select
+ <guilabel>Properties</guilabel>, then 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, such as,
+ <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 these steps for every profile you need to migrate.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Side Bar Notes</title>
+
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>info</tertiary></indexterm>
+You should obtain the SID of your NT4 domain. You can use the <command>net rpc info</command> to do this.
+See <link linkend="NetCommand">The Net Command Chapter</link>, <link linkend="netmisc1">Other Miscellaneous Operations</link> for more information.
+</para>
+
+</sect3>
+
+<sect3>
+<title>moveuser.exe</title>
+
+<para>
+<indexterm><primary>moveuser.exe</primary></indexterm>
+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 username 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>
+<indexterm><primary>GetSID.exe</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 <link linkend="PolicyMgmt">System and Account
+Policies</link>.
+</para>
+
+<note><para>
+<indexterm><primary>fake-permissions module</primary></indexterm>
+<indexterm><primary>VFS module</primary></indexterm>
+<indexterm><primary>fake_perms</primary></indexterm>
+Under NO circumstances should the profile directory (or its contents) be made read-only because this may
+render the profile unusable. 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>
+<indexterm><primary>NTUser.MAN</primary></indexterm>
+<indexterm><primary>NTUser.DAT</primary></indexterm>
+For MS Windows NT4/200x/XP, the procedure shown in <link linkend="profilemigrn">Profile Migration from Windows
+NT4/200x Server to Samba</link> 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>
+<indexterm><primary>User.MAN</primary></indexterm>
+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>
+<indexterm><primary>template</primary></indexterm>
+<indexterm><primary>profile migration tool</primary></indexterm>
+<indexterm><primary>profile access rights</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>
+<indexterm><primary>User Manager</primary></indexterm>
+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>
+<indexterm><primary>registry keys</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 affect 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>
+<indexterm><primary>System Policy Editor</primary></indexterm>
+<indexterm><primary>registry</primary></indexterm>
+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>
+<indexterm><primary>regedit.exe</primary></indexterm>
+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
+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>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+When a user logs on to an MS Windows NT4 machine that is a member of a Microsoft security domain,
+the following steps are followed for profile handling:
+</para>
+
+<procedure>
+ <step> <para> The user's account information that is obtained during the logon process
+ contains the location of the user's 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>
+<indexterm><primary>NTConfig.POL</primary></indexterm>
+<indexterm><primary>NETLOGON</primary></indexterm>
+<indexterm><primary>authenticating server</primary></indexterm>
+<indexterm><primary>logon server</primary></indexterm>
+<indexterm><primary>HKEY_CURRENT_USER</primary></indexterm>
+ 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
+ re-created 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 is 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:
+<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>
+<indexterm><primary>regedt32</primary></indexterm>
+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
+made 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
+first creating a default user profile, then while logged in as that user, running <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:
+<screen>
+HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\
+User Shell Folders
+</screen>
+</para>
+
+<para>
+The default entries are shown in <link linkend="regkeys">Defaults of Profile Settings Registry Keys</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>
+<indexterm><primary>Windows XP Home Edition</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>domain security</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 is that they allow the administrator to create a global default
+profile and enforce it through the use of Group Policy Objects (GPOs).
+</para></note>
+
+<para>
+<indexterm><primary>Default User</primary></indexterm>
+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>
+<indexterm><primary>NETLOGON</primary></indexterm>
+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, it is <filename>%LOGONSERVER%\NETLOGON\Default User,</filename>
+and if one exists there, it will copy this to the workstation in the <filename>C:\Documents and
+Settings\</filename> under the Windows login name of the use.
+</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 user's desktop profile is 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 is 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 because it is maintenance intensive.
+ </para> </listitem>
+
+ <listitem> <para> Create an NT4-style NTConfig.POL file that specifies 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 affects 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>
+This 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:
+<screen>
+%LOGONSERVER%\%USERNAME%\Default Folders
+</screen>
+This stores the folders in the user's home directory under a directory called <filename>Default
+Folders</filename>. You could also use:
+<screen>
+\\<replaceable>SambaServer</replaceable>\<replaceable>FolderShare</replaceable>\%USERNAME%
+</screen>
+</para>
+
+<para>
+in which case the default folders are 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 <emphasis>must</emphasis> 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 is 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 is 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 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/200x). </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 &smbmdash; 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. 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
+ autodeletion 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 gigabytes 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 this discussion is to show that roaming profiles and good controls of how they can be
+changed as well as good discipline make 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 preset 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 autodeletion of roaming profiles 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>
+
+<sect2>
+<title>Debugging Roaming Profiles and NT4-style Domain Policies</title>
+
+<para>
+Roaming profiles and domain policies are implemented via <command>USERENV.DLL</command>.
+Microsoft Knowledge Base articles <ulink
+url="http://support.microsoft.com/default.aspx?scid=kb;en-us;221833">221833</ulink> and
+<ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;154120">154120</ulink>
+ describe how to instruct that DLL to debug the login process.
+</para>
+
+</sect2>
+</sect1>
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml b/docs-xml/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml
new file mode 100644
index 0000000000..5ce64ddffd
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-RightsAndPriviliges.xml
@@ -0,0 +1,600 @@
+<?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>
+<indexterm><primary>Windows user</primary></indexterm>
+<indexterm><primary>Windows group</primary></indexterm>
+<indexterm><primary>machine accounts</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+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 and
+Active Directory domains.
+</para>
+
+<para>
+<indexterm><primary>Windows NT4/2kX/XPPro</primary></indexterm>
+<indexterm><primary>machine account</primary></indexterm>
+<indexterm><primary>trusted</primary></indexterm>
+<indexterm><primary>user logons</primary></indexterm>
+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>
+<indexterm><primary>user accounts</primary></indexterm>
+<indexterm><primary>special account</primary></indexterm>
+<indexterm><primary>account name</primary></indexterm>
+<indexterm><primary>/bin/false</primary></indexterm>
+<indexterm><primary>/dev/null</primary></indexterm>
+<indexterm><primary>man-in-the-middle</primary></indexterm>
+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 normal user accounts in that the account name (login ID) is terminated with a
+<literal>$</literal> 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> The machine
+account is used only to authenticate domain member machines during start-up. This security measure
+is designed to block man-in-the-middle attempts to violate network integrity.
+</para>
+
+<note><para>
+<indexterm><primary>computer accounts</primary></indexterm>
+<indexterm><primary>domain member servers</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>secure authentication</primary></indexterm>
+Machine (computer) accounts are used in the Windows NT OS family to store security
+credentials for domain member servers and workstations. When the domain member
+starts up, it goes through a validation process that includes an exchange of
+credentials with a domain controller. If the domain member fails to authenticate
+using the credentials known for it by domain controllers, the machine will be refused
+all access by domain users. The computer account is essential to the way that MS
+Windows secures authentication.
+</para></note>
+
+<para>
+<indexterm><primary>UNIX system accounts</primary></indexterm>
+<indexterm><primary>system administrator</primary></indexterm>
+<indexterm><primary>root</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+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 user.
+</para>
+
+<para>
+<indexterm><primary>system interface scripts</primary></indexterm>
+<indexterm><primary>CIFS function calls</primary></indexterm>
+<indexterm><primary>root account</primary></indexterm>
+<indexterm><primary>UNIX host system</primary></indexterm>
+All versions of Samba call system interface scripts that permit CIFS function
+calls that are used to manage users, groups, and machine accounts
+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 requirement 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 possess <constant>root</constant>-level
+access to the UNIX host system.
+</para>
+
+<sect1>
+<title>Rights Management Capabilities</title>
+
+<para>
+<indexterm><primary>Windows privilege model</primary></indexterm>
+<indexterm><primary>privilege model</primary></indexterm>
+<indexterm><primary>rights assigned</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+Samba 3.0.11 introduced 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>
+<indexterm><primary>rights</primary></indexterm>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>manage privileges</primary></indexterm>
+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>
+
+<indexterm><primary>SeMachineAccountPrivilege</primary></indexterm>
+<indexterm><primary>SePrintOperatorPrivilege</primary></indexterm>
+<indexterm><primary>SeAddUsersPrivilege</primary></indexterm>
+<indexterm><primary>SeRemoteShutdownPrivilege</primary></indexterm>
+<indexterm><primary>SeDiskOperatorPrivilege</primary></indexterm>
+<indexterm><primary>SeTakeOwnershipPrivilege</primary></indexterm>
+<table id="rp-privs">
+ <title>Current Privilege Capabilities</title>
+ <tgroup cols="2">
+ <colspec align="right"/>
+ <colspec align="left"/>
+ <thead>
+ <row>
+ <entry align="left">Privilege</entry>
+ <entry align="left">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>
+<!-- These are not used at this time - so void them from the docs.
+ <row>
+ <entry><para>SeBackupPrivilege</para></entry>
+ <entry><para>Back up files and directories</para></entry>
+ </row>
+ <row>
+ <entry><para>SeRestorePrivilege</para></entry>
+ <entry><para>Restore files and directories</para></entry>
+ </row>
+**** End of commented out section **** -->
+ <row>
+ <entry><para>SeTakeOwnershipPrivilege</para></entry>
+ <entry><para>Take ownership of files or other objects</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<sect2>
+<title>Using the <quote>net rpc rights</quote> Utility</title>
+
+<para>
+<indexterm><primary>managing rights</primary></indexterm>
+<indexterm><primary>rights assigned</primary></indexterm>
+<indexterm><primary>NT4 User Manager for Domains</primary></indexterm>
+<indexterm><primary>command-line utility</primary></indexterm>
+<indexterm><primary>administrative actions</primary></indexterm>
+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 three new subcommands:
+</para>
+
+<variablelist>
+ <varlistentry><term>list [name|accounts]</term>
+ <listitem><para>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>list</tertiary></indexterm>
+<indexterm><primary>available rights</primary></indexterm>
+<indexterm><primary>privileges assigned</primary></indexterm>
+<indexterm><primary>privileged accounts</primary></indexterm>
+ When called with no arguments, <command>net rpc list</command>
+ simply lists 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> returns a list of all
+ privileged accounts on the server and the assigned rights.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>grant &lt;user&gt; &lt;right [right ...]&gt;</term>
+ <listitem><para>
+<indexterm><primary>assign rights</primary></indexterm>
+<indexterm><primary>grant rights</primary></indexterm>
+<indexterm><primary>add client machines</primary></indexterm>
+<indexterm><primary>user or group</primary></indexterm>
+ 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 domain controller,
+ 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>
+ The following syntax has the same result:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights grant</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc rights grant 'DOMAIN\Domain Admins' \
+ SeMachineAccountPrivilege -S server -U domadmin
+</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 backslash and the space from being interpreted by the system shell.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>revoke &lt;user&gt; &lt;right [right ...]&gt;</term>
+ <listitem><para>
+ This command is similar in format to <command>net rpc rights grant</command>. Its
+ effect is to remove an assigned right (or list of rights) from a user or group.
+ </para></listitem>
+ </varlistentry>
+
+</variablelist>
+
+<note><para>
+<indexterm><primary>member</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>revoke privileges</primary></indexterm>
+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. There are no
+default rights and privileges, except the ability for a member of the Domain Admins group to assign them.
+This means that all administrative rights and privileges (other than the ability to assign them) must be
+explicitly assigned, even for the Domain Admins group.
+</para></note>
+
+<para>
+<indexterm><primary>performed as root</primary></indexterm>
+<indexterm><primary>necessary rights</primary></indexterm>
+<indexterm><primary>add machine script</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+By default, no privileges are initially assigned to any account because 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, <parameter>add machine script</parameter> 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>
+<indexterm><primary>Access</primary></indexterm>
+<indexterm><primary>root user</primary></indexterm>
+<indexterm><primary>bypasses privilege</primary></indexterm>
+Access as the root user (UID=0) bypasses all privilege checks.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Description of Privileges</title>
+
+<para>
+<indexterm><primary>privileges</primary></indexterm>
+<indexterm><primary>additional privileges</primary></indexterm>
+<indexterm><primary>house-keeping</primary></indexterm>
+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 as a housekeeping matter, so 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>
+<indexterm><primary>SeAddUsersPrivilege</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>net rpc user add</primary></indexterm>
+ 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>
+<indexterm><primary>SeDiskOperatorPrivilege</primary></indexterm>
+<indexterm><primary>add/delete/change share</primary></indexterm>
+<indexterm><primary>ACL</primary></indexterm>
+ Accounts that possess 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>
+<indexterm><primary>SeMachineAccountPrivilege</primary></indexterm>
+<indexterm><primary>right to join domain</primary></indexterm>
+<indexterm><primary>join client</primary></indexterm>
+ This right controls whether or not the user can join client
+ machines to a Samba-controlled domain.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>SePrintOperatorPrivilege</term>
+ <listitem><para>
+<indexterm><primary>SePrintOperatorPrivilege</primary></indexterm>
+<indexterm><primary>privilege</primary></indexterm>
+<indexterm><primary>global right</primary></indexterm>
+<indexterm><primary>administrative rights</primary></indexterm>
+<indexterm><primary>printers admin</primary></indexterm>
+ 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>
+<indexterm><primary>SeRemoteShutdownPrivilege</primary></indexterm>
+<indexterm><primary>rebooting server</primary></indexterm>
+<indexterm><primary>aborting shutdown</primary></indexterm>
+ 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.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>SeTakeOwnershipPrivilege</term>
+ <listitem><para>
+<indexterm><primary>SeTakeOwnershipPrivilege</primary></indexterm>
+<indexterm><primary>take ownership</primary></indexterm>
+ This right permits users to take ownership of files and directories.
+ </para></listitem>
+ </varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>Privileges Suppored by Windows 2000 Domain Controllers</title>
+
+<para>
+ For reference purposes, a Windows NT4 Primary Domain Controller reports support for the following
+ privileges:
+<indexterm><primary>SeCreateTokenPrivilege</primary></indexterm>
+<indexterm><primary>SeAssignPrimaryTokenPrivilege</primary></indexterm>
+<indexterm><primary>SeLockMemoryPrivilege</primary></indexterm>
+<indexterm><primary>SeIncreaseQuotaPrivilege</primary></indexterm>
+<indexterm><primary>SeMachineAccountPrivilege</primary></indexterm>
+<indexterm><primary>SeTcbPrivilege</primary></indexterm>
+<indexterm><primary>SeSecurityPrivilege</primary></indexterm>
+<indexterm><primary>SeTakeOwnershipPrivilege</primary></indexterm>
+<indexterm><primary>SeLoadDriverPrivilege</primary></indexterm>
+<indexterm><primary>SeSystemProfilePrivilege</primary></indexterm>
+<indexterm><primary>SeSystemtimePrivilege</primary></indexterm>
+<indexterm><primary>SeProfileSingleProcessPrivilege</primary></indexterm>
+<indexterm><primary>SeIncreaseBasePriorityPrivilege</primary></indexterm>
+<indexterm><primary>SeCreatePagefilePrivilege</primary></indexterm>
+<indexterm><primary>SeCreatePermanentPrivilege</primary></indexterm>
+<indexterm><primary>SeBackupPrivilege</primary></indexterm>
+<indexterm><primary>SeRestorePrivilege</primary></indexterm>
+<indexterm><primary>SeShutdownPrivilege</primary></indexterm>
+<indexterm><primary>SeDebugPrivilege</primary></indexterm>
+<indexterm><primary>SeAuditPrivilege</primary></indexterm>
+<indexterm><primary>SeSystemEnvironmentPrivilege</primary></indexterm>
+<indexterm><primary>SeChangeNotifyPrivilege</primary></indexterm>
+<indexterm><primary>SeRemoteShutdownPrivilege</primary></indexterm>
+<screen>
+ SeCreateTokenPrivilege Create a token object
+ SeAssignPrimaryTokenPrivilege Replace a process level token
+ SeLockMemoryPrivilege Lock pages in memory
+ SeIncreaseQuotaPrivilege Increase quotas
+ SeMachineAccountPrivilege Add workstations to domain
+ SeTcbPrivilege Act as part of the operating system
+ SeSecurityPrivilege Manage auditing and security log
+ SeTakeOwnershipPrivilege Take ownership of files or other objects
+ SeLoadDriverPrivilege Load and unload device drivers
+ SeSystemProfilePrivilege Profile system performance
+ SeSystemtimePrivilege Change the system time
+SeProfileSingleProcessPrivilege Profile single process
+SeIncreaseBasePriorityPrivilege Increase scheduling priority
+ SeCreatePagefilePrivilege Create a pagefile
+ SeCreatePermanentPrivilege Create permanent shared objects
+ SeBackupPrivilege Back up files and directories
+ SeRestorePrivilege Restore files and directories
+ SeShutdownPrivilege Shut down the system
+ SeDebugPrivilege Debug programs
+ SeAuditPrivilege Generate security audits
+ SeSystemEnvironmentPrivilege Modify firmware environment values
+ SeChangeNotifyPrivilege Bypass traverse checking
+ SeRemoteShutdownPrivilege Force shutdown from a remote system
+</screen>
+ And Windows 200x/XP Domain Controllers and workstations reports to support the following privileges:
+<indexterm><primary>SeCreateTokenPrivilege</primary></indexterm>
+<indexterm><primary>SeAssignPrimaryTokenPrivilege</primary></indexterm>
+<indexterm><primary>SeLockMemoryPrivilege</primary></indexterm>
+<indexterm><primary>SeIncreaseQuotaPrivilege</primary></indexterm>
+<indexterm><primary>SeMachineAccountPrivilege</primary></indexterm>
+<indexterm><primary>SeTcbPrivilege</primary></indexterm>
+<indexterm><primary>SeSecurityPrivilege</primary></indexterm>
+<indexterm><primary>SeTakeOwnershipPrivilege</primary></indexterm>
+<indexterm><primary>SeLoadDriverPrivilege</primary></indexterm>
+<indexterm><primary>SeSystemProfilePrivilege</primary></indexterm>
+<indexterm><primary>SeSystemtimePrivilege</primary></indexterm>
+<indexterm><primary>SeProfileSingleProcessPrivilege</primary></indexterm>
+<indexterm><primary>SeIncreaseBasePriorityPrivilege</primary></indexterm>
+<indexterm><primary>SeCreatePagefilePrivilege</primary></indexterm>
+<indexterm><primary>SeCreatePermanentPrivilege</primary></indexterm>
+<indexterm><primary>SeBackupPrivilege</primary></indexterm>
+<indexterm><primary>SeRestorePrivilege</primary></indexterm>
+<indexterm><primary>SeShutdownPrivilege</primary></indexterm>
+<indexterm><primary>SeDebugPrivilege</primary></indexterm>
+<indexterm><primary>SeAuditPrivilege</primary></indexterm>
+<indexterm><primary>SeSystemEnvironmentPrivilege</primary></indexterm>
+<indexterm><primary>SeChangeNotifyPrivilege</primary></indexterm>
+<indexterm><primary>SeRemoteShutdownPrivilege</primary></indexterm>
+<indexterm><primary>SeUndockPrivilege</primary></indexterm>
+<indexterm><primary>SeSyncAgentPrivilege</primary></indexterm>
+<indexterm><primary>SeEnableDelegationPrivilege</primary></indexterm>
+<indexterm><primary>SeManageVolumePrivilege</primary></indexterm>
+<indexterm><primary>SeImpersonatePrivilege</primary></indexterm>
+<indexterm><primary>SeCreateGlobalPrivilege</primary></indexterm>
+<screen>
+ SeCreateTokenPrivilege Create a token object
+ SeAssignPrimaryTokenPrivilege Replace a process level token
+ SeLockMemoryPrivilege Lock pages in memory
+ SeIncreaseQuotaPrivilege Increase quotas
+ SeMachineAccountPrivilege Add workstations to domain
+ SeTcbPrivilege Act as part of the operating system
+ SeSecurityPrivilege Manage auditing and security log
+ SeTakeOwnershipPrivilege Take ownership of files or other objects
+ SeLoadDriverPrivilege Load and unload device drivers
+ SeSystemProfilePrivilege Profile system performance
+ SeSystemtimePrivilege Change the system time
+SeProfileSingleProcessPrivilege Profile single process
+SeIncreaseBasePriorityPrivilege Increase scheduling priority
+ SeCreatePagefilePrivilege Create a pagefile
+ SeCreatePermanentPrivilege Create permanent shared objects
+ SeBackupPrivilege Back up files and directories
+ SeRestorePrivilege Restore files and directories
+ SeShutdownPrivilege Shut down the system
+ SeDebugPrivilege Debug programs
+ SeAuditPrivilege Generate security audits
+ SeSystemEnvironmentPrivilege Modify firmware environment values
+ SeChangeNotifyPrivilege Bypass traverse checking
+ SeRemoteShutdownPrivilege Force shutdown from a remote system
+ SeUndockPrivilege Remove computer from docking station
+ SeSyncAgentPrivilege Synchronize directory service data
+ SeEnableDelegationPrivilege Enable computer and user accounts to
+ be trusted for delegation
+ SeManageVolumePrivilege Perform volume maintenance tasks
+ SeImpersonatePrivilege Impersonate a client after authentication
+ SeCreateGlobalPrivilege Create global objects
+</screen>
+<indexterm><primary>equivalence</primary></indexterm>
+ The Samba Team is implementing only those privileges that are logical and useful in the UNIX/Linux
+ environment. Many of the Windows 200X/XP privileges have no direct equivalence in UNIX.
+ </para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>The Administrator Domain SID</title>
+
+<para>
+<indexterm><primary>domain Administrator</primary></indexterm>
+<indexterm><primary>User Rights and Privileges</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>net getlocalsid</primary></indexterm>
+Please note that every Windows NT4 and later server requires a domain Administrator account. Samba versions
+commencing with 3.0.11 permit Administrative duties to be performed via assigned rights and privileges
+(see <link linkend="rights">User Rights and Privileges</link>). An account in the server's passdb backend can
+be set to the well-known RID of the default administrator account. To obtain the domain SID on a Samba domain
+controller, run the following command:
+<screen>
+&rootprompt; net getlocalsid
+SID for domain FOO is: S-1-5-21-4294955119-3368514841-2087710299
+</screen>
+<indexterm><primary>RID</primary></indexterm>
+You may assign the domain administrator RID to an account using the <command>pdbedit</command>
+command as shown here:
+<indexterm><primary>pdbedit</primary></indexterm>
+<screen>
+&rootprompt; pdbedit -U S-1-5-21-4294955119-3368514841-2087710299-500 -u root -r
+</screen>
+</para>
+
+<note><para>
+<indexterm><primary>RID 500</primary></indexterm>
+<indexterm><primary>well known RID</primary></indexterm>
+<indexterm><primary>rights and privileges</primary></indexterm>
+<indexterm><primary>root account</primary></indexterm>
+The RID 500 is the well known standard value of the default Administrator account. It is the RID
+that confers the rights and privileges that the Administrator account has on a Windows machine
+or domain. Under UNIX/Linux the equivalent is UID=0 (the root account).
+</para></note>
+
+<para>
+<indexterm><primary>without Administrator account</primary></indexterm>
+<indexterm><primary>equivalent rights and privileges</primary></indexterm>
+<indexterm><primary>Windows group account</primary></indexterm>
+<indexterm><primary>3.0.11</primary></indexterm>
+Releases of Samba version 3.0.11 and later make it possible to operate without an Administrator account
+provided equivalent rights and privileges have been established for a Windows user or a Windows
+group account.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+ <sect2>
+ <title>What Rights and Privileges Will Permit Windows Client Administration?</title>
+
+ <para>
+<indexterm><primary>domain global</primary></indexterm>
+<indexterm><primary>local group</primary></indexterm>
+<indexterm><primary>administrative rights</primary></indexterm>
+<indexterm><primary>Windows client</primary></indexterm>
+ When a Windows NT4 (or later) client joins a domain, the domain global <literal>Domain Admins</literal> group
+ is added to the membership of the local <literal>Administrators</literal> group on the client. Any user who is
+ a member of the domain global <literal>Domain Admins</literal> group will have administrative rights on the
+ Windows client.
+ </para>
+
+ <para>
+<indexterm><primary>desirable solution</primary></indexterm>
+<indexterm><primary>administrative rights and privileges</primary></indexterm>
+<indexterm><primary>Power Users</primary></indexterm>
+<indexterm><primary>domain global user</primary></indexterm>
+<indexterm><primary>domain global group</primary></indexterm>
+ This is often not the most desirable solution because it means that the user will have administrative
+ rights and privileges on domain servers also. The <literal>Power Users</literal> group on Windows client
+ workstations permits local administration of the workstation alone. Any domain global user or domain global
+ group can be added to the membership of the local workstation group <literal>Power Users</literal>.
+ </para>
+
+ <para>
+<indexterm><primary>Nested Group Support</primary></indexterm>
+<indexterm><primary>add domain users and groups to a local group</primary></indexterm>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>Windows workstation.</primary></indexterm>
+ See <link linkend="nestedgrpmgmgt">Nested Group Support</link> for an example of how to add domain users
+ and groups to a local group that is on a Windows workstation. The use of the <command>net</command>
+ command permits this to be done from the Samba server.
+ </para>
+
+ <para>
+<indexterm><primary>cmd</primary></indexterm>
+<indexterm><primary>cmd shell</primary></indexterm>
+<indexterm><primary>net</primary><secondary>localgroup</secondary></indexterm>
+ Another way this can be done is to log onto the Windows workstation as the user
+ <literal>Administrator</literal>, then open a <command>cmd</command> shell, then execute:
+<screen>
+&dosprompt; net localgroup administrators /add <userinput>domain_name\entity</userinput>
+</screen>
+ where <literal>entity</literal> is either a domain user or a domain group account name.
+ </para>
+
+ </sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml b/docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml
new file mode 100644
index 0000000000..73b092f7f0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-SWAT.xml
@@ -0,0 +1,640 @@
+<?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: The Samba Web Administration Tool</title>
+
+<para>
+<indexterm><primary>configuration tool</primary></indexterm>
+<indexterm><primary>SWAT</primary></indexterm>
+<indexterm><primary>Web-based configuration</primary></indexterm>
+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 allows 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 networkwide MS Windows network password management.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+<indexterm><primary>internetworking super daemon</primary></indexterm>
+SWAT is a facility that is part of the Samba suite. The main executable is called
+<command>swat</command> and is invoked by the internetworking super daemon.
+See <link linkend="xinetd">appropriate section</link> for details.
+</para>
+
+<para>
+<indexterm><primary>man</primary></indexterm>
+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>
+<indexterm><primary>documentation</primary></indexterm>
+<indexterm><primary>configuration files</primary></indexterm>
+<indexterm><primary>internal ordering</primary></indexterm>
+Some network administrators 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 writes 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>
+<indexterm><primary>stripped of comments</primary></indexterm>
+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 nondefault settings will be written to the file.
+</para></note>
+
+</sect1>
+
+<sect1>
+<title>Guidelines and Technical Tips</title>
+
+<para>
+<indexterm><primary>internationalization support</primary></indexterm>
+This section aims to unlock the dark secrets behind how SWAT may be made to work,
+how it can be made more secure, and how to solve internationalization support problems.
+</para>
+
+<sect2>
+<title>Validate SWAT Installation</title>
+
+<para>
+<indexterm><primary>SWAT binary support</primary></indexterm>
+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, but several Linux distributions do not install SWAT by default,
+even though they do ship an installable binary support package containing SWAT
+on the distribution media.
+</para>
+
+<para>
+<indexterm><primary>swat</primary></indexterm>
+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>
+<indexterm><primary>inetd</primary></indexterm>
+<indexterm><primary>xinetd</primary></indexterm>
+Finally, when you are sure that SWAT has been fully installed, please check that SWAT
+is enabled in the control file for the internetworking super-daemon (inetd or xinetd)
+that is used on your operating system platform.
+</para>
+
+<sect3>
+<title>Locating the <command>SWAT</command> File</title>
+
+<para>
+<indexterm><primary>/usr/local/samba/bin</primary></indexterm>
+<indexterm><primary>/usr/sbin</primary></indexterm>
+<indexterm><primary>/opt/samba/bin</primary></indexterm>
+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:</para>
+<para><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 dependent 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 of methods that may be used to locate the <command>swat</command> binary file.
+The following methods may be helpful.
+</para>
+
+<para>
+<indexterm><primary>swat</primary></indexterm>
+<indexterm><primary>operating system search path</primary></indexterm>
+<indexterm><primary>swat command-line options</primary></indexterm>
+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 is 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 in a similar location.
+</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>
+<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>
+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>
+<indexterm><primary>swat</primary></indexterm>
+<indexterm><primary>/usr/sbin</primary></indexterm>
+<indexterm><primary>/usr/share/samba/swat</primary></indexterm>
+<indexterm><primary>/usr/local/samba/swat</primary></indexterm>
+Both of the previous 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>
+<indexterm><primary>SWAT permission allowed</primary></indexterm>
+<indexterm><primary>password change facility</primary></indexterm>
+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>, and
+<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>, and <guibutton>PASSWORD</guibutton>.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Securing SWAT through SSL</title>
+
+
+<para>
+<indexterm><primary>SSL</primary></indexterm>
+<indexterm><primary>swat</primary><secondary>security</secondary></indexterm>
+Many people have asked about how to set up 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>
+<indexterm><primary>OpenSSL</primary></indexterm>
+ Install OpenSSL.
+ </para></step>
+
+ <step><para>
+<indexterm><primary>certificate</primary></indexterm>
+<indexterm><primary>private key</primary></indexterm>
+ Generate certificate and private key.
+<indexterm><primary>/usr/bin/openssl</primary></indexterm>
+<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>
+<indexterm><primary>stunnel</primary></indexterm>
+ 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>
+<indexterm><primary>msg file</primary></indexterm>
+<indexterm><primary>Japanese</primary></indexterm>
+<indexterm><primary>French</primary></indexterm>
+<indexterm><primary>English</primary></indexterm>
+The name of the <command>msg</command> file is the same as the language ID sent by the browser. For
+example, <emphasis>en</emphasis> means English, <emphasis>ja</emphasis> means Japanese, <emphasis>fr</emphasis> means French.
+</para>
+
+<para>
+<indexterm><primary>locale</primary></indexterm>
+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>
+<indexterm><primary>msg</primary></indexterm>
+and so on. If you find a mistake or create a new <command>msg</command> file, please email it
+to us so we will consider it in the next release of Samba. The <command>msg</command> file should be encoded in UTF-8.
+</para>
+
+<para>
+<indexterm><primary>UTF-8 encoding</primary></indexterm>
+Note that if you enable this feature and the <smbconfoption name="display charset"/> is not
+matched to your browser's 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 tool that may 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 Samba3-HOWTO (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
+because it runs SWAT without authentication and with full administrative ability. It 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 exposes 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 affect a currently configured share, simply click on the pull-down button between the
+<guibutton>Choose Share</guibutton> and the <guibutton>Delete Share</guibutton> buttons and
+select the share you wish to operate on. 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 and
+select the printer you wish to operate on. 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 of 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
+because 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 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;, and &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
+are continually spawned. The auto-refresh facility allows you to track the changing
+conditions with minimal effort.
+</para>
+
+<para>
+Finally, 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>
+The view page allows you to view the optimized &smb.conf; file and, if you are
+particularly masochistic, permits 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. You can also use
+this tool to change a local password for a user account.
+</para>
+
+<para>
+When logged in as a non-root account, the user must 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-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml b/docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml
new file mode 100644
index 0000000000..4d79895985
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-SecureLDAP.xml
@@ -0,0 +1,405 @@
+<?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">
+<chapterinfo>
+ &author.ghenry;
+ <pubdate>July 8, 2005</pubdate>
+</chapterinfo>
+<title>LDAP and 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>
+<indexterm><primary>ACL</primary></indexterm>
+ Up until now, we have discussed the straightforward 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>
+<indexterm><primary>RFC 2830</primary></indexterm>
+ <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">RFC 2830</ulink>; <emphasis>Lightweight Directory Access Protocol (v3):
+ Extension for Transport Layer Security.</emphasis>
+ </para>
+
+ <para>
+<indexterm><primary>X.509 certificates</primary></indexterm>
+ 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>
+<indexterm><primary>DN</primary></indexterm>
+<indexterm><primary>CN</primary></indexterm>
+<indexterm><primary>FQDN</primary></indexterm>
+ 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>
+<indexterm><primary>Certificate Authority</primary><see>CA</see></indexterm>
+ 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>
+<indexterm><primary>OpenSSL</primary></indexterm>
+ 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 recognized 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
+ horse's 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>, in 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>
+ 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;
+&rootprompt; 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 Security, 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 &lt;&gt; 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 Security, 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 Fully 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-xml/Samba3-HOWTO/TOSHARG-Securing.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Securing.xml
new file mode 100644
index 0000000000..21218ea9da
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Securing.xml
@@ -0,0 +1,448 @@
+<?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>
+<indexterm><primary>security</primary></indexterm>
+<indexterm><primary>direct internet access</primary></indexterm>
+<indexterm><primary>firewall</primary></indexterm>
+<indexterm><primary>private network</primary></indexterm>
+<indexterm><primary>barriers</primary></indexterm>
+<indexterm><primary>deterents</primary></indexterm>
+<indexterm><primary>secured networks</primary></indexterm>
+The information contained in this chapter applies in general to all Samba installations. Security is
+everyone's concern in the information technology world. A surprising number of Samba servers are being
+installed on machines that have direct internet access, thus security is made more critical than it would have been had the
+server been located behind a firewall and on a private network. Paranoia regarding server security is causing
+some network administrators to insist on the installation of robust firewalls even on servers that are located
+inside secured networks. This chapter provides information to assist the administrator who understands
+how to create the needed barriers and deterents against <quote>the enemy</quote>, no matter where [s]he may
+come from.
+</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>
+<indexterm><primary>moderately secure</primary></indexterm>
+<indexterm><primary>perimeter firewall</primary></indexterm>
+<indexterm><primary>host security</primary></indexterm>
+<indexterm><primary>Samba security</primary></indexterm>
+There are three levels at which security principles 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>
+<indexterm><primary>host-based protection</primary></indexterm>
+<indexterm><primary>interface-based exclusion</primary></indexterm>
+<indexterm><primary>resource-based exclusion</primary></indexterm>
+Samba can be secured from connections that originate from outside the local network. This can 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$]"/> autoshare. The <smbconfsection
+name="[IPC$]"/> share is used for browsing purposes as well as to establish TCP/IP connections.
+</para>
+
+<para>
+<indexterm><primary>Access Control Entries</primary><see>ACE</see></indexterm>
+<indexterm><primary>ACL</primary></indexterm>
+<indexterm>controls<primary></primary></indexterm>
+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 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, 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>
+<indexterm><primary>outside threat</primary></indexterm>
+<indexterm><primary>insecure</primary></indexterm>
+<indexterm><primary>Internet</primary></indexterm>
+ In many installations of Samba, the greatest threat comes from outside
+ your immediate network. By default, Samba accepts 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>
+<indexterm><primary>allow access</primary></indexterm>
+<indexterm><primary>range of hosts</primary></indexterm>
+ 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
+ allow access to your server only from a specific range of hosts. An example might be:
+ <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>
+<indexterm><primary>localhost</primary></indexterm>
+<indexterm><primary>private networks</primary></indexterm>
+<indexterm><primary>called name</primary></indexterm>
+ The above will allow SMB connections only 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 <literal>not listening on called name</literal> 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:
+ <smbconfblock>
+ <smbconfoption name="valid users">@smbusers, jacko</smbconfoption>
+ </smbconfblock>
+ </para>
+
+ <para>
+<indexterm><primary>smbusers</primary></indexterm>
+ This restricts all server access either to the user <emphasis>jacko</emphasis>
+ or to members of the system group <emphasis>smbusers</emphasis>.
+ </para>
+
+ </sect2>
+
+ <sect2>
+
+ <title>Using Interface Protection</title>
+
+ <para>
+<indexterm><primary>network interface</primary></indexterm>
+<indexterm><primary>accept connections</primary></indexterm>
+<indexterm><primary>Internet</primary></indexterm>
+ By default, Samba accepts connections on any network interface that
+ it finds on your system. That means if you have an 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:
+ <smbconfblock>
+ <smbconfoption name="interfaces">eth* lo</smbconfoption>
+ <smbconfoption name="bind interfaces only">yes</smbconfoption>
+ </smbconfblock>
+ </para>
+
+ <para>
+<indexterm><primary>interfaces</primary></indexterm>
+<indexterm><primary>loopback interface</primary></indexterm>
+<indexterm><primary>Ethernet adapters</primary></indexterm>
+<indexterm><primary>listen for connections</primary></indexterm>
+ This tells Samba to listen for connections only on interfaces with a name starting with
+ <constant>eth</constant> such as <constant>eth0</constant> or <constant>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>
+<indexterm><primary>PPP</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>cracker</primary></indexterm>
+<indexterm><primary>confirm address</primary></indexterm>
+ 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 [s]he will get a TCP connection refused reply. In that case, no Samba code
+ is run at all, because the operating system has been told not to pass connections from that interface to any
+ Samba process. However, the refusal helps a would-be cracker by confirming that the IP address provides
+ valid active services.
+ </para>
+
+ <para>
+<indexterm><primary>ignore connection</primary></indexterm>
+<indexterm><primary>refusing connection</primary></indexterm>
+<indexterm><primary>exploitation</primary></indexterm>
+<indexterm><primary>denial of service</primary></indexterm>
+<indexterm><primary>firewall</primary></indexterm>
+ A better response would be to ignore the connection (from, for example, ppp0) altogether. The
+ advantage of ignoring the connection attempt, as compared with refusing it, is that it foils those who
+ probe an interface with the sole intention of finding valid IP addresses for later use in exploitation
+ or denial of service attacks. This method of dealing with potential malicious activity demands the
+ use of appropriate firewall mechanisms.
+ </para>
+
+ </sect2>
+
+ <sect2 id="firewallports">
+ <title>Using a Firewall</title>
+
+ <para>
+<indexterm><primary>deny access</primary></indexterm>
+<indexterm><primary>exposed</primary></indexterm>
+<indexterm><primary>firewall active</primary></indexterm>
+ 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:
+<indexterm><primary>Port 135/TCP</primary></indexterm>
+<indexterm><primary>Port 137/UDP</primary></indexterm>
+<indexterm><primary>Port 138/UDP</primary></indexterm>
+<indexterm><primary>Port 139/TCP</primary></indexterm>
+<indexterm><primary>Port 445/TCP</primary></indexterm>
+ </para>
+
+ <simplelist>
+ <member>Port 135/TCP - used by smbd</member>
+ <member>Port 137/UDP - used by nmbd</member>
+ <member>Port 138/UDP - used by nmbd</member>
+ <member>Port 139/TCP - used by smbd</member>
+ <member>Port 445/TCP - used by smbd</member>
+ </simplelist>
+
+ <para>
+<indexterm><primary>firewall setups</primary></indexterm>
+ The last one is important because many older firewall setups may not be aware of it, given that this port
+ was only added to the protocol in recent years.
+ </para>
+
+ <para>
+<indexterm><primary>configuring a firewall</primary></indexterm>
+<indexterm><primary>high order ports</primary></indexterm>
+<indexterm><primary>block incoming packets</primary></indexterm>
+ When configuring a firewall, the high order ports (1024-65535) are often used for outgoing connections and
+ therefore should be permitted through the firewall. It is prudent to block incoming packets on the high order
+ ports except for established connections.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Using IPC$ Share-Based Denials </title>
+
+ <para>
+<indexterm><primary>IPC$</primary></indexterm>
+<indexterm><primary>deny</primary></indexterm>
+<indexterm><primary>security hole</primary></indexterm>
+ If the above methods are not suitable, then you could also place a more specific deny on the IPC$ share that
+ is used in the recently discovered security hole. This allows you to offer access to other shares while
+ denying access to IPC$ from potentially untrustworthy hosts.
+ </para>
+
+ <para>
+ To do this you could use:
+ <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>
+<indexterm><primary>IPC$</primary></indexterm>
+<indexterm><primary>protection against attackers</primary></indexterm>
+<indexterm><primary>valid username/password</primary></indexterm>
+ This instructs Samba that IPC$ connections are not allowed from anywhere except the two listed network
+ addresses (localhost and the 192.168.115 subnet). Connections to other shares are still allowed. Because the
+ IPC$ share is the only share that is always accessible anonymously, this provides some level of protection
+ against attackers who do not know a valid username/password for your host.
+ </para>
+
+ <para>
+<indexterm><primary>access denied</primary></indexterm>
+<indexterm><primary>IPC$</primary></indexterm>
+<indexterm><primary>browse shares</primary></indexterm>
+ If you use this method, then clients will be given an <literal>`access denied'</literal> 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 for some reason you cannot use one of the other methods
+ just discussed.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>NTLMv2 Security</title>
+
+ <para>
+<indexterm><primary>NTLMv2</primary></indexterm>
+ 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 to 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 negotiated.
+ </para>
+ </sect2>
+</sect1>
+
+<sect1>
+<title>Upgrading Samba</title>
+
+<para>
+<indexterm><primary>updates</primary></indexterm>
+<indexterm><primary>important announcements</primary></indexterm>
+<indexterm><primary>security vulnerability</primary></indexterm>
+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 promptly 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 Samba and host platform configurations were really as intuitive as one might like them to be, this
+chapter would not be necessary. Security issues are often vexing for a support person to resolve, not because
+of the complexity of the problem, but because 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. Linux vendors tend to install 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 <link linkend="firewallports">the Using a
+ Firewall</link> section.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Why Can Users Access Other Users' Home Directories?</title>
+
+ <para>
+ <quote>
+<indexterm><primary>mapping home directory</primary></indexterm>
+<indexterm><primary>own home directory</primary></indexterm>
+ 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>
+<indexterm><primary>security flaw</primary></indexterm>
+<indexterm><primary>defined shares</primary></indexterm>
+ 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 on to the UNIX box, except that it only allows such views onto the file
+ system as are allowed by the defined shares.
+ </para>
+
+ <para>
+<indexterm><primary>UNIX home directories</primary></indexterm>
+<indexterm><primary>permissions</primary></indexterm>
+ If your UNIX home directories are set up so that one user can happily <command>cd</command>
+ into another user's directory and execute <command>ls</command>, the UNIX security solution is to change file
+ permissions on the user's home directories so that the <command>cd</command> and <command>ls</command> are denied.
+ </para>
+
+ <para>
+<indexterm><primary>security policies</primary></indexterm>
+<indexterm><primary>permissions</primary></indexterm>
+ Samba tries very hard not to second guess the UNIX administrator's 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-xml/Samba3-HOWTO/TOSHARG-ServerType.xml b/docs-xml/Samba3-HOWTO/TOSHARG-ServerType.xml
new file mode 100644
index 0000000000..8aea1775e3
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-ServerType.xml
@@ -0,0 +1,833 @@
+<?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>
+<indexterm><primary>migrate</primary></indexterm>
+<indexterm><primary>security mode</primary></indexterm>
+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 the 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>
+This 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 toward 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>
+<indexterm><primary>UNIX</primary><secondary>server</secondary></indexterm>
+<indexterm><primary>interoperability</primary></indexterm>
+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 the features mentioned in this chapter?
+</para>
+
+<itemizedlist>
+ <listitem><para>
+ <indexterm><primary>domain</primary><secondary>controller</secondary></indexterm>
+ Samba-3 can replace an MS Windows NT4 domain controller.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>active directory</primary></indexterm>
+ Samba-3 offers excellent interoperability with MS Windows NT4-style
+ domains as well as natively with Microsoft Active Directory domains.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>interdomain</primary><secondary>trustrs</secondary></indexterm>
+ Samba-3 permits full NT4-style interdomain trusts.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>authentication</primary></indexterm>
+ <indexterm><primary>security</primary><secondary>modes</secondary></indexterm>
+ Samba has security modes that permit more flexible authentication
+ than is possible with MS Windows NT4 domain controllers.
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>account</primary><secondary>database</secondary><tertiary>backends</tertiary></indexterm>
+ <indexterm><primary>encrypted</primary></indexterm>
+ Samba-3 permits use of multiple concurrent account database backends.
+ (Encrypted passwords that are stored in the account database are in
+ formats that are unique to Windows networking).
+ </para></listitem>
+
+ <listitem><para>
+ <indexterm><primary>replicated</primary></indexterm>
+ The account 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 types of servers:
+</para>
+
+<itemizedlist>
+ <listitem><para>Domain Controller</para>
+ <itemizedlist>
+ <listitem><para>Primary Domain Controller (PDC)</para></listitem>
+ <listitem><para>Backup Domain Controller (BDC)</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>Standalone Server</para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>domain</primary><secondary>control</secondary></indexterm>
+<indexterm><primary>domain</primary><secondary>member</secondary></indexterm>
+<indexterm><primary>domain control</primary><secondary>primary</secondary></indexterm>
+<indexterm><primary>domain control</primary><secondary>backup</secondary></indexterm>
+The chapters covering domain control (<link linkend="samba-pdc">Domain Control</link>),
+backup domain control (<link linkend="samba-bdc">Backup Domain Control</link>), and
+domain membership (<link linkend="domain-member">Domain Membership</link>) provide
+pertinent information regarding Samba configuration for each of these server roles.
+You are strongly encouraged to become intimately familiar with these chapters because
+they lay the foundation for deployment of Samba domain security.
+</para>
+
+<para>
+<indexterm><primary>standalone</primary></indexterm>
+A Standalone server is autonomous in respect of the source of its account backend.
+Refer to <link linkend="StandAloneServer">Standalone Servers</link> to gain a wider appreciation
+of what is meant by a server being configured as a <emphasis>standalone</emphasis> server.
+</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>
+<indexterm><primary>Server Message Block</primary><see>SMB</see></indexterm>
+<indexterm><primary>Common Internet Filesystem</primary><see>CIFS</see></indexterm>
+Microsoft Windows networking uses a protocol that was originally called the Server Message Block (SMB)
+protocol. Since some time around 1996 the protocol has been better known as the Common Internet Filesystem
+(CIFS) protocol.
+</para>
+
+<para>
+<indexterm><primary>security levels</primary></indexterm>
+<indexterm><primary>security modes</primary></indexterm>
+<indexterm><primary>user-level</primary></indexterm>
+<indexterm><primary>share-level</primary></indexterm>
+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 MS Windows
+NT4/200x servers. In 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 of the security levels <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 informs the client, at the time of a session setup, the security level the server 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>
+
+<para>
+The term <literal>client</literal> refers to all agents whether it is a Windows workstation, a Windows server,
+another Samba server, or any vanilla SMB or CIFS client application (e.g., <command>smbclient</command>) that
+make use of services provided by an SMB/CIFS server.
+</para>
+
+<sect2>
+<title>User Level Security</title>
+
+<para>
+<indexterm><primary>user-level</primary></indexterm>
+We describe user-level security first because its simpler. In user-level security, the client sends 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>
+<indexterm><primary>credentials</primary></indexterm>
+If the server accepts the username/password credentials, the client expects to be able to mount shares (using
+a <emphasis>tree connection</emphasis>) without further specifying a password. It expects that all access
+rights will be as the username/password credentials set that was specified in the initial <emphasis>session
+setup</emphasis>.
+</para>
+
+<para>
+<indexterm><primary>session setup</primary></indexterm>
+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>
+
+<para>
+<indexterm><primary>LanManager</primary></indexterm>
+<indexterm><primary>case-preserving</primary></indexterm>
+<indexterm><primary>case-insensitive</primary></indexterm>
+<indexterm><primary>upper-case</primary></indexterm>
+<indexterm><primary>lower-case</primary></indexterm>
+Windows networking user account names are case-insensitive, meaning that upper-case and lower-case characters
+in the account name are considered equivalent. They are said to be case-preserving, but not case significant.
+Windows and LanManager systems previous to Windows NT version 3.10 have case-insensitive passwords that were
+not necessarilty case-preserving. All Windows NT family systems treat passwords as case-preserving and
+case-sensitive.
+</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>
+<indexterm><primary>share-level</primary></indexterm>
+<indexterm><primary>mount</primary></indexterm>
+In share-level security, the client authenticates itself separately for each share. It sends a password along
+with each tree connection request (share mount), but 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, the SMB server is not 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, think in terms of MS Windows 9x/Me where you 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 request 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
+issues a tree connection request, 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>
+
+<para>
+<indexterm><primary>name service switch</primary><see>NSS</see></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>nsswitch.conf</primary></indexterm>
+Where the list of possible user names is not provided, Samba makes a UNIX system call to find the user
+account that has a password that matches the one provided from the standard account database. On a system that
+has no name service switch (NSS) facility, such lookups will be from the <filename>/etc/passwd</filename>
+database. On NSS enabled systems, the lookup will go to the libraries that have been specified in the
+<filename>nsswitch.conf</filename> file. The entries in that file in which the libraries are specified are:
+<screen>
+passwd: files nis ldap
+shadow: files nis ldap
+group: files nis ldap
+</screen>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>/etc/group</primary></indexterm>
+<indexterm><primary>NIS</primary></indexterm>
+In the example shown here (not likely to be used in practice) the lookup will check
+<filename>/etc/passwd</filename> and <filename>/etc/group</filename>, if not found it will check NIS, then
+LDAP.
+</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</primary><secondary>controllers</secondary></indexterm>
+<indexterm><primary>security</primary><secondary>controllers</secondary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>logon</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+Domain security provides a mechanism for storing all user and group accounts in a central, shared, account
+repository. The centralized account repository is shared between domain (security) controllers. Servers that
+act as domain controllers provide authentication and validation services to all machines that participate in
+the security context for the domain. A primary domain controller (PDC) is a server that is responsible for
+maintaining the integrity of the security account database. Backup domain controllers (BDCs) provide only domain
+logon and authentication services. Usually, BDCs will answer network logon requests more responsively than
+will a PDC.
+</para>
+
+<para>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>trust account</primary></indexterm>
+<indexterm><primary>trust</primary><secondary>account</secondary></indexterm>
+<indexterm><primary>domain</primary><secondary>security</secondary></indexterm>
+<indexterm><primary>domain</primary><secondary>controller</secondary></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,
+even when it is in fact acting as a domain controller. All machines that participate in domain security must
+have a machine account in the security database.
+</para>
+
+<para>
+<indexterm><primary>account</primary><secondary>database</secondary></indexterm>
+<indexterm><primary>machine</primary><secondary>account</secondary></indexterm>
+<indexterm><primary>NetBIOS</primary><secondary>name</secondary></indexterm>
+<indexterm><primary>NetBIOS</primary></indexterm>
+Within the domain security environment, the underlying security architecture uses user-level security. Even
+machines that are domain members must authenticate on startup. The machine account consists of an account
+entry in the accounts database, the name of which is the NetBIOS name of the machine and of which the password
+is randomly generated and known to both the domain controllers and the member machine. If the machine account
+cannot be validated during startup, users will not be able to log on to the domain using this machine because
+it cannot be trusted. The machine account is referred to as a machine trust account.
+</para>
+
+<para>
+There are three possible domain member configurations:
+</para>
+
+<orderedlist>
+ <listitem><para>Primary domain controller (PDC) - of which there is one per domain.</para></listitem>
+ <listitem><para>Backup domain controller (BDC) - of which there can be any number per domain.</para></listitem>
+ <listitem><para>Domain member server (DMS) - of which there can be any number per domain.</para></listitem>
+</orderedlist>
+
+<para>
+<indexterm><primary>DMS</primary></indexterm>
+We will discuss each of these in separate chapters. For now, we are most interested in basic DMS
+configuration.
+</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:
+<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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+Samba-2.2.4 and later Samba 2.2.x series releases can autojoin 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>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
+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>
+<indexterm><primary>invalid shell</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>/bin/false</primary></indexterm>
+Use of this mode of authentication requires there to be a standard UNIX account for each user in order to
+assign a UID once the account has been authenticated by the Windows domain controller. 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. The best way to allocate an invalid shell to a user account is to
+set the shell to the file <filename>/bin/false</filename>.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+Domain controllers can be located anywhere that is convenient. The best advice is to have a BDC on every
+physical network segment, and if the PDC is on a remote network segment the use of WINS (see <link
+linkend="NetworkBrowsing">Network Browsing</link> for more information) is almost essential.
+</para>
+
+<para>
+An alternative to assigning UIDs to Windows users on a Samba member server is presented in <link
+linkend="winbind">Winbind</link>, <link linkend="winbind">Winbind: Use of Domain Accounts</link>.
+</para>
+
+<para>
+For more information regarding domain membership, <link linkend="domain-member">Domain Membership</link>.
+</para>
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>ADS Security Mode (User-Level Security)</title>
+
+<para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>native mode</primary></indexterm>
+Both Samba-2.2, and Samba-3 can join an Active Directory domain using NT4 style RPC based security. 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.
+</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>
+
+<para>
+<indexterm><primary>realm</primary></indexterm>
+<indexterm><primary>mixed mode</primary></indexterm>
+Sites that use Microsoft Windows active directory services (ADS) should be aware of the significance of the
+terms: <literal>native mode</literal> and <literal>mixed mode</literal> ADS operation. The term
+<literal>realm</literal> is used to describe a Kerberos-based security architecture (such as is used by
+Microsoft ADS).
+</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>
+<indexterm><primary>session setup</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+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 log into 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 parameter allows the Samba server to use another
+SMB server as the <smbconfoption name="password server"/>.
+</para>
+
+<para>
+<indexterm><primary>security level</primary></indexterm>
+<indexterm><primary>encryption</primary></indexterm>
+You should also note that at the start of all this, when 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
+user mode 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>
+<indexterm><primary>password server</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+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>
+<indexterm><primary>bogus</primary></indexterm>
+<indexterm><primary>lockout</primary></indexterm>
+The downside of this mode of configuration is 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 bogus username and password pair, then an alternative mode of
+identification or validation is used. Where a site uses password lockout, 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 plaintext or encrypted, but
+not both in the same authentication request.
+</para>
+
+<para>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+<indexterm><primary>encrypted</primary></indexterm>
+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 uppercase,
+ 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 "magic" 8-byte value.
+ The resulting 16 bytes form the LanMan hash.
+ </para></listitem>
+</itemizedlist>
+
+<para>
+<indexterm><primary>plain-text</primary><secondary>passwords</secondary></indexterm>
+MS Windows 95 pre-service pack 1 and 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>
+<indexterm><primary>cached</primary><secondary>password</secondary></indexterm>
+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 plaintext password. This means that when the registry parameter is changed
+to re-enable use of plaintext 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 plaintext password support in such clients.
+</para>
+
+<para>
+The following parameters can be used to work around the issue of Windows 9x/Me clients
+uppercasing usernames and passwords before transmitting them to the SMB server
+when using clear-text authentication:
+</para>
+
+
+<?latex \newpage ?>
+<smbconfblock>
+<smbconfoption name="password level"><replaceable>integer</replaceable></smbconfoption>
+<smbconfoption name="username level"><replaceable>integer</replaceable></smbconfoption>
+</smbconfblock>
+
+<para>
+By default Samba will convert to lowercase the username before attempting to lookup the user
+in the database of local system accounts. Because UNIX usernames conventionally
+only contain lowercase characters, the <smbconfoption name="username-level"/> parameter
+is rarely needed.
+</para>
+
+<para>
+<indexterm><primary>clear-text</primary></indexterm>
+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 uppercase 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 because 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 plaintext
+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,
+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 security 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>
+
+<para>
+Samba is a server regardless of which security mode is chosen. When Samba is used outside of a domain security
+context, it is best to leave the security mode at the default setting. By default Samba-3 uses user-mode
+security.
+</para>
+
+</sect2>
+
+<sect2>
+<title>What Makes Samba a Domain Controller?</title>
+
+<para>
+<indexterm><primary>server-mode</primary></indexterm>
+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>
+
+<sect2>
+<title>Stand-alone Server is converted to Domain Controller &smbmdash; Now User accounts don't work</title>
+
+<para><quote>
+When I try to log in to the DOMAIN, the eventlog shows <emphasis>tried credentials DOMAIN/username; effective
+credentials SERVER/username</emphasis>
+</quote></para>
+
+<para>
+Usually this is due to a user or machine account being created before the Samba server is configured to be a
+domain controller. Accounts created before the server becomes a domain controller will be
+<emphasis>local</emphasis> accounts and authenticated as what looks like a member in the SERVER domain, much
+like local user accounts in Windows 2000 and later. Accounts created after the Samba server becomes a domain
+controller will be <emphasis>domain</emphasis> accounts and will be authenticated as a member of the DOMAIN
+domain.
+</para>
+
+<para>
+This can be verified by issuing the command <command>pdbedit -L -v username</command>. If this reports DOMAIN
+then the account is a domain account, if it reports SERVER then the account is a local account.
+</para>
+
+<para>
+The easiest way to resolve this is to remove and recreate the account; however this may cause problems with
+established user profiles. You can also use <command>pdbedit -u username -I DOMAIN</command>. You may also
+need to change the User SID and Primary Group SID to match the domain.
+</para>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Speed.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Speed.xml
new file mode 100644
index 0000000000..18a15ae092
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Speed.xml
@@ -0,0 +1,327 @@
+<?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, so 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 and 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
+<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, 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 affect 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>
+
+<blockquote>
+<para>
+<indexterm><primary>Gentoo</primary></indexterm>
+<indexterm><primary>slow network</primary></indexterm>
+I am running Gentoo on my server and Samba 2.2.8a. Recently I changed kernel versions from
+<filename>linux-2.4.19-gentoo-r10</filename> to <filename>linux-2.4.20-wolk4.0s</filename>. 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>
+</blockquote>
+
+<para>
+The answer he was given is:
+</para>
+
+<blockquote>
+<para>
+<indexterm><primary>ifconfig</primary></indexterm>
+<indexterm><primary>framing error</primary></indexterm>
+<indexterm><primary>collisions</primary></indexterm>
+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>
+</blockquote>
+
+</sect1>
+
+<sect1>
+<title>Corrupt tdb Files</title>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>mbd kept spawning</primary></indexterm>
+<indexterm><primary>/var/locks/*.tdb</primary></indexterm>
+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 SMDB's (normally we average 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>
+<indexterm><primary>tdbbackup</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<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>
+<indexterm><primary>slow performance</primary></indexterm>
+A site reported experiencing very baffling symptoms with MYOB Premier opening and
+accessing its data files. Some operations on the file would take between 40 and
+45 seconds.
+</para>
+
+<para>
+<indexterm><primary>printer monitor</primary></indexterm>
+<indexterm><primary>pauses</primary></indexterm>
+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>
+<indexterm><primary>networks access</primary></indexterm>
+<indexterm><primary>printing now</primary></indexterm>
+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 Canon LBP-810 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 application at every step of the installation of other software
+process (we had to do this many times).
+</para>
+
+<para>
+Moral of the story: Check everything (other software included)!
+</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-StandAloneServer.xml b/docs-xml/Samba3-HOWTO/TOSHARG-StandAloneServer.xml
new file mode 100644
index 0000000000..895544ed22
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-StandAloneServer.xml
@@ -0,0 +1,341 @@
+<?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>Standalone Servers</title>
+
+<para>
+<indexterm><primary>standalone server</primary></indexterm>
+<indexterm><primary>not domain members</primary></indexterm>
+<indexterm><primary>minimum security control</primary></indexterm>
+Standalone servers are independent of domain controllers on the network.
+They are not domain members and function more like workgroup servers. In many
+cases a standalone 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>
+<indexterm><primary>secure</primary></indexterm>
+<indexterm><primary>insecure</primary></indexterm>
+Standalone 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>
+<indexterm><primary>read-only files</primary></indexterm>
+<indexterm><primary>share-mode</primary></indexterm>
+<indexterm><primary>read-only</primary></indexterm>
+<indexterm><primary>standalone server</primary></indexterm>
+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. Noone can write files to the server because it is legislatively
+important that all documents remain unaltered. A share-mode read-only standalone
+server is an ideal solution.
+</para>
+
+<para>
+<indexterm><primary>simplicity</primary></indexterm>
+<indexterm><primary>printers</primary></indexterm>
+<indexterm><primary>share-mode server</primary></indexterm>
+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 standalone server makes
+a great solution.
+</para>
+</sect1>
+
+<sect1>
+<title>Background</title>
+
+<para>
+<indexterm><primary>standalone server</primary></indexterm>
+<indexterm><primary>local authentication</primary></indexterm>
+<indexterm><primary>access control</primary></indexterm>
+The term <emphasis>standalone 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
+<emphasis>share</emphasis> mode or in <emphasis>user</emphasis> mode.
+</para>
+
+<para>
+<indexterm><primary>create user accounts</primary></indexterm>
+<indexterm><primary>no network logon service</primary></indexterm>
+<indexterm><primary>independent</primary></indexterm>
+No special action is needed other than to create user accounts. Standalone
+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 he or she uses will
+be translated (mapped) locally on the standalone server to a locally known
+user name. There are several ways this can be done.
+</para>
+
+<para>
+<indexterm><primary>local authentication database</primary></indexterm>
+<indexterm><primary>SMB</primary></indexterm>
+<indexterm><primary>not domain member</primary></indexterm>
+Samba tends to blur the distinction a little in defining
+a standalone 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>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>UNIX-user database</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>/etc/shadow</primary></indexterm>
+<indexterm><primary>local smbpasswd file</primary></indexterm>
+<indexterm><primary>LDAP backend</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+Through the use of Pluggable Authentication Modules (PAM) (see <link linkend="pam">the chapter on PAM</link>)
+and the name service switcher (NSS), 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>
+<indexterm><primary>inspire simplicity</primary></indexterm>
+<indexterm><primary>complexity</primary></indexterm>
+<link linkend="simplynice">The example 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>
+<indexterm><primary>read-only</primary></indexterm>
+<indexterm><primary>reference documents</primary></indexterm>
+<indexterm><primary>/export</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+Configuration of a read-only data server that everyone can access is very simple. By default, all shares are
+read-only, unless set otherwise in the &smb.conf; file. <link linkend="simplynice">The example - Reference
+Documentation Server</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>
+
+<example id="simplynice">
+<title>smb.conf for Reference Documentation Server</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<blockquote>
+<attribution>Mark Twain</attribution>
+<para>
+I would have spoken more briefly, if I'd had more time to prepare.
+</para>
+</blockquote>
+
+<para>
+<indexterm><primary>password backend</primary></indexterm>
+<indexterm><primary>guest</primary></indexterm>
+<indexterm><primary>unprivileged account names</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+In <link linkend="simplynice">this example</link>, the machine name is set to &example.server.samba;, and 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 course make use of it.
+</para>
+
+<para>
+A US Air Force Colonel was renowned for saying: <quote>Better is the enemy of good enough!</quote> There are often
+sound reasons for avoiding complexity as well as for avoiding a technically perfect solution. Unfortunately,
+many network administrators still need to learn the art of doing just enough to keep out of trouble.
+</para>
+
+</sect2>
+
+<sect2 id="SimplePrintServer">
+<title>Central Print Serving</title>
+
+<para>
+<indexterm><primary>simple print server</primary></indexterm>
+<indexterm><primary>tools</primary></indexterm>
+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>
+<indexterm><primary>print server</primary></indexterm>
+<indexterm><primary>/var/spool/samba</primary></indexterm>
+<indexterm><primary>anonymous</primary></indexterm>
+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 to enable anonymous printing.
+</para>
+
+<itemizedlist>
+<title>Enabling Anonymous Printing</title>
+ <listitem><para>
+<indexterm><primary>guest account</primary></indexterm>
+<indexterm><primary>nobody</primary></indexterm>
+<indexterm><primary>testparm</primary></indexterm>
+ 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>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+ Make sure that this account exists in your system password
+ database (<filename>/etc/passwd</filename>).
+ </para>
+
+ <para>
+<indexterm><primary>set a password</primary></indexterm>
+<indexterm><primary>lock password</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+ It is a good idea either to set a password on this account, or else to lock it
+ from UNIX use. Assuming that the guest account is called <literal>pcguest</literal>,
+ it can be locked by executing:
+<screen>
+&rootprompt; passwd -l pcguest
+</screen>
+ The exact command may vary depending on your UNIX/Linux distribution.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>directory</primary></indexterm>
+<indexterm><primary>guest account</primary></indexterm>
+<indexterm><primary>available</primary></indexterm>
+<indexterm><primary>mkdir</primary></indexterm>
+<indexterm><primary>chown</primary></indexterm>
+<indexterm><primary>chmod</primary></indexterm>
+ 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 Anonymous Printing example</link>.
+</para>
+
+<example id="AnonPtrSvr">
+<title>&smb.conf; for Anonymous Printing</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+
+<note><para>
+<indexterm><primary>MIME</primary><secondary>raw</secondary></indexterm>
+<indexterm><primary>raw printing</primary></indexterm>
+<indexterm><primary>/etc/mime.conv</primary></indexterm>
+<indexterm><primary>/etc/mime.types</primary></indexterm>
+<indexterm><primary>CUPS print filters</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-printing">CUPS Printing Support</link>, <link linkend="cups-raw">Explicitly Enable raw Printing
+for application/octet-stream</link>.
+</para></note>
+
+<para>
+<indexterm><primary>CUPS libarary API</primary></indexterm>
+<indexterm><primary>no printcap file</primary></indexterm>
+<indexterm><primary>PDF filter</primary></indexterm>
+<indexterm><primary>printcap name</primary></indexterm>
+The example in <link linkend="AnonPtrSvr">the Anonymous Printing example</link> uses CUPS for direct printing
+via the CUPS libarary API. This means that all printers will be exposed to Windows users without need to
+configure a printcap file. If there is necessity to expose only a sub-set of printers, or to define a special
+type of printer (for example, a PDF filter) the <parameter>printcap name = cups</parameter> can be replaced
+with the entry <parameter>printcap name = /etc/samba/myprintcap</parameter>. In this case the file specified
+should contain a list of the printer names that should be exposed to Windows network users.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+<indexterm><primary>greatest mistake</primary></indexterm>
+<indexterm><primary>configuration too complex</primary></indexterm>
+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-xml/Samba3-HOWTO/TOSHARG-Support.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Support.xml
new file mode 100644
index 0000000000..b970bc00f0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Support.xml
@@ -0,0 +1,163 @@
+<?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">
+
+<chapter lang="en-US">
+<title>Samba Support</title>
+
+<para>
+<indexterm><primary>support</primary></indexterm>
+One of the most difficult to answer questions in the information technology industry is, <quote>What is
+support?</quote>. That question irritates some folks, as much as common answers may annoy others.
+</para>
+
+<para>
+<indexterm><primary>customers</primary></indexterm>
+The most aggravating situation pertaining to support is typified when, as a Linux user, a call is made to
+an Internet service provider who, instead of listening to the problem to find a solution, blandly replies:
+<quote>Oh, Linux? We do not support Linux!</quote>. It has happened to me, and similar situations happen
+through-out the IT industry. Answers like that are designed to inform us that there are some customers
+that a business just does not want to deal with, and well may we feel the anguish of the rejection that
+is dished out.
+</para>
+
+<para>
+One way to consider support is to view it as consisting of the right answer, in the right place,
+at the right time, no matter the situation. Support is all that it takes to take away pain, disruption,
+inconvenience, loss of productivity, disorientation, uncertainty, and real or perceived risk.
+</para>
+
+<para>
+<indexterm><primary>provided services</primary></indexterm>
+<indexterm><primary>services provided</primary></indexterm>
+<indexterm><primary>customer expected</primary></indexterm>
+One of the forces that has become a driving force for the adoption of open source software is the fact that
+many IT businesses have provided services that have perhaps failed to deliver what the customer expected, or
+that have been found wanting for other reasons.
+</para>
+
+<para>
+<indexterm><primary>consumer expects</primary></indexterm>
+<indexterm><primary>problem resolution</primary></indexterm>
+In recognition of the need for needs satisfaction as the primary experience an information technology user or
+consumer expects, the information provided in this chapter may help someone to avoid an unpleasant experience
+in respect of problem resolution.
+</para>
+
+<para>
+<indexterm><primary>free support</primary></indexterm>
+<indexterm><primary>paid-for support</primary></indexterm>
+<indexterm><primary>commercial support</primary></indexterm>
+In the open source software arena there are two support options: free support and paid-for (commercial)
+support.
+</para>
+
+ <sect1>
+ <title>Free Support</title>
+
+ <para>
+<indexterm><primary>user groups</primary></indexterm>
+<indexterm><primary>mailing lists</primary></indexterm>
+<indexterm><primary>interactive help</primary></indexterm>
+<indexterm><primary>help</primary></indexterm>
+<indexterm><primary>mutual assistance</primary></indexterm>
+<indexterm><primary>assistance</primary></indexterm>
+ Free support may be obtained from friends, colleagues, user groups, mailing lists, and interactive help
+ facilities. An example of an interactive dacility is the Internet relay chat (IRC) channels that host user
+ supported mutual assistance.
+ </para>
+
+ <para>
+<indexterm><primary>mailing list</primary></indexterm>
+<indexterm><primary>deployment</primary></indexterm>
+<indexterm><primary>subscription</primary></indexterm>
+<indexterm><primary>IRC</primary></indexterm>
+<indexterm><primary>project</primary></indexterm>
+ The Samba project maintains a mailing list that is commonly used to discuss solutions to Samba deployments.
+ Information regarding subscription to the Samba mailing list can be found on the Samba <ulink
+ url="https://lists.samba.org/mailman/">web</ulink> site. The public mailing list that can be used to obtain
+ free, user contributed, support is called the <literal>samba</literal> list. The email address for this list
+ is at <literal>mail:samba@samba.org</literal>. Information regarding the Samba IRC channels may be found on
+ the Samba <ulink url="http://www.samba.org/samba.irc.html">IRC</ulink> web page.
+ </para>
+
+ <para>
+<indexterm><primary>free support</primary></indexterm>
+<indexterm><primary>qualified problem</primary></indexterm>
+<indexterm><primary>requesting payment</primary></indexterm>
+<indexterm><primary>professional support</primary></indexterm>
+ As a general rule, it is considered poor net behavior to contact a Samba Team member directly
+ for free support. Most active members of the Samba Team work exceptionally long hours to assist
+ users who have demonstrated a qualified problem. Some team members may respond to direct email
+ or telephone contact, with requests for assistance, by requesting payment. A few of the Samba
+ Team members actually provide professional paid-for Samba support and it is therefore wise
+ to show appropriate discretion and reservation in all direct contact.
+ </para>
+
+ <para>
+<indexterm><primary>bug report</primary></indexterm>
+<indexterm><primary>problem report</primary></indexterm>
+<indexterm><primary>code maintainer</primary></indexterm>
+ When you stumble across a Samba bug, often the quickest way to get it resolved is by posting
+ a bug <ulink url="https://bugzilla.samba.org/">report</ulink>. All such reports are mailed to
+ the responsible code maintainer for action. The better the report, and the more serious it is,
+ the sooner it will be dealt with. On the other hand, if the responsible person can not duplicate
+ the reported bug it is likely to be rejected. It is up to you to provide sufficient information
+ that will permit the problem to be reproduced.
+ </para>
+
+ <para>
+<indexterm><primary>purchase support</primary></indexterm>
+ We all recognize that sometimes free support does not provide the answer that is sought within
+ the time-frame required. At other times the problem is elusive and you may lack the experience
+ necessary to isolate the problem and thus to resolve it. This is a situation where is may be
+ prudent to purchase paid-for support.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Commercial Support</title>
+
+ <para>
+ There are six basic support oriented services that are most commonly sought by Samba sites:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>Assistance with network design</para></listitem>
+ <listitem><para>Staff Training</para></listitem>
+ <listitem><para>Assistance with Samba network deployment and installation</para></listitem>
+ <listitem><para>Priority telephone or email Samba configuration assistance</para></listitem>
+ <listitem><para>Trouble-shooting and diagnostic assistance</para></listitem>
+ <listitem><para>Provision of quality assured ready-to-install Samba binary packages</para></listitem>
+ </itemizedlist>
+
+ <para>
+<indexterm><primary>commercial support</primary></indexterm>
+<indexterm><primary>country of origin</primary></indexterm>
+ Information regarding companies that provide professional Samba support can be obtained by performing a Google
+ search, as well as by reference to the Samba <ulink
+ url="http://www.samba.org/samba/support.html">Support</ulink> web page. Companies who notify the Samba Team
+ that they provide commercial support are given a free listing that is sorted by the country of origin.
+ Multiple listings are permitted, however no guarantee is offered. It is left to you to qualify a support
+ provider and to satisfy yourself that both the company and its staff are able to deliver what is required of
+ them.
+ </para>
+
+ <para>
+<indexterm><primary>commercial support</primary></indexterm>
+ The policy within the Samba Team is to treat all commercial support providers equally and to show no
+ preference. As a result, Samba Team members who provide commercial support are lumped in with everyone else.
+ You are encouraged to obtain the services needed from a company in your local area. The open source movement
+ is pro-community; so do what you can to help a local business to prosper.
+ </para>
+
+ <para>
+<indexterm><primary>unsupported software</primary></indexterm>
+ Open source software support can be found in any quality, at any price and in any place you can
+ to obtain it. Over 180 companies around the world provide Samba support, there is no excuse for
+ suffering in the mistaken belief that Samba is unsupported software &smbmdash; it is supported.
+ </para>
+
+ </sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-TheNetCommand.xml b/docs-xml/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
new file mode 100644
index 0000000000..b2b3ebd5b1
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
@@ -0,0 +1,1916 @@
+<?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: The Net Command</title>
+
+<para>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>remote management</primary></indexterm>
+<indexterm><primary>command-line</primary></indexterm>
+<indexterm><primary>scripted control</primary></indexterm>
+The <command>net</command> command is one of the new features of Samba-3 and is an attempt to provide a useful
+tool for 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>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>network administrator's toolbox</primary></indexterm>
+<indexterm><primary>smbgroupedit</primary></indexterm>
+<indexterm><primary>rpcclient</primary></indexterm>
+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 has introduced tools, such as
+<command>smbgroupedit</command> and <command>rpcclient</command>, from which really useful capabilities 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 cannot 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>
+<indexterm><primary>standalone</primary></indexterm>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>DMS</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+ The tasks that follow the installation of a Samba-3 server, whether standalone or 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 standalone server and 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>
+<indexterm><primary>server type</primary></indexterm>
+<indexterm><primary>local UNIX groups</primary></indexterm>
+<indexterm><primary>mapped</primary></indexterm>
+<indexterm><primary>domain global group</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>access rights</primary></indexterm>
+<indexterm><primary>net</primary></indexterm>
+ 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 and 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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+<indexterm><primary>DMS</primary></indexterm>
+<indexterm><primary>security account</primary></indexterm>
+<indexterm><primary>domain authentication</primary></indexterm>
+<indexterm><primary>trust accounts</primary></indexterm>
+<indexterm><primary>net</primary></indexterm>
+ 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>
+<indexterm><primary>interdomain trusts</primary></indexterm>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>administrative duties</primary></indexterm>
+<indexterm><primary>user management</primary></indexterm>
+<indexterm><primary>group management</primary></indexterm>
+<indexterm><primary>share management</primary></indexterm>
+<indexterm><primary>printer management</primary></indexterm>
+<indexterm><primary>printer migration</primary></indexterm>
+<indexterm><primary>SID management</primary></indexterm>
+ The establishment of interdomain 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>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>man pages</primary></indexterm>
+ The overall 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 online UNIX man pages.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Administrative Tasks and Methods</title>
+
+ <para>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Distributed Computing Environment</primary><see>DCE</see></indexterm>
+<indexterm><primary>Remote Procedure Call</primary><see>RPC</see></indexterm>
+ 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 Distributed Computing Environment Remote Procedure Call (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</constant>, <constant>rpc</constant>, and
+ <constant>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>
+<indexterm><primary>Active Directory</primary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary></indexterm>
+<indexterm><primary>net</primary><secondary>ads</secondary></indexterm>
+<indexterm><primary>net</primary><secondary>rap</secondary></indexterm>
+<indexterm><primary>RAP</primary></indexterm>
+ As stated, 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 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>
+<indexterm><primary>net</primary></indexterm>
+<indexterm><primary>user management</primary></indexterm>
+<indexterm><primary>group management</primary></indexterm>
+ Samba's <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>
+<indexterm><primary>groups</primary></indexterm>
+<indexterm><primary>domain</primary><secondary>groups</secondary></indexterm>
+<indexterm><primary>local</primary><secondary>groups</secondary></indexterm>
+<indexterm><primary>domain user accounts</primary></indexterm>
+ 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>
+
+ <para>
+ Samba provides file and print services to Windows clients. The file system resources it makes available
+ to the Windows environment must, of necessity, be provided in a manner that is compatible with the
+ Windows networking environment. UNIX groups are created and deleted as required to serve operational
+ needs in the UNIX operating system and its file systems.
+ </para>
+
+ <para>
+ In order to make available to the Windows environment, Samba has a facility by which UNIX groups can
+ be mapped to a logical entity, called a Windows (or domain) group. Samba supports two types of Windows
+ groups, local and global. Global groups can contain as members, global users. This membership is
+ affected in the normal UNIX manner, but adding UNIX users to UNIX groups. Windows user accounts consist
+ of a mapping between a user SambaSAMAccount (logical entity) and a UNIX user account. Therefore,
+ a UNIX user is mapped to a Windows user (i.e., is given a Windows user account and password) and the
+ UNIX groups to which that user belongs, is mapped to a Windows group account. The result is that in
+ the Windows account environment that user is also a member of the Windows group account by virtue
+ of UNIX group memberships.
+ </para>
+
+ <para>
+ The following sub-sections that deal with management of Windows groups demonstrates the relationship
+ between the UNIX group account and its members to the respective Windows group accounts. It goes on to
+ show how UNIX group members automatically pass-through to Windows group membership as soon as a logical
+ mapping has been created.
+ </para>
+
+ <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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group</tertiary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group list</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc group list -Uroot%not24get
+Password:
+Domain Admins
+Domain Users
+Domain Guests
+Print Operators
+Backup Operators
+Replicator
+Domain Computers
+Engineers
+</screen>
+ </para>
+
+<?latex \newpage ?>
+ <para>
+ A Windows group account called <quote>SupportEngrs</quote> can be added by executing the following
+command:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group add</tertiary></indexterm>
+<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
+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>
+<indexterm><primary>POSIX</primary></indexterm>
+<indexterm><primary>smbldap-groupadd</primary></indexterm>
+<indexterm><primary>getent</primary></indexterm>
+ 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:
+<indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>list</tertiary></indexterm>
+<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>
+<indexterm><primary>mapped</primary></indexterm>
+<indexterm><primary>Windows groups</primary></indexterm>
+<indexterm><primary>system groups</primary></indexterm>
+<indexterm><primary>access controls</primary></indexterm>
+ 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>
+<indexterm><primary>access controls</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>locally known UID</primary></indexterm>
+ All file system (file and directory) access controls, within the file system of a UNIX/Linux server that is
+ hosting a Samba server, are implemented using a UID/GID identity tuple. Samba does not in any way override
+ or replace UNIX file system semantics. Thus it is necessary that all Windows networking operations that
+ access the file system 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. Note that the <command>net</command>
+ command does not call any RPC-functions here but directly accesses the passdb.
+ </para>
+
+ <para>
+<indexterm><primary>default mappings</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>Domain Users</primary></indexterm>
+<indexterm><primary>Domain Guests</primary></indexterm>
+<indexterm><primary>Windows group</primary></indexterm>
+<indexterm><primary>UNIX group</primary></indexterm>
+<indexterm><primary>mapping</primary></indexterm>
+ 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>
+<indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>modify</tertiary></indexterm>
+<indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>add</tertiary></indexterm>
+<indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>delete</tertiary></indexterm>
+ The operations that are permitted include: <constant>add</constant>, <constant>modify</constant>,
+ and <constant>delete</constant>. An example of each operation is shown here.
+ </para>
+
+ <note><para>
+ Commencing with Samba-3.0.23 Windows Domain Groups must be explicitly created. By default, all
+ UNIX groups are exposed to Windows networking as Windows local groups.
+ </para></note>
+
+ <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>
+ Supported mapping types are 'd' (domain global) and 'l' (domain local).
+ 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>
+ The deletion and addition operations affected only the logical entities known as Windows groups, or domain
+ groups. These operations are inert to UNIX system groups, meaning that they neither delete nor create UNIX
+ system groups. The mapping of a UNIX group to a Windows group makes the UNIX group available as Windows
+ groups so that files and folders on domain member clients (workstations and servers) can be given
+ domain-wide access controls for domain users and groups.
+ </para>
+
+ <para>
+ Two types of Windows groups can be created: <constant>domain (global)</constant> and <constant>local</constant>.
+ In the previous 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>
+ Supported mapping types are 'd' (domain global) and 'l' (domain local), a domain local group in Samba is
+ treated as local to the individual Samba server. Local groups can be used with Samba to enable multiple
+ nested group support.
+ </para>
+
+ </sect3>
+
+ <sect3>
+ <title>Deleting a Group Account</title>
+
+ <para>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group delete</tertiary></indexterm>
+ 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 at this time. 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 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>:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group rename</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc group rename SupportEngrs \
+ CustomerSupport -Uroot%not24get
+</screen>
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="grpmemshipchg">
+ <title>Manipulating Group Memberships</title>
+
+ <para>
+ Three operations can be performed regarding group membership. It is possible to (1) add Windows users
+ to a 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>
+ To avoid confusion, it makes sense to check group membership before attempting to make any 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group addmem</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group delmem</tertiary></indexterm>
+<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 are validated using
+ the <command>net rpc group</command> utility. Note the this contents of the UNIX/Linux group was shown
+ four paragraphs earlier. The Windows (domain) group membership is shown here:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group members</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc group members "Domain Users" -Uroot%not24get
+MIDEARTH\jht
+MIDEARTH\lct
+MIDEARTH\ajt
+MIDEARTH\met
+MIDEARTH\vlendecke
+</screen>
+ This express example shows 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 id="nestedgrpmgmgt">
+ <title>Nested Group Support</title>
+
+ <para>
+ It is possible in Windows (and now in Samba also) to create 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>
+
+ <sect3>
+ <title>Managing Nest Groups on Workstations from the Samba Server</title>
+
+ <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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group addmem</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc group addmem "Administrators" "Domain Users" \
+ -S WINPC032 -Uadministrator%secret
+</screen>
+ </para>
+
+ <para>
+ This can be scripted, and can therefore be performed as a user logs onto the domain from a Windows
+ workstation. Here is a simple example that shows how this can be done.
+ </para>
+
+ <procedure>
+ <title>Automating User Addition to the Workstation Power Users Group</title>
+
+ <step><para>
+ Create the script shown in <link linkend="autopoweruserscript"></link> and locate it in
+ the directory <filename>/etc/samba/scripts</filename>, named as <filename>autopoweruser.sh</filename>.
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group addmem</tertiary></indexterm>
+<indexterm><primary>autopoweruser.sh</primary></indexterm>
+<indexterm><primary>/etc/samba/scripts</primary></indexterm>
+ </para></step>
+
+<example id="autopoweruserscript">
+<title>Script to Auto-add Domain Users to Workstation Power Users Group</title>
+<screen>
+#!/bin/bash
+
+/usr/bin/net rpc group addmem "Power Users" "DOMAIN_NAME\$1" \
+ -UAdministrator%secret -S $2
+
+exit 0
+</screen>
+</example>
+
+ <step><para>
+ Set the permissions on this script to permit it to be executed as part of the logon process:
+<screen>
+&rootprompt; chown root:root /etc/samba/autopoweruser.sh
+&rootprompt; chmod 755 /etc/samba/autopoweruser.sh
+</screen>
+ </para></step>
+
+ <step><para>
+ Modify the &smb.conf; file so the <literal>NETLOGON</literal> stanza contains the parameters
+ shown in <link linkend="magicnetlogon">the Netlogon Example smb.conf file</link>.
+ </para></step>
+
+<example id="magicnetlogon">
+<title>A Magic Netlogon Share</title>
+<smbconfblock>
+<smbconfsection name="[netlogon]"/>
+<smbconfoption name="comment">Netlogon Share</smbconfoption>
+<smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption>
+<smbconfoption name="root preexec">/etc/samba/scripts/autopoweruser.sh %U %m</smbconfoption>
+<smbconfoption name="read only">Yes</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+ <step><para>
+ Ensure that every Windows workstation Administrator account has the same password that you
+ have used in the script shown in <link linkend="magicnetlogon">the Netlogon Example smb.conf
+ file</link>
+ </para></step>
+
+</procedure>
+
+ <para>
+ This script will be executed every time a user logs on to the network. Therefore every user will
+ have local Windows workstation management rights. This could of course be assigned using a group,
+ in which case there is little justification for the use of this procedure. The key justification
+ for the use of this method is that it will guarantee that all users have appropriate rights on
+ the workstation.
+ </para>
+
+ </sect3>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1>
+ <title>UNIX and Windows User Management</title>
+
+ <para>
+<indexterm><primary>user account</primary></indexterm>
+<indexterm><primary>UNIX/Linux user account</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>POSIX account</primary></indexterm>
+<indexterm><primary>range</primary></indexterm>
+<indexterm><primary>Windows user accounts</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>account information</primary></indexterm>
+ 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 cannot 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 [&lt;method&gt;] user ADD &lt;name&gt; [-c container] [-F user flags] \
+ [misc. options] [targets]
+</screen>
+ The user account password may be set using this syntax:
+<screen>
+net rpc password &lt;username&gt; [&lt;password&gt;] -Uadmin_username%admin_pass
+</screen>
+ </para>
+
+ <para>
+ The following demonstrates the addition of an account to the server <constant>FRODO</constant>:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user add</tertiary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user password</tertiary></indexterm>
+<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 [&lt;method&gt;] user DELETE &lt;name&gt; [misc. options] [targets]
+</screen>
+ The following command will delete the user account <constant>jacko</constant>:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user delete</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user info</tertiary></indexterm>
+<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>
+
+ <para>
+ It is also possible to rename user accounts:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user rename</tertiary></indexterm>oldusername newusername
+ Note that this operation does not yet work against Samba Servers. It is, however, possible to rename useraccounts on
+ Windows Servers.
+
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>User Mapping</title>
+
+ <para>
+<indexterm><primary>logon name</primary></indexterm>
+<indexterm><primary>/etc/samba/smbusers</primary></indexterm>
+<indexterm><primary>username map</primary></indexterm>
+ In some situations it is unavoidable that a user's 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>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>manage printers</primary></indexterm>
+<indexterm><primary>manage shares</primary></indexterm>
+<indexterm><primary>manage groups</primary></indexterm>
+<indexterm><primary>manage users</primary></indexterm>
+ With all versions of Samba earlier than 3.0.11 the only account on a Samba server that could
+ manage users, groups, shares, printers, and such was the <constant>root</constant> account. This caused
+ 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>
+<indexterm><primary>delegate administrative privileges</primary></indexterm>
+<indexterm><primary>normal user</primary></indexterm>
+<indexterm><primary>rights and privilege</primary></indexterm>
+<indexterm><primary>privilege management</primary></indexterm>
+<indexterm><primary>groups of users</primary></indexterm>
+ 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 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:
+<indexterm><primary>SeMachineAccountPrivilege</primary></indexterm>
+<indexterm><primary>SePrintOperatorPrivilege</primary></indexterm>
+<indexterm><primary>SeAddUsersPrivilege</primary></indexterm>
+<indexterm><primary>SeRemoteShutdownPrivilege</primary></indexterm>
+<indexterm><primary>SeDiskOperatorPrivilege</primary></indexterm>
+<indexterm><primary>SeBackupPrivilege</primary></indexterm>
+<indexterm><primary>SeRestorePrivilege</primary></indexterm>
+<indexterm><primary>SeTakeOwnershipPrivilege</primary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights list</tertiary></indexterm>
+<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
+ SeBackupPrivilege Back up files and directories
+ SeRestorePrivilege Restore files and directories
+ SeTakeOwnershipPrivilege Take ownership of files or other objects
+</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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights grant</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights list accounts</tertiary></indexterm>
+<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 is between domain controllers and domain
+ member machines (network clients), the second is between domains (called interdomain trusts). All
+ Samba servers that participate in domain security require a domain membership trust account, as do like
+ Windows NT/200x/XP workstations.
+ </para>
+
+ <sect2>
+ <title>Machine Trust Accounts</title>
+
+ <para>
+ The net command looks in the &smb.conf; file to obtain its own configuration settings. Thus, the following
+ command 'knows' which domain to join from the &smb.conf; file.
+ </para>
+
+ <para>
+ A Samba server domain trust account can be validated as shown in this example:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>testjoin</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>testjoin</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join member</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join bdc</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>join</tertiary></indexterm>
+<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 an 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user delete</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc user delete HERRING\$ -Uroot%not24get
+Deleted user account.
+</screen>
+ The removal is made possible because machine accounts 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:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>leave</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>status</tertiary></indexterm>
+<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 online from
+ the <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample.pdf">Samba-3 by Example</ulink>.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Interdomain Trusts</title>
+
+ <para>
+ Interdomain 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom list</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc trustdom list -Uroot%not24get
+Trusted domains list:
+
+none
+
+Trusting domains list:
+
+none
+</screen>
+ There are no interdomain 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom add</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom list</tertiary></indexterm>
+<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 joining the trust relationship:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom establish</tertiary></indexterm>
+<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 users to access a foreign domain. The trusting
+ connection can be revoked as shown here:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom revoke</tertiary></indexterm>
+<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>
+<indexterm><primary>security identifier</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>desktop profiles</primary></indexterm>
+<indexterm><primary>user encoded</primary></indexterm>
+<indexterm><primary>group SID</primary></indexterm>
+ The basic security identifier that is used by 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>
+<indexterm><primary>machine SID</primary></indexterm>
+<indexterm><primary>domain SID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>rejoin</primary></indexterm>
+ It is truly prudent to store the machine and/or domain SID in a file for safekeeping. 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 rejoin 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:
+<indexterm><primary>net</primary><secondary>getlocalsid</secondary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>setlocalsid</secondary></indexterm>
+<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 backup 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.
+ DMS and workstation clients should have their own machine SID to avoid
+ any potential namespace 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):
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>getsid</tertiary></indexterm>
+<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 insofar 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 command"/>, <smbconfoption name="delete share command"/> and
+ <smbconfoption name="change share command"/> 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 sharepoint 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share add</tertiary></indexterm>
+<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 it is possible to obtain a listing of available shares, as shown here:
+<screen>
+&rootprompt; net rpc share -S MERLIN -Uroot%not24get
+profdata
+archive
+Bulge &lt;--- 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share delete</tertiary></indexterm>
+<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 <command>net</command> tool cannot 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
+ or using the Computer Management MMC snap-in. Neither is covered here,
+ but see <link linkend="AccessControls"/>.
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Share, Directory, and File Migration</title>
+
+ <para>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>vampire</tertiary></indexterm>
+ 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, 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 fileserver, 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.
+ 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 is that 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 effect 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 - as net's general rule of thumb .
+ </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 on both
+ the migration source and the migration target.
+ </para></listitem>
+
+ <listitem><para>
+ Printer settings may not be fully or may be 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</parameter> and <parameter>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 &lt;share-name&gt; -S &lt;source&gt;
+ [--destination=localhost] [--exclude=share1,share2] [-v]
+</screen>
+ When the parameter &lt;share-name&gt; 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate</tertiary></indexterm>
+<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 and 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>right list accounts</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc right list accounts -Uroot%not24get
+</screen>
+ The steps taken so far perform 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 demonstrate 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 MS Windows
+ administrators because Windows NT and 200X servers do not always include the tools needed. The
+ <command>xcopy</command> from Windows NT is not capable of preserving file and directory ACLs,
+ it does so only with Windows 200x. Microsoft does 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 a 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 both to a
+ DMS and to domain controllers 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 &lt;share-name&gt; -S &lt;source&gt;
+ [--destination=localhost] [--exclude=share1,share2]
+ [--acls] [--attrs] [--timestamps] [-v]
+</screen>
+ If the &lt;share-name&gt; 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 timestamps can be preserved by specifying the
+ <parameter>--timestamps</parameter> switch, and the DOS file attributes (i.e., hidden, archive, etc.) can
+ 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 supports
+ 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate files</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc share migrate files -S nt4box --acls \
+ --attrs -U administrator%secret
+</screen>
+ </para>
+
+ <para>
+ This 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>Share-ACL Migration</title>
+ <para>
+ It is possible to have share-ACLs (security descriptors) that won't allow you, even as Administrator, to
+ copy any files or directories into it. Therefor the migration of the share-ACLs has been put into a separate
+ function:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate security</tertiary></indexterm>
+<screen>
+&rootprompt; net rpc share migrate security -S nt4box -U administrator%secret
+</screen>
+ </para>
+
+ <para>
+ This command will only copy the share-ACL of each share on nt4box to your local samba-system.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Simultaneous Share and File Migration</title>
+
+ <para>
+ The operating mode shown here is just a combination of the previous three. It first migrates
+ share definitions and then all shared files and directories and finally migrates the share-ACLs:
+<screen>
+net rpc share MIGRATE ALL &lt;share-name&gt; -S &lt;source&gt;
+ [--exclude=share1, share2] [--acls] [--attrs] [--timestamps] [-v]
+</screen>
+ </para>
+
+ <para>
+ An example of simultaneous migration is shown here:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate all</tertiary></indexterm>
+<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 is similar to
+ building a house; progress is very rapid from the laying of foundations up to the stage at which
+ 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 it will not be possible to find driver files that are
+ currently in use, 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 &smbmdash; no 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 that 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 is now
+ 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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate printers</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate drivers</tertiary></indexterm>
+<screen>
+net rpc printer MIGRATE DRIVERS [printer] [misc. options] [targets]
+</screen>
+ Printer forms can be migrated with the following operation:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate forms</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate security</tertiary></indexterm>
+<screen>
+net rpc printer MIGRATE SECURITY [printer] [misc. options] [targets]
+</screen>
+ Printer configuration settings include factors such as paper size and default paper orientation.
+ These can be migrated from the Windows print server to the Samba server with this command:
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate settings</tertiary></indexterm>
+<screen>
+net rpc printer MIGRATE SETTINGS [printer] [misc. options] [targets]
+</screen>
+ </para>
+
+ <para>
+ Migration of printers including 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, which provides the tools 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:
+<indexterm><primary>net</primary><secondary>rap</secondary><tertiary>session</tertiary></indexterm>
+<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 an 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 may be obtained
+ from the ADS server by executing the <command>net ads print info</command> command following this syntax:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer info</tertiary></indexterm>
+<screen>
+net ads printer info &lt;printer_name&gt; &lt;server_name&gt; -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:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer publish</tertiary></indexterm>
+<screen>
+net ads printer publish &lt;printer_name&gt; -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:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer remove</tertiary></indexterm>
+<screen>
+net ads printer remove &lt;printer_name&gt; -Uadministrator%secret
+</screen>
+ </para>
+
+ <para>
+ A generic search (query) can also be made to locate a printer across the entire ADS domain by executing:
+<indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer search</tertiary></indexterm>
+<screen>
+net ads printer search &lt;printer_name&gt; -Uadministrator%secret
+</screen>
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Manipulating the Samba Cache</title>
+
+ <para>
+ Please refer to the <command>net</command> command man page for information regarding cache management.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Managing IDMAP UID/SID Mappings</title>
+
+ <para>
+ The IDMAP UID to SID, and SID to UID, mappings that are created by <command>winbindd</command> can be
+ backed up to a text file. The text file can be manually edited, although it is highly recommended that
+ you attempt this only if you know precisely what you are doing.
+ </para>
+
+ <para>
+ An IDMAP text dump file can be restored (or reloaded). There are two situations that may necessitate
+ this action: a) The existing IDMAP file is corrupt, b) It is necessary to install an editted version
+ of the mapping information.
+ </para>
+
+ <para>
+ Winbind must be shut down to dump the IDMAP file. Before restoring a dump file, shut down
+ <command>winbindd</command> and delete the old <filename>winbindd_idmap.tdb</filename> file.
+ </para>
+
+ <sect2>
+ <title>Creating an IDMAP Database Dump File</title>
+
+ <para>
+ The IDMAP database can be dumped to a text file as shown here:
+<screen>
+net idmap dump &lt;full_path_and_tdb_filename&gt; &gt; dumpfile.txt
+</screen>
+ Where a particular build of Samba the run-time tdb files are stored in the
+ <filename>/var/lib/samba</filename> directory the following commands to create the dump file will suffice:
+<screen>
+net idmap dump /var/lib/samba/winbindd_idmap.tdb &gt; idmap_dump.txt
+</screen>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>Restoring the IDMAP Database Dump File</title>
+
+ <para>
+ The IDMAP dump file can be restored using the following command:
+<screen>
+net idmap restore &lt;full_path_and_tdb_filename&gt; &lt; dumpfile.txt
+</screen>
+ Where the Samba run-time tdb files are stored in the <filename>/var/lib/samba</filename> directory
+ the following command can be used to restore the data to the tdb file:
+<screen>
+net idmap restore /var/lib/samba/winbindd_idmap.tdb &lt; idmap_dump.txt
+</screen>
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="netmisc1">
+ <title>Other Miscellaneous Operations</title>
+
+ <para>
+ The following command is useful for obtaining basic statistics regarding a Samba domain. This command does
+ not work with current Windows XP Professional clients.
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>info</tertiary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>time</secondary></indexterm>
+<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:
+<indexterm><primary>net</primary><secondary>time</secondary><tertiary>system</tertiary></indexterm>
+<screen>
+&rootprompt; net time system -S FRODO
+051700532005.16
+</screen>
+ The time can be set on a target server by executing:
+<indexterm><primary>net</primary><secondary>time</secondary><tertiary>set</tertiary></indexterm>
+<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 of a server by executing the following command against it:
+<indexterm><primary>net</primary><secondary>time</secondary><tertiary>zone</tertiary></indexterm>
+<screen>
+&rootprompt; net time zone -S SAURON
+-0600
+</screen>
+ </para>
+
+ </sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Unicode.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Unicode.xml
new file mode 100644
index 0000000000..d4318995a1
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Unicode.xml
@@ -0,0 +1,571 @@
+<?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>
+<indexterm><primary>use computer anywhere</primary></indexterm>
+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>
+<indexterm><primary>codepages</primary></indexterm>
+Samba-2.x supported a single locale through a mechanism called
+<emphasis>codepages</emphasis>. Samba-3 is destined to become a truly transglobal
+file- and printer-sharing platform.
+</para>
+
+</sect1>
+
+<sect1>
+<title>What Are Charsets and Unicode?</title>
+
+<para>
+<indexterm><primary>character set</primary></indexterm>
+Computers communicate in numbers. In texts, each number is
+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>
+<indexterm><primary>charset</primary></indexterm>
+<indexterm><primary>ASCII</primary></indexterm>
+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>
+<indexterm><primary>multibyte charsets</primary></indexterm>
+<indexterm><primary>extended characters</primary></indexterm>
+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 multibyte charsets because they use
+more then one byte to store one character.
+</para>
+
+<para>
+<indexterm><primary>unicode</primary></indexterm>
+One standardized multibyte charset encoding scheme is known as
+<ulink url="http://www.unicode.org/">unicode</ulink>. A big advantage of using a
+multibyte 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>
+<indexterm><primary>single-byte charsets</primary></indexterm>
+<indexterm><primary>SMB/CIFS</primary></indexterm>
+<indexterm><primary>negotiating the charset</primary></indexterm>
+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>
+<indexterm><primary>Unicode</primary></indexterm>
+<indexterm><primary>character sets</primary></indexterm>
+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>
+<indexterm><primary>UTF-8</primary></indexterm>
+<indexterm><primary>CP850</primary></indexterm>
+ This is the charset used internally by your operating system.
+ The default is <constant>UTF-8</constant>, which is fine for most
+ systems and covers all characters in all languages. The default
+ in previous Samba releases was to save filenames in the encoding of the
+ clients &smbmdash; for example, CP850 for Western European countries.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><smbconfoption name="display charset"/></term>
+ <listitem><para>This is the charset Samba uses 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 &quot;dos charset&quot;</command> to see
+ what the default is on your system.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1>
+<title>Conversion from Old Names</title>
+
+<para>
+<indexterm><primary>charset conversion</primary></indexterm>
+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>
+<indexterm><primary>JIS X 0208</primary></indexterm>
+ 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>
+<indexterm><primary>Shift_JIS</primary></indexterm>
+<indexterm><primary>EUC-JP</primary></indexterm>
+<indexterm><primary>CAP</primary></indexterm>
+<indexterm><primary>HEX</primary></indexterm>
+<indexterm><primary>Japanese</primary></indexterm>
+ 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 used in Windows
+ and some UNIXes. The other is the EUC-JP series used in most UNIXes
+ and Linux. Moreover, Samba previously also offered several unique encoding
+ methods, named CAP and HEX, to keep interoperability with CAP/NetAtalk and
+ UNIXes that 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() depend
+ 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>
+<indexterm><primary>UCS-2</primary></indexterm>
+<indexterm><primary>Shift_JIS</primary></indexterm>
+<indexterm><primary>ASCII</primary></indexterm>
+<indexterm><primary>English</primary></indexterm>
+ 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>
+<indexterm><primary>CP932</primary></indexterm>
+ The <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>
+<indexterm><primary>Shift_JIS</primary></indexterm>
+<indexterm><primary>UTF-8</primary></indexterm>
+<indexterm><primary>EUC-JP</primary></indexterm>
+ The <smbconfoption name="unix charset"/> can be either Shift_JIS series,
+ EUC-JP series, or UTF-8. UTF-8 is always available, but the availability of other locales
+ and the name itself depends on the system.
+ </para>
+
+ <para>
+ Additionally, you can consider using 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 that 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 filename consists 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 filename on UNIX becomes
+ 0x8ba4, 0x974c, <quote>.txt</quote> (an 8-byte BINARY string), same as Windows.
+ </para>
+
+ <para>Since Shift_JIS series is usually used on some commercial-based
+ UNIXes; hp-ux and AIX as the Japanese locale (however, it is also possible
+ to use the EUC-JP locale series). To use Shift_JIS series on these platforms,
+ Japanese filenames 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 filenames written from Windows, the
+ Shift_JIS series is the best choice. However, broken filenames
+ may be displayed, and some commands that cannot handle non-ASCII
+ filenames may be aborted during parsing filenames. Especially, there
+ may be <quote>\ (0x5c)</quote> in filenames, which need to be handled carefully.
+ It is best to not touch filenames written from Windows on UNIX.
+ </para>
+
+ <para>
+ Note that most Japanized free software actually works with EUC-JP
+ only. It is good practice to verify that the Japanized free software can work
+ with Shift_JIS.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>EUC-JP series</term>
+ <listitem><para>
+<indexterm><primary>EUC-JP</primary></indexterm>
+<indexterm><primary>Japanese UNIX</primary></indexterm>
+ EUC-JP series means a locale that 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
+ filename consists of 0x8ba4 and 0x974c and <quote>.txt</quote> is written from
+ Windows on Samba, the filename on UNIX becomes 0xb6a6, 0xcdad,
+ <quote>.txt</quote> (an 8-byte BINARY string).
+ </para>
+
+ <para>
+<indexterm><primary>EUC-JP</primary></indexterm>
+<indexterm><primary>UNIX</primary></indexterm>
+<indexterm><primary>Linux</primary></indexterm>
+<indexterm><primary>FreeBSD</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>IRIX</primary></indexterm>
+<indexterm><primary>Tru64 UNIX</primary></indexterm>
+<indexterm><primary>Japanese locale</primary></indexterm>
+<indexterm><primary>Shift_JIS</primary></indexterm>
+<indexterm><primary>UTF-8</primary></indexterm>
+ 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,
+ and on Tru64 UNIX it is possible to use Shift_JIS). To use EUC-JP series, most Japanese filenames created from
+ Windows can be referred to also on UNIX. Also, most Japanized free software works mainly with EUC-JP only.
+ </para>
+
+ <para>
+ It is recommended to choose EUC-JP series when using Japanese filenames on UNIX.
+ </para>
+
+ <para>
+ Although there is no character that needs to be carefully treated
+ like <quote>\ (0x5c)</quote>, broken filenames may be displayed and some
+ commands that cannot handle non-ASCII filenames may be aborted
+ during parsing filenames.
+ </para>
+
+ <para>
+<indexterm><primary>eucJP-ms locale</primary></indexterm>
+ Moreover, if you built Samba using differently installed libiconv,
+ the eucJP-ms locale included in libiconv and EUC-JP series locale
+ included in the operating system may not be compatible. In this case, you may need to
+ avoid using incompatible characters for filenames.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>UTF-8</term>
+ <listitem><para>
+ UTF-8 means a locale equivalent to UTF-8, the international standard defined by the Unicode consortium. In
+ UTF-8, a <parameter>character</parameter> is expressed using 1 to 3 bytes. In case of the Japanese language,
+ 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 the length of the UTF-8
+ string is 1.5 times that of the original Shift_JIS string. In the case of UTF-8, for example, if a Japanese
+ filename consists of 0x8ba4 and 0x974c, and <quote>.txt</quote> is written from Windows on Samba, the filename
+ on UNIX becomes 0xe585, 0xb1e6, 0x9c89, <quote>.txt</quote> (a 10-byte 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 the default locale for Japanese.
+ </para>
+
+ <para>
+ Some broken filenames may be displayed, and some commands that
+ cannot handle non-ASCII filenames may be aborted during parsing
+ filenames. Especially, there may be <quote>\ (0x5c)</quote> in filenames, which
+ must be handled carefully, so you had better not touch filenames
+ written from Windows on UNIX.
+ </para>
+
+ <para>
+<indexterm><primary>Windows</primary></indexterm>
+<indexterm><primary>Java</primary></indexterm>
+<indexterm><primary>Unicode UTF-8</primary></indexterm>
+ In addition, although it is not directly concerned with Samba, since
+ there is a delicate difference between the iconv() function, which is
+ generally used on UNIX, and the functions used on other platforms,
+ such as Windows and Java, so far is concerens the conversion between
+ Shift_JIS and Unicode UTF-8 must be done with care and recognition
+ of the limitations involved in the process.
+ </para>
+
+ <para>
+<indexterm><primary>Mac OS X </primary></indexterm>
+ 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>
+<indexterm><primary>CAP</primary></indexterm>
+<indexterm><primary>NetAtalk</primary></indexterm>
+<indexterm><primary>Macintosh</primary></indexterm>
+ CAP encoding means a specification used in CAP and NetAtalk, file
+ server software for Macintosh. In the case of CAP encoding, for
+ example, if a Japanese filename consists of 0x8ba4 and 0x974c, and
+ <quote>.txt</quote> is written from Windows on Samba, the filename on UNIX
+ becomes <quote>:8b:a4:97L.txt</quote> (a 14 bytes ASCII string).
+ </para>
+
+ <para>
+ For CAP encoding, a byte that cannot be expressed as an ASCII
+ character (0x80 or above) is encoded in an <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 that cannot handle non-ASCII filenames.
+ </para>
+
+ <para>
+ The greatest merit of CAP encoding is the compatibility of encoding
+ filenames with CAP or NetAtalk. These are respectively the Columbia Appletalk
+ Protocol, and the NetAtalk Open Source software project.
+ Since these software applications 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 from being broken.
+ </para>
+
+ <para>
+ However, recently, NetAtalk has been
+ patched on some systems to write filenames with EUC-JP (e.g., Japanese original Vine Linux).
+ In this case, 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 that cannot handle non-ASCII characters or systems that
+ share files with NetAtalk.
+ </para>
+
+ <para>
+ To use CAP encoding on Samba-3, you should use the unix charset parameter and VFS
+ as in <link linkend="vfscap-intl">the VFS CAP smb.conf file</link>.
+ </para>
+
+<example id="vfscap-intl">
+<title>VFS CAP</title>
+ <smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <para>
+<indexterm><primary>CP932</primary></indexterm>
+<indexterm><primary>libiconv</primary></indexterm>
+<indexterm><primary>unix charset</primary></indexterm>
+<indexterm><primary>cap-share</primary></indexterm>
+ You should set CP932 if using GNU libiconv for unix charset. With this setting,
+ 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>
+
+<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 because of 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:
+ <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>
+
+ <para>
+ Other Japanese locales (for example, Shift_JIS and EUC-JP) should not
+ be used because of 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, the <quote>coding system</quote> parameter was used. The default codepage in Samba
+2.x was code page 850. In the Samba-3 series this has been replaced with the <smbconfoption name="unix
+charset"/> parameter. <link linkend="japancharsets">Japanese Character Sets in Samba-2.2 and Samba-3</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>
+ 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 that the configure process found iconv. This can be
+ confirmed by checking the <filename>config.log</filename> file that is generated when
+ <command>configure</command> is executed.</para>
+ </sect2>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-VFS.xml b/docs-xml/Samba3-HOWTO/TOSHARG-VFS.xml
new file mode 100644
index 0000000000..b8bd3277a6
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-VFS.xml
@@ -0,0 +1,949 @@
+<?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>
+<indexterm><primary>Virtual File System</primary><see>VFS</see></indexterm>
+<indexterm><primary>modules</primary></indexterm>
+<indexterm><primary>loaded modules</primary></indexterm>
+Stackable VFS (Virtual File System) modules support was new to Samba-3 and has proven quite popular. Samba
+passes each request to access the UNIX file system through the loaded VFS modules. This chapter covers the
+modules that come with the Samba source and provides references to some external modules.
+</para>
+
+
+</sect1>
+
+<sect1>
+<title>Discussion</title>
+
+<para>
+<indexterm><primary>IRIX</primary></indexterm>
+<indexterm><primary>GNU/Linux</primary></indexterm>
+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>
+<indexterm><primary>VFS modules</primary></indexterm>
+<indexterm><primary>modules</primary></indexterm>
+<indexterm><primary>recycle bin</primary></indexterm>
+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">the smb.conf with VFS
+modules example</link>:
+</para>
+
+<example id="vfsrecyc">
+<title>smb.conf with VFS modules</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+<para>
+<indexterm><primary>virus scanner</primary></indexterm>
+<indexterm><primary>scanner module</primary></indexterm>
+<indexterm><primary>recycle bin</primary></indexterm>
+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 to get run and may detect a virus immediately, before any action is performed on that file.
+<smbconfoption name="vfs objects">vscan-clamav recycle</smbconfoption>
+</para>
+
+<para>
+<indexterm><primary>/usr/local/samba/lib/vfs</primary></indexterm>
+<indexterm><primary>/usr/lib/samba/vfs</primary></indexterm>
+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>
+<indexterm><primary>modules</primary></indexterm>
+<indexterm><primary>VFS</primary></indexterm>
+<indexterm><primary>multiple modules</primary></indexterm>
+<indexterm><primary>multiple VFS</primary></indexterm>
+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 smb.conf with multiple VFS modules</link>.
+
+<example id="multimodule">
+<title>smb.conf with multiple VFS modules</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+</para>
+
+</sect1>
+
+<sect1>
+<title>Included Modules</title>
+
+ <sect2>
+ <title>audit</title>
+
+ <para>
+<indexterm><primary>audit file access</primary></indexterm>
+ 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>default_quota</title>
+
+ <para>
+ This module allows the default quota values, in the windows explorer GUI, to be stored on a Samba-3 server.
+ The challenge is that linux filesystems only store quotas for users and groups, but no default quotas.
+ </para>
+
+ <para>
+ Samba returns NO_LIMIT as the default quotas by default and refuses to update them. With this module you
+ can store the default quotas that are reported to a windows client, in the quota record of a user. By
+ default the root user is taken because quota limits for root are typically not enforced.
+ </para>
+
+ <para>
+ This module takes 2 parametric entries in the &smb.conf; file. The default prefix for each is the
+ <quote>default_quota</quote>. This can be overwrittem when you load the module in the <emphasis>vfs
+ modules</emphasis> parameter like this:
+<screen>
+vfs objects = default_quota:myprefix
+</screen>
+ </para>
+
+ <para>
+ The parametric entries that may be specified for the default_quotas module are:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>myprefix:uid</term>
+ <listitem><para>
+ This parameter takes a integer argument that specifies the uid of the quota record that will be
+ used for storing the default user quotas.
+ </para>
+
+ <para>
+ The default value is 0 (for root user). An example of use is:
+<screen>
+vfs objects = default_quota
+default_quota: uid = 65534
+</screen>
+ The above demonstrates the case where the <constant>myprefix</constant> was omitted, thus the
+ default prefix is the name of the module. When a <constant>myprefix</constant> parameter is
+ specified the above can be re-written like this:
+<screen>
+vfs objects = default_quota:myprefix
+myprefix: uid = 65534
+</screen>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>myprefix:uid nolimit</term>
+ <listitem><para>
+ This parameter takes a boolean argument that specifies if the stored default quota values also be
+ reported for the user record, or if the value <constant>NO_LIMIT</constant> should be reported to
+ the windows client for the user specified by the <parameter>prefix:uid</parameter> parameter.
+ </para>
+
+ <para>
+ The default value is <constant>yes</constant> (which means to report NO_LIMIT). An example of use
+ is shown here:
+<screen>
+vfs objects = default_quota:myprefix
+myprefix: uid nolimit = no
+</screen>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>myprefix:gid</term>
+ <listitem><para>
+ This parameter takes an integer argument, it's just like the <parameter>prefix>:uid</parameter> but
+ for group quotas. NOTE: group quotas are not supported from the windows explorer.
+ </para>
+
+ <para>
+ The default value is 0 (for root group). An example of use is shown here:
+<screen>
+vfs objects = default_quota
+default_quota: gid = 65534
+</screen>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>myprefix:gid nolimit</term>
+ <listitem><para>
+ This parameter takes a boolean argument, just like the <parameter>prefix>:uid nolimit</parameter>
+ but for group quotas. NOTE: group quotas are not supported from the windows explorer.
+ </para>
+
+ <para>
+ The default value is <constant>yes</constant> (which means to report NO_LIMIT). An example of use
+ is shown here:
+<screen>
+vfs objects = default_quota
+default_quota: uid nolimit = no
+</screen>
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ An example of use of multiple parametric specifications is shown here:
+<screen>
+...
+vfs objects = default_quota:quotasettings
+quotasettings: uid nolimit = no
+quotasettings: gid = 65534
+quotasettings: gid nolimit = no
+...
+</screen>
+ </para>
+
+ </sect2>
+
+ <sect2>
+ <title>extd_audit</title>
+
+ <para>
+<indexterm><primary>audit module</primary></indexterm>
+<indexterm><primary>extd_audit module</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+ 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 &amp; 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>
+<indexterm><primary>logging</primary></indexterm>
+ 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>
+<indexterm><primary>fake_perms</primary></indexterm>
+<indexterm><primary>Roaming Profile</primary></indexterm>
+<indexterm><primary>writeable</primary></indexterm>
+<indexterm><primary>read only</primary></indexterm>
+ 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>
+<indexterm><primary>recycle</primary></indexterm>
+<indexterm><primary>unlink calls</primary></indexterm>
+<indexterm><primary>recycle directory</primary></indexterm>
+ 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>
+<indexterm><primary>recycle</primary></indexterm>
+<indexterm><primary>.recycle</primary></indexterm>
+<indexterm><primary>recycle:keeptree</primary></indexterm>
+<indexterm><primary>deleted files</primary></indexterm>
+ 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 and <parameter>recycle:repository</parameter>
+ is not configured.
+ If <parameter>recycle:repository</parameter> is configured, the name
+ of the created directory depends on <parameter>recycle:repository</parameter>.
+ Users can recover files from the recycle bin. 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>
+<indexterm><primary>recycle:repository</primary></indexterm>
+ Path of the directory where deleted files should be moved.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:directory_mode</term>
+ <listitem><para>
+<indexterm><primary>directory_mode</primary></indexterm>
+ Set it to the octal mode you want for the recycle directory. With
+ this mode the recycle directory will be created if it not
+ exists and the first file is deleted.
+ If <parameter>recycle:subdir_mode</parameter> is not set, these
+ mode also apply to sub directories.
+ If <parameter>directory_mode</parameter> not exists, the default
+ mode 0700 is used.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:subdir_mode</term>
+ <listitem><para>
+<indexterm><primary>recycle:subdir_mode</primary></indexterm>
+ Set it to the octal mode you want for the sub directories of
+ the recycle directory. With this mode the sub directories will
+ be created.
+ If <parameter>recycle:subdir_mode</parameter> is not set, the
+ sub directories will be created with the mode from
+ <parameter>directory_mode</parameter>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:keeptree</term>
+ <listitem><para>
+<indexterm><primary>recycle:keeptree</primary></indexterm>
+ 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>
+<indexterm><primary>recycle:versions</primary></indexterm>
+ 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>
+<indexterm><primary>recycle:touch</primary></indexterm>
+ 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:touch_mtime</term>
+ <listitem><para>
+<indexterm><primary>recycle:touch</primary></indexterm>
+ Specifies whether a file's last modify date date should be touched when the file is moved to the recycle bin.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>recycle:maxsize</term>
+ <listitem><para>
+<indexterm><primary>recycle:maxsize</primary></indexterm>
+ 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>
+<indexterm><primary>recycle:exclude</primary></indexterm>
+ 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>
+<indexterm><primary>recycle:exclude_dir</primary></indexterm>
+ 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>
+<indexterm><primary>recycle:noversions</primary></indexterm>
+ 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>
+<indexterm><primary>netatalk</primary></indexterm>
+ A netatalk module will ease co-existence of Samba and netatalk file sharing services.
+ </para>
+
+ <para>Advantages compared to the old netatalk module:
+ <itemizedlist>
+<indexterm><primary>.AppleDouble</primary></indexterm>
+ <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>
+<indexterm><primary>shadow_copy</primary></indexterm>
+ <emphasis>THIS IS NOT A BACKUP, ARCHIVAL, OR VERSION CONTROL SOLUTION!</emphasis>
+ </para>
+
+ <para>
+<indexterm><primary>version control</primary></indexterm>
+ 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>
+<indexterm><primary>shadow_copy</primary></indexterm>
+<indexterm><primary>VFS module</primary></indexterm>
+<indexterm><primary>shadow_copy module</primary></indexterm>
+<indexterm><primary>LVM</primary></indexterm>
+<indexterm><primary>EVMS</primary></indexterm>
+<indexterm><primary>Logical Volume Manager</primary><see>LVM</see></indexterm>
+ 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:
+ </para>
+
+ <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, two part tutorial on Linux and LVM using LVM
+ source code and reiserfs.</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect3>
+ <title>Shadow Copy Setup</title>
+ <para>
+<indexterm><primary>XFS file system</primary></indexterm>
+<indexterm><primary>Debian Sarge</primary></indexterm>
+ 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 &amp; 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 later server running.
+ </para></formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara><title>Install &amp; Configure LVM</title>
+ <para>
+<indexterm><primary>shadow copies</primary></indexterm>
+<indexterm><primary>Snapshots</primary></indexterm>
+ 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>
+<indexterm><primary>lvm10 package</primary></indexterm>
+<indexterm><primary>devfsd package</primary></indexterm>
+<indexterm><primary>Debian</primary></indexterm>
+<indexterm><primary>xfsprogs</primary></indexterm>
+<indexterm><primary>apt-get</primary></indexterm>
+ 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
+ &amp;&amp; apt-get install lvm10 devfsd xfsprogs</command> should do the trick for this example.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>create volume</primary></indexterm>
+<indexterm><primary>create partition</primary></indexterm>
+<indexterm><primary>fdisk</primary></indexterm>
+<indexterm><primary>cfdisk</primary></indexterm>
+<indexterm><primary>Linux LVM</primary></indexterm>
+ 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>
+<indexterm><primary>Linux LVM partition</primary></indexterm>
+<indexterm><primary>LVM volume</primary></indexterm>
+<indexterm><primary>modprobe</primary></indexterm>
+ 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>
+<indexterm><primary>pvcreate</primary></indexterm>
+ Create the physical volume with <command>pvcreate /dev/hdb1</command>
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>vgcreate</primary></indexterm>
+<indexterm><primary>volume group</primary></indexterm>
+ Create the volume group and add /dev/hda1 to it with <command>vgcreate shadowvol /dev/hdb1</command>
+ </para>
+
+ <para>
+<indexterm><primary>vgdisplay</primary></indexterm>
+ You can use <command>vgdisplay</command> to review information about the volume group.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>lvcreate</primary></indexterm>
+ Now you can create the logical volume with something like <command>lvcreate -L400M -nsh_test shadowvol</command>
+ </para>
+
+ <para>
+<indexterm><primary>/dev/shadowvol</primary></indexterm>
+ This creates the logical volume of 400 MBs 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>
+<indexterm><primary>mkfs.xfs</primary></indexterm>
+ 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>
+<indexterm><primary>logical volume</primary></indexterm>
+<indexterm><primary>LVM</primary></indexterm>
+<indexterm><primary>freezing</primary></indexterm>
+<indexterm><primary>resizing</primary></indexterm>
+<indexterm><primary>growing</primary></indexterm>
+ 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>
+<indexterm><primary>LVM volume</primary></indexterm>
+<indexterm><primary>shadow_copy</primary></indexterm>
+<indexterm><primary>module</primary></indexterm>
+ Now we have an LVM volume where we can play with the shadow_copy VFS module.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>mkdir</primary></indexterm>
+<indexterm><primary>permissions</primary></indexterm>
+<indexterm><primary>chmod</primary></indexterm>
+ Now we need to prepare the directory with something like
+<screen>
+&rootprompt; mkdir -p /data/shadow_share
+</screen>
+ or whatever you want to name your shadow copy-enabled Samba share. Make sure you set the permissions so 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>
+<indexterm><primary>mount</primary></indexterm>
+ Mount the LVM volume using something like <command>mount /dev/shadowvol/sh_test /data/shadow_share</command>
+ </para>
+
+ <para>
+<indexterm><primary>/etc/fstab</primary></indexterm>
+ 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 &amp; 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>
+
+ <example id="vfsshadow">
+ <title>Share With shadow_copy VFS</title>
+ <smbconfblock>
+ <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>
+ </smbconfblock>
+ </example>
+
+ </listitem>
+
+ <listitem>
+ <formalpara><title>Create Snapshots and Make Them Available to shadow_copy.so</title>
+ <para>
+<indexterm><primary>shadow_copy</primary></indexterm>
+<indexterm><primary>LVM snapshots</primary></indexterm>
+<indexterm><primary>module</primary></indexterm>
+ 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>
+<indexterm><primary>VFS modules</primary></indexterm>
+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>
+<indexterm><primary>DatabaseFS</primary></indexterm>
+URL: <ulink noescape="1" url="http://www.css.tayloru.edu/~elorimer/databasefs/index.php">
+Taylors University DatabaeFS</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, it
+might prove useful for someone else who wishes to create a virtual filesystem.
+</para>
+
+</sect2>
+
+<sect2>
+<title>vscan</title>
+
+<indexterm><primary>vscan</primary></indexterm>
+<para>URL: <ulink noescape="1" url="http://www.openantivirus.org/projects.php#samba-vscan">
+Open Anti-Virus vscan</ulink>
+</para>
+
+<para>
+<indexterm><primary>samba-vscan</primary></indexterm>
+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>
+
+<sect2>
+<title>vscan-clamav</title>
+<para>
+Samba users have been using the RPMS from SerNet without a problem.
+OpenSUSE Linux users have also used the vscan scanner for quite some time
+with excellent results. It does impact overall write performance though.
+</para>
+
+<para>
+The following share stanza is a good guide for those wanting to configure vscan-clamav:
+</para>
+
+<screen>
+[share]
+vfs objects = vscan-clamav
+vscan-clamav: config-file = /etc/samba/vscan-clamav.conf
+</screen>
+
+<para>
+The following example of the <filename>vscan-clamav.conf</filename> file may help to get this
+fully operational:
+</para>
+
+<screen>
+<title>VFS: Vscan ClamAV Control File</title>
+#
+# /etc/samba/vscan-clamav.conf
+#
+
+[samba-vscan]
+; run-time configuration for vscan-samba using
+; clamd
+; all options are set to default values
+
+; do not scan files larger than X bytes. If set to 0 (default),
+; this feature is disable (i.e. all files are scanned)
+max file size = 10485760
+
+; log all file access (yes/no). If set to yes, every access will
+; be logged. If set to no (default), only access to infected files
+; will be logged
+verbose file logging = no
+
+; if set to yes (default), a file will be scanned while opening
+scan on open = yes
+; if set to yes, a file will be scanned while closing (default is yes)
+scan on close = yes
+
+; if communication to clamd fails, should access to file denied?
+; (default: yes)
+deny access on error = no
+
+; if daemon failes with a minor error (corruption, etc.),
+; should access to file denied?
+; (default: yes)
+deny access on minor error = no
+
+; send a warning message via Windows Messenger service
+; when virus is found?
+; (default: yes)
+send warning message = yes
+
+; what to do with an infected file
+; quarantine: try to move to quantine directory
+; delete: delete infected file
+; nothing: do nothing (default)
+infected file action = quarantine
+
+; where to put infected files - you really want to change this!
+quarantine directory = /opt/clamav/quarantine
+; prefix for files in quarantine
+quarantine prefix = vir-
+
+; as Windows tries to open a file multiple time in a (very) short time
+; of period, samba-vscan use a last recently used file mechanism to avoid
+; multiple scans of a file. This setting specified the maximum number of
+; elements of the last recently used file list. (default: 100)
+max lru files entries = 100
+
+; an entry is invalidad after lru file entry lifetime (in seconds).
+; (Default: 5)
+lru file entry lifetime = 5
+
+; exclude files from being scanned based on the MIME-type! Semi-colon
+; seperated list (default: empty list). Use this with care!
+exclude file types =
+
+; socket name of clamd (default: /var/run/clamd). Setting will be ignored if
+; libclamav is used
+clamd socket name = /tmp/clamd
+
+; limits, if vscan-clamav was build for using the clamav library (libclamav)
+; instead of clamd
+
+; maximum number of files in archive (default: 1000)
+libclamav max files in archive = 1000
+
+; maximum archived file size, in bytes (default: 10 MB)
+libclamav max archived file size = 5242880
+
+; maximum recursion level (default: 5)
+libclamav max recursion level = 5
+</screen>
+
+<para>
+Obviously, a running clam daemon is necessary for this to work. This is a working example for me using ClamAV.
+The ClamAV documentation should provide additional configuration examples. On your system these may be located
+under the <filename>/usr/share/doc/</filename> directory. Some examples may also target other virus scanners,
+any of which can be used.
+</para>
+
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-Winbind.xml b/docs-xml/Samba3-HOWTO/TOSHARG-Winbind.xml
new file mode 100644
index 0000000000..7731e4e206
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-Winbind.xml
@@ -0,0 +1,1479 @@
+<?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>June 15, 2005</pubdate>
+</chapterinfo>
+
+<title>Winbind: Use of Domain Accounts</title>
+
+<sect1>
+ <title>Features and Benefits</title>
+
+ <para>
+<indexterm><primary>holy grail</primary></indexterm>
+<indexterm><primary>heterogeneous computing</primary></indexterm>
+ 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>
+<indexterm><primary>interoperability</primary></indexterm>
+<indexterm><primary>domain user</primary></indexterm>
+<indexterm><primary>domain group</primary></indexterm>
+<indexterm><primary>group ownership</primary></indexterm>
+ 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>
+<indexterm><primary>Pluggable Authentication Modules</primary><see>PAM</see></indexterm>
+<indexterm><primary>winbind</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>RPC</primary></indexterm>
+ <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 (PAMs), and the name service switch (NSS) to
+ allow Windows NT domain users to appear and operate as UNIX users on a UNIX
+ machine. This chapter describes the Winbind system, the functionality
+ it provides, how it is configured, and how it works internally.
+ </para>
+
+ <para>
+ Winbind provides three separate functions:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>NT4 domain</primary></indexterm>
+ 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>
+<indexterm><primary>identity resolution</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+ Identity resolution (via NSS). This is the default when winbind is not used.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>idmap uid</primary></indexterm>
+<indexterm><primary>idmap gid</primary></indexterm>
+<indexterm><primary>idmap backend</primary></indexterm>
+<indexterm><primary></primary>LDAP</indexterm>
+ 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 stores 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>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>/etc/group</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>NSS</primary></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 been enabled with the NSS,
+ the resolution of user and group information will be accomplished via NSS.
+ </para></note>
+
+
+ <figure id="winbind_idmap">
+ <title>Winbind Idmap</title>
+ <imagefile scale="45">idmap_winbind_no_loop</imagefile>
+ </figure>
+
+</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>
+<indexterm><primary>synchronization problems</primary></indexterm>
+<indexterm><primary>passwords</primary></indexterm>
+ 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, because
+ 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>
+<indexterm><primary>unified logon</primary></indexterm>
+<indexterm><primary>duplication of information</primary></indexterm>
+ 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>
+<indexterm><primary>Windows account management</primary></indexterm>
+<indexterm><primary>UNIX users</primary></indexterm>
+<indexterm><primary>UNIX groups</primary></indexterm>
+<indexterm><primary>NT domain</primary></indexterm>
+ 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>
+<indexterm><primary>Winbind hooks</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>redirection</primary></indexterm>
+ The end result is that whenever a
+ program on the UNIX machine asks the operating system to look up
+ 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>
+<indexterm><primary>user and group</primary></indexterm>
+<indexterm><primary>domain user</primary></indexterm>
+ 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>
+<indexterm><primary>domain controller</primary></indexterm>
+ 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 because 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>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+ Additionally, Winbind provides an authentication service that hooks into the 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>
+<indexterm><primary>infrastructure</primary></indexterm>
+ 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>
+<indexterm><primary>Appliances</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+ 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>
+<indexterm><primary>foreign SID</primary></indexterm>
+ 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>
+<indexterm><primary>local domain</primary></indexterm>
+ Fact: Winbind is needed to handle users who use workstations that are NOT part
+ of the local domain.
+ </para>
+
+ <para>
+<indexterm><primary>PDC</primary></indexterm>
+ Response: <quote>Why? I've used Samba with workstations that are not part of my domains
+ lots of times without using winbind. I thought winbind was for using Samba as a member server
+ in a domain controlled by another Samba/Windows PDC.</quote>
+ </para>
+
+ <para>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>foreign user</primary></indexterm>
+ 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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>domain non-member</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+ This means that winbind is eminently useful in cases where a single
+ Samba PDC on a local network is combined with both domain member and domain non-member workstations.
+ If winbind is not used, the user george on a 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>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>UNIX domain socket</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+ 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 are processed sequentially.</para>
+
+ <para>The technologies used to implement Winbind are described
+ in detail below.</para>
+
+ <sect2>
+ <title>Microsoft Remote Procedure Calls</title>
+
+ <para>
+<indexterm><primary>Microsoft Remote Procedure Call</primary><see>MSRPC</see></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>remote management</primary></indexterm>
+<indexterm><primary>user authentication</primary></indexterm>
+<indexterm><primary>print spooling</primary></indexterm>
+ Over the last few years, efforts have been underway by various Samba Team members to implement 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>
+<indexterm><primary>MSRPC</primary></indexterm>
+<indexterm><primary>enumerate domain users</primary></indexterm>
+<indexterm><primary>enumerate domain groups</primary></indexterm>
+ 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>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>native mode</primary></indexterm>
+ 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>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>networked workstation</primary></indexterm>
+<indexterm><primary>NIS</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+ The 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 file system. 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>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>MSRPC</primary></indexterm>
+<indexterm><primary>trusted domain</primary></indexterm>
+<indexterm><primary>local users</primary></indexterm>
+<indexterm><primary>local groups</primary></indexterm>
+ 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, you can enumerate the users and groups on a UNIX machine running Winbind and see all users and
+ groups in an NT domain plus any trusted domain as though they were local users and groups.
+ </para>
+
+ <para>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+ 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:
+<screen>
+passwd: files example
+</screen>
+<indexterm><primary>/lib/libnss_files.so</primary></indexterm>
+<indexterm><primary>/lib/libnss_example.so</primary></indexterm>
+<indexterm><primary>resolver functions</primary></indexterm>
+ 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>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>libnss_winbind.so</primary></indexterm>
+<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+ 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>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>authentication methods</primary></indexterm>
+<indexterm><primary>authorization</primary></indexterm>
+<indexterm><primary>NIS database</primary></indexterm>
+ PAMs provide 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 an NIS database to log in over the network.
+ </para>
+
+ <para>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>authentication management</primary></indexterm>
+<indexterm><primary>password management</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+ 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 PDC. These users can also change their passwords and have this change take effect directly
+ on the PDC.
+ </para>
+
+ <para>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>/etc/pam.d/</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+<indexterm><primary>/lib/security/</primary></indexterm>
+ 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: simply copy the <filename>pam_winbind.so</filename> module 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>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>UNIX ID</primary></indexterm>
+ 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 used 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>
+<indexterm><primary>ID mapping database</primary></indexterm>
+<indexterm><primary>tdb</primary></indexterm>
+<indexterm><primary>UNIX ID</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+ 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>
+<indexterm><primary>caching scheme</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+ An active directory 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>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>authentication control</primary></indexterm>
+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>
+<indexterm><primary>Samba administrator</primary></indexterm>
+<indexterm><primary>authentication mechanisms</primary></indexterm>
+<indexterm><primary>domain members</primary></indexterm>
+<indexterm><primary>accounts</primary></indexterm>
+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>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>Windows NT/200x</primary></indexterm>
+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>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>back up</primary></indexterm>
+<indexterm><primary>boot disk`</primary></indexterm>
+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>
+<indexterm><primary>PAM configuration</primary></indexterm>
+<indexterm><primary>/etc/pam.d</primary></indexterm>
+<indexterm><primary>single-user mode</primary></indexterm>
+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> to the original state it was in if you get frustrated with the
+way things are going.
+</para>
+
+<para>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>daemon</primary></indexterm>
+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>
+<indexterm><primary>domain users</primary></indexterm>
+<indexterm><primary>shares and files</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>development libraries</primary></indexterm>
+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 to the PAM Web site <ulink url="http://www.kernel.org/pub/linux/libs/pam/"/>.
+</para>
+</sect2>
+
+<sect2>
+<title>Testing Things Out</title>
+
+<para>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>/etc/pam.d</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+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 is 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>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>pam-devel</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+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>
+<indexterm><primary>libnss_winbind.so</primary></indexterm>
+<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:
+</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:
+<indexterm><primary>nss_winbind.so.1</primary></indexterm>
+<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>
+
+<para>
+<indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
+As root, 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 looked like this after editing:
+<programlisting>
+passwd: files winbind
+shadow: files
+group: files winbind
+</programlisting></para>
+
+<para>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>ldconfig</primary></indexterm>
+<indexterm><primary>libnss_winbind</primary></indexterm>
+<indexterm><primary>grep</primary></indexterm>
+<indexterm><primary>dynamic link loader</primary></indexterm>
+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:
+<screen>
+&rootprompt;<userinput>/sbin/ldconfig -v | grep winbind</userinput>
+</screen>
+This makes <filename>libnss_winbind</filename> available to winbindd and reports the current
+search path that is used by the dynamic link loader. The use of the <command>grep</command>
+filters the output of the <command>ldconfig</command> command so that we may see proof that
+this library is indeed recognized by the dynamic link loader.
+</para>
+
+<para>
+<indexterm><primary>dynamic link loader</primary></indexterm>
+<indexterm><primary>crle</primary></indexterm>
+<indexterm><primary>/usr/local/lib</primary></indexterm>
+<indexterm><primary>link loader configuration</primary></indexterm>
+<indexterm><primary>object module dependencies</primary></indexterm>
+The Sun Solaris dynamic link loader management tool is called <command>crle</command>. The
+use of this tool is necessary to instruct the dynamic link loader to search directories that
+contain library files that were not supplied as part of the original operating system platform.
+The following example shows how to use this tool to add the directory <filename>/usr/local/lib</filename>
+to the dynamic link loader's search path:
+<screen>
+&rootprompt; crle -u -l /usr/lib:/usr/local/lib
+</screen>
+When executed without arguments, <command>crle</command> reports the current dynamic
+link loader configuration. This is demonstrated here:
+<screen>
+&rootprompt; crle
+
+Configuration file [version 4]: /var/ld/ld.config
+ Default Library Path (ELF): /lib:/usr/lib:/usr/local/lib
+ Trusted Directories (ELF): /lib/secure:/usr/lib/secure (system default)
+
+Command line:
+ crle -c /var/ld/ld.config -l /lib:/usr/lib:/usr/local/lib
+</screen>
+From this it is apparent that the <filename>/usr/local/lib</filename> directory is included
+in the search dynamic link libraries in order to satisfy object module dependencies.
+</para>
+
+</sect3>
+
+<sect3>
+<title>NSS Winbind on AIX</title>
+
+<para>(This section is only for those running AIX.)</para>
+
+<para>
+<indexterm><primary>AIX</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>/usr/lib/security</primary></indexterm>
+<indexterm><primary>authentication module API</primary></indexterm>
+<indexterm><primary>/usr/lib/security/methods.cfg</primary></indexterm>
+<indexterm><primary>PAM module</primary></indexterm>
+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:
+<programlisting>
+WINBIND:
+ program = /usr/lib/security/WINBIND
+ options = authonly
+</programlisting>
+can then be added to <filename>/usr/lib/security/methods.cfg</filename>. This module only supports
+identification, but there have been reports of success using the standard Winbind PAM module for
+authentication. Use caution configuring loadable authentication modules, since misconfiguration can make
+it impossible to log on to the system. Information regarding the AIX authentication module API can
+be found in the <quote>Kernel Extensions and Device Support Programming Concepts for AIX</quote> document that
+describes the <ulink url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/kernextc/sec_load_mod.htm">
+Loadable Authentication Module Programming Interface</ulink> for AIX. Further information on administering the modules
+can be found in the <ulink url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/baseadmn/iandaadmin.htm">System
+Management Guide: Operating System and Devices.</ulink>
+</para>
+</sect3>
+
+<sect3>
+<title>Configure smb.conf</title>
+
+<para>
+<indexterm><primary>winbind</primary></indexterm>
+<indexterm><primary>man page</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+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 smb.conf for Winbind Setup</link>, was modified to include the necessary entries in the [global] section.
+</para>
+
+<example id="winbindcfg">
+<title>smb.conf for Winbind Setup</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+</sect3>
+
+
+<sect3>
+<title>Join the Samba Server to the PDC Domain</title>
+
+<para>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>BDC</primary></indexterm>
+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>
+<indexterm><primary>joining domain</primary></indexterm>
+<indexterm><primary>domain join</primary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>MS DCE RPC</primary></indexterm>
+<indexterm><primary>DCE RPC</primary></indexterm>
+<indexterm><primary>RPC</primary></indexterm>
+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 domain controller. It is therefore necessary to temporarily
+start Samba on a PDC so that it can join its own domain.
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>administrative privileges</primary></indexterm>
+<indexterm><primary>Administrator</primary></indexterm>
+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>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>tcp ports</primary></indexterm>
+<indexterm><primary>udp ports</primary></indexterm>
+Before attempting to join a machine to the domain, verify that Samba is running
+on the target domain controller (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>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
+The use of the <command>net rpc join</command> facility is shown here:
+<screen>
+&rootprompt;<userinput>/usr/local/samba/bin/net rpc join -S PDC -U Administrator</userinput>
+</screen>
+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>
+<indexterm><primary>startup script</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>Winbind services</primary></indexterm>
+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:
+<screen>
+&rootprompt;<userinput>/usr/local/samba/sbin/winbindd</userinput>
+</screen>
+Use the appropriate path to the location of the <command>winbindd</command> executable file.
+</para>
+
+<note><para>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>/usr/local/samba</primary></indexterm>
+The command to start up Winbind services 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>
+<indexterm><primary>paranoid</primary></indexterm>
+<indexterm><primary>daemon running</primary></indexterm>
+I'm always paranoid and like to make sure the daemon is really running.
+<screen>
+&rootprompt;<userinput>ps -ae | grep winbindd</userinput>
+</screen>
+</para>
+
+<para>
+<indexterm><primary>winbindd</primary></indexterm>
+This command should produce output like the following if the daemon is running.
+<screen>
+3025 ? 00:00:00 winbindd
+</screen>
+</para>
+
+<para>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>wbinfo</primary></indexterm>
+Now, for the real test, try to get some information about the users on your PDC:
+<screen>
+&rootprompt;<userinput>/usr/local/samba/bin/wbinfo -u</userinput>
+</screen>
+This should echo back a list of users on your Windows users on your PDC. For example, I get the following
+response:
+<screen>
+CEO\Administrator
+CEO\burdell
+CEO\Guest
+CEO\jt-ad
+CEO\krbtgt
+CEO\TsInternetUser
+</screen>
+Obviously, I have named my domain <quote>CEO</quote> and my <smbconfoption name="winbind separator"/> is
+<quote>\</quote>.
+</para>
+
+<para>
+<indexterm><primary>wbinfo</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+You can do the same sort of thing to get group information from the PDC:
+<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>
+<indexterm><primary>getent</primary></indexterm>
+<indexterm><primary>PDC</primary></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>UID</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>home directories</primary></indexterm>
+<indexterm><primary>default shells</primary></indexterm>
+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:
+<screen>
+&rootprompt;<userinput>getent passwd</userinput>
+</screen>
+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:
+<screen>
+&rootprompt;<userinput>getent group</userinput>
+</screen>
+</para>
+
+</sect3>
+
+
+<sect3>
+<title>Fix the init.d Startup Scripts</title>
+
+<sect4>
+<title>Linux</title>
+
+<para>
+<indexterm><primary>winbindd daemon</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>/etc/init.d/smb</primary></indexterm>
+<indexterm><primary>/etc/init.d/samba</primary></indexterm>
+<indexterm><primary>/usr/local/samba/bin</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+<indexterm><primary></primary></indexterm>
+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 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:
+<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 ] &amp;&amp; \
+ 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 ] &amp;&amp; \
+ 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 section</link>
+for details.
+</para>
+
+<para>
+<indexterm><primary>Solaris 9</primary></indexterm>
+<indexterm><primary>/etc/init.d/samba.server</primary></indexterm>
+<indexterm><primary>/usr/local/samba/bin</primary></indexterm>
+<indexterm><primary>smbd</primary></indexterm>
+<indexterm><primary>nmbd</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+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>
+ <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" != "" ] &amp;&amp; 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></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>
+<indexterm><primary>daemons</primary></indexterm>
+<indexterm><primary>local user</primary></indexterm>
+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>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>/etc/pam.d</primary></indexterm>
+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>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>../source/nsswitch</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+<indexterm><primary>/lib/security</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>/usr/lib/security</primary></indexterm>
+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:
+<screen>
+&rootprompt;<userinput>make nsswitch/pam_winbind.so</userinput>
+</screen>
+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>.
+<screen>
+&rootprompt;<userinput>cp ../samba/source/nsswitch/pam_winbind.so /lib/security</userinput>
+</screen>
+</para>
+
+<sect4>
+<title>Linux/FreeBSD-Specific PAM Configuration</title>
+
+<para>
+<indexterm><primary>/etc/pam.d/samba</primary></indexterm>
+The <filename>/etc/pam.d/samba</filename> file does not need to be changed. I just left this file as it was:
+<programlisting>
+auth required /lib/security/pam_stack.so service=system-auth
+account required /lib/security/pam_stack.so service=system-auth
+</programlisting></para>
+
+<para>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>authentication service</primary></indexterm>
+<indexterm><primary>login</primary></indexterm>
+<indexterm><primary>console</primary></indexterm>
+<indexterm><primary>telnet logins</primary></indexterm>
+<indexterm><primary>ftp service</primary></indexterm>
+<indexterm><primary>/etc/xinetd.d</primary></indexterm>
+<indexterm><primary>/etc/inetd.conf</primary></indexterm>
+<indexterm><primary>/etc/xinetd.d/telnet</primary></indexterm>
+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:
+<programlisting>
+ enable = no
+</programlisting>
+to
+<programlisting>
+ enable = yes
+</programlisting></para>
+
+<para>
+<indexterm><primary>ftp services</primary></indexterm>
+<indexterm><primary>home directory template</primary></indexterm>
+<indexterm><primary>domain users</primary></indexterm>
+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>
+<indexterm><primary>pam_mkhomedir</primary></indexterm>
+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>
+<indexterm><primary>/etc/pam.d/ftp</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>ftp access</primary></indexterm>
+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:
+<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></para>
+
+<para>
+<indexterm><primary>/etc/pam.d/login</primary></indexterm>
+The <filename>/etc/pam.d/login</filename> file can be changed in nearly the same way. It now looks like this:
+<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>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+<indexterm><primary>pam_securetty.so</primary></indexterm>
+<indexterm><primary>pam_unix.so</primary></indexterm>
+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>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary></primary></indexterm>
+The <filename>/etc/pam.conf</filename> needs to be changed. I changed this file so my Domain
+users can log on both locally as well as with 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.
+<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>
+<indexterm><primary>winbind.so</primary></indexterm>
+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>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>NSS</primary></indexterm>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>RPC calls</primary></indexterm>
+<indexterm><primary>domain users</primary></indexterm>
+The Winbind system, through the use of the NSS, PAMs, 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 NSS and PAM 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 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>
+
+ <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.
+Alternately, fix the operation of nscd to resolve the problem.
+</para>
+
+</sect2>
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml b/docs-xml/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml
new file mode 100644
index 0000000000..50ee1c63e0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-WindowsClientConfig.xml
@@ -0,0 +1,599 @@
+<?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>
+<indexterm><primary>network difficulty</primary></indexterm>
+<indexterm><primary>network client</primary></indexterm>
+<indexterm><primary>client client instructions</primary></indexterm>
+Occasionally network administrators report difficulty getting Microsoft Windows clients to interoperate
+correctly with Samba servers. It seems that some folks just cannot accept the fact that the right way
+to configure an MS Windows network client is precisely as one would do when using MS Windows NT4 or 200x
+servers. Yet there is repetitious need to provide detailed Windows client configuration instructions.
+</para>
+
+<para>
+<indexterm><primary>graphically illustrated client configuration</primary></indexterm>
+<indexterm><primary>critical aspects of configuration</primary></indexterm>
+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>
+<indexterm><primary>TCP/IP protocol configuration</primary></indexterm>
+<indexterm><primary>network membership</primary></indexterm>
+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>
+<indexterm><primary>network configuration problems</primary></indexterm>
+<indexterm><primary>plague network users</primary></indexterm>
+ The builder of a house must ensure that all construction takes place on a firm foundation.
+ The same is true for the builder of a TCP/IP-based networking system. Fundamental network configuration problems
+ will plague all network users until they are resolved.
+ </para>
+
+ <para>
+<indexterm><primary>fixed IP addresses</primary></indexterm>
+<indexterm><primary>DHCP</primary></indexterm>
+ MS 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>
+<indexterm><primary>shortcuts</primary></indexterm>
+<indexterm><primary>abbreviated keystrokes</primary></indexterm>
+ 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>
+<indexterm><primary>Windows XP TCP/IP</primary></indexterm>
+ 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>
+<indexterm><primary>Windows XP Professional</primary></indexterm>
+ The following procedure steps through the Windows XP Professional TCP/IP configuration process:
+ </para>
+
+ <procedure>
+ <step><para>
+<indexterm><primary>Local Area Connection</primary></indexterm>
+<indexterm><primary>Network Bridge</primary></indexterm>
+<indexterm><primary>interface</primary></indexterm>
+ 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"/>.
+ <figure id="WXPP002"><title>Network Bridge Configuration.</title><imagefile>WXPP002</imagefile></figure>
+ </para>
+ </step>
+
+ <step><para>
+<indexterm><primary>TCP/IP protocol settings</primary></indexterm>
+<indexterm><primary>Network Bridge Configuration</primary></indexterm>
+ 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 on <guibutton>Properties</guibutton>.
+ </para>
+
+ <para>
+<indexterm><primary>DHCP-enabled operation</primary></indexterm>
+<indexterm><primary>IP address automatically</primary></indexterm>
+ The default setting is DHCP-enabled operation
+ (i.e., <quote>Obtain an IP address automatically</quote>). See <link linkend="WXPP003"/>.
+ <figure id="WXPP003">
+ <title>Internet Protocol (TCP/IP) Properties.</title>
+ <imagefile>WXPP003</imagefile>
+ </figure>
+ </para>
+
+ <para>
+<indexterm><primary>DHCP</primary></indexterm>
+<indexterm><primary>TCP/IP</primary></indexterm>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>ISC DHCP server</primary></indexterm>
+ 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 Windows client support see <link linkend="DHCP">the DNS and DHCP Configuration Guide</link>,
+ <link linkend="DHCP">DHCP Server</link>.
+ </para>
+
+ <para>
+<indexterm><primary>fixed IP address</primary></indexterm>
+<indexterm><primary>subnet mask</primary></indexterm>
+<indexterm><primary>gateway address</primary></indexterm>
+ If it is necessary to provide a fixed IP address, click on <quote>Use the following IP address</quote> and enter the
+ IP Address, the subnet mask, and the default gateway address in the boxes provided.
+ </para></step>
+
+ <step><para>
+<indexterm><primary>Advanced TCP/IP configuration</primary></indexterm>
+<indexterm><primary>TCP/IP configuration</primary></indexterm>
+<indexterm><primary>IP aliases</primary></indexterm>
+<indexterm><primary>default gateways</primary></indexterm>
+ 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.
+ <figure id="WXPP005"><title>Advanced Network Settings</title><imagefile>WXPP005</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>DHCP</primary></indexterm>
+ Fixed settings may be required for DNS and WINS if these settings are not provided automatically via DHCP.
+ </para></step>
+
+ <step><para>
+<indexterm><primary>DNS server settings</primary></indexterm>
+<indexterm><primary>manually configured DNS settings</primary></indexterm>
+ 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"/>.
+ <figure id="WXPP014"> <title>DNS Configuration.</title> <imagefile>WXPP014</imagefile> </figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>manual WINS server entries</primary></indexterm>
+ 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 <guibutton>OK</guibutton> to commit
+ the settings. See <link linkend="WXPP009"></link>.
+ <figure id="WXPP009"><title>WINS Configuration</title><imagefile>WXPP009</imagefile></figure>
+ </para></step>
+ </procedure>
+
+ </sect3>
+
+ <sect3>
+ <title>MS Windows 2000</title>
+
+ <para>
+<indexterm><primary>Windows 2000 Professional TCP/IP</primary></indexterm>
+<indexterm><primary>TCP/IP configuration panel</primary></indexterm>
+ 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>Alternatively,</emphasis> click <guimenu>Start</guimenu>, then right-click <guimenu>My Network Places</guimenu>, and
+ select <guimenuitem>Properties</guimenuitem>.
+ </para>
+
+ <para>
+<indexterm><primary>Windows XP Professional TCP/IP</primary></indexterm>
+ 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>, then click
+ <guimenuitem>Properties</guimenuitem>. See <link linkend="w2kp001"></link>.
+ <figure id="w2kp001"><title>Local Area Connection Properties.</title><imagefile>w2kp001</imagefile></figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>Local Area Connection Properties</primary></indexterm>
+<indexterm><primary>TCP/IP protocol settings</primary></indexterm>
+ 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>
+<indexterm><primary>DHCP-enabled</primary></indexterm>
+<indexterm><primary>IP address automatically</primary></indexterm>
+ The default setting is DHCP-enabled operation
+ (i.e., <quote>Obtain an IP address automatically</quote>). See <link linkend="w2kp002"/>.
+ <figure id="w2kp002"><title>Internet Protocol (TCP/IP) Properties.</title><imagefile>w2kp002</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>DHCP</primary></indexterm>
+<indexterm><primary>protocol stack settings</primary></indexterm>
+ 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 Windows client support, see, <link linkend="DHCP"></link>.
+ </para>
+
+ <para>
+<indexterm><primary>fixed IP address</primary></indexterm>
+<indexterm><primary>network clients</primary></indexterm>
+ If it is necessary to provide a fixed IP address, click on <quote>Use the following IP address</quote> and 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>.
+ <figure id="w2kp003"><title>Advanced Network Settings.</title><imagefile>w2kp003</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>DHCP</primary></indexterm>
+ Fixed settings may be required for DNS and WINS if these settings are not provided automatically via DHCP.
+ </para></step>
+
+ <step><para>
+<indexterm><primary>DNS server settings</primary></indexterm>
+<indexterm><primary>commit the settings</primary></indexterm>
+ Click the <guimenu>DNS</guimenu> tab to add DNS server settings.
+ The example system uses manually configured DNS settings. When finished making changes,
+ click <guibutton>OK</guibutton> to commit the settings. See <link linkend="w2kp004"></link>.
+ <figure id="w2kp004"><title>DNS Configuration.</title><imagefile>w2kp004</imagefile></figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>manual WINS server entries</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+ 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 <guibutton>OK</guibutton> to commit the settings.
+ See <link linkend="w2kp005"></link>.
+ <figure id="w2kp005">
+ <title>WINS Configuration.</title><imagefile>w2kp005</imagefile>
+ </figure>
+ </para></step>
+
+ </procedure>
+
+ </sect3>
+
+ <sect3>
+ <title>MS Windows Me</title>
+
+ <para>
+<indexterm><primary>Windows Millennium edition (Me) TCP/IP</primary></indexterm>
+<indexterm><primary>Windows Millennium</primary></indexterm>
+<indexterm><primary>TCP/IP configuration</primary></indexterm>
+ 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>
+<indexterm><primary>My Network Places</primary></indexterm>
+<indexterm><primary>Properties</primary></indexterm>
+ <emphasis>Alternatively,</emphasis> click on <guimenu>Start -></guimenu>, and right click on <guimenu>My Network Places</guimenu>
+ then select <guimenuitem>Properties</guimenuitem>.
+ </para>
+
+ <para>
+<indexterm><primary>Windows Me TCP/IP</primary></indexterm>
+ The following procedure steps through the Windows Me TCP/IP configuration process:
+ </para>
+
+ <procedure>
+ <step><para>
+<indexterm><primary>Internet Protocol TCP/IP</primary></indexterm>
+ In the box labeled <guimenuitem>The following network components are installed:</guimenuitem>,
+ click on <guimenu>Internet Protocol TCP/IP</guimenu>, then click on the <guibutton>Properties</guibutton> button.
+ See <link linkend="WME001"></link>.
+ <figure id="WME001">
+ <title>The Windows Me Network Configuration Panel.</title>
+ <imagefile>WME001</imagefile>
+ </figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>DHCP</primary></indexterm>
+<indexterm><primary>TCP/IP</primary></indexterm>
+<indexterm><primary>ISC DHCP server</primary></indexterm>
+ 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 Windows client support see <link linkend="DHCP">the DNS and DHCP Configuration Guide</link>,
+ <link linkend="DHCP">DHCP Server</link>. The default setting on Windows Me workstations is for DHCP-enabled operation
+ (i.e., <guimenu>Obtain IP address automatically</guimenu> is enabled). See <link linkend="WME002"></link>.
+ <figure id="WME002"><title>IP Address.</title><imagefile>WME002</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>Specify an IP address</primary></indexterm>
+<indexterm><primary>subnet mask</primary></indexterm>
+<indexterm><primary>DHCP</primary></indexterm>
+ If it is necessary to provide a fixed IP address, click on <guimenuitem>Specify an IP address</guimenuitem> and 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>
+<indexterm><primary>DNS</primary></indexterm>
+<indexterm><primary>WINS</primary></indexterm>
+ Fixed settings may be required for DNS and WINS if these settings are not provided automatically via DHCP.
+ </para></step>
+
+ <step><para>
+<indexterm><primary>WINS server settings</primary></indexterm>
+ 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>
+<indexterm><primary>WINS</primary></indexterm>
+<indexterm><primary>manually configured</primary></indexterm>
+ The following example uses manually configured WINS settings. See <link linkend="WME005"></link>.
+ When finished making changes, click <guibutton>OK</guibutton> to commit the settings.
+ <figure id="WME005"><title>DNS Configuration.</title><imagefile>WME005</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>single DHCP server</primary></indexterm>
+<indexterm><primary>multiple Windows workgroups or domains</primary></indexterm>
+ 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>.
+ <figure id="WME003"><title>WINS Configuration.</title><imagefile>WME003</imagefile></figure>
+ </para></step>
+ </procedure>
+
+
+ </sect3>
+
+ </sect2>
+
+ <sect2>
+ <title>Joining a Domain: Windows 2000/XP Professional</title>
+
+ <para>
+<indexterm><primary>Windows NT/200x/XP Professional</primary></indexterm>
+<indexterm><primary>domain security</primary></indexterm>
+<indexterm><primary>domain member</primary></indexterm>
+<indexterm><primary>domain joining</primary></indexterm>
+ 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>
+<indexterm><primary>Control Panel</primary></indexterm>
+ 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>.
+ <figure id="wxpp001"><title>The General Panel.</title><imagefile>wxpp001</imagefile></figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>Computer Name</primary></indexterm>
+ 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>
+<indexterm><primary>Network ID</primary></indexterm>
+<indexterm><primary>configuration wizard</primary></indexterm>
+ 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 or join or leave the domain, click the <guimenu>Change</guimenu> button.
+ See <link linkend="wxpp004"></link>.
+ <figure id="wxpp004"><title>The Computer Name Panel.</title><imagefile>wxpp004</imagefile></figure>
+ </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>.
+ <figure id="wxpp006"><title>The Computer Name Changes Panel.</title><imagefile>wxpp006</imagefile></figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>domain radio button</primary></indexterm>
+ 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>.
+ <figure id="wxpp007"><title>The Computer Name Changes Panel &smbmdash; Domain MIDEARTH.</title><imagefile>wxpp007</imagefile></figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>credentials</primary></indexterm>
+<indexterm><primary>username and password</primary></indexterm>
+ 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>
+<indexterm><primary>root</primary></indexterm>
+ Enter the name <quote>root</quote> and the root password from your Samba-3 server. See <link linkend="wxpp008"></link>.
+ <figure id="wxpp008">
+ <title>Computer Name Changes &smbmdash; Username and Password Panel.</title><imagefile>wxpp008</imagefile>
+ </figure>
+ </para></step>
+
+ <step><para>
+ Click on <guimenu>OK</guimenu>.
+ </para>
+
+ <para>
+<indexterm><primary>Welcome</primary></indexterm>
+<indexterm><primary>rebooted</primary></indexterm>
+ 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>
+<indexterm><primary>Windows 9x/Me</primary></indexterm>
+<indexterm><primary>domain logon</primary></indexterm>
+<indexterm><primary>LanManager</primary></indexterm>
+ 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>
+<indexterm><primary>Windows XP Home edition</primary></indexterm>
+<indexterm><primary>LanManager</primary></indexterm>
+<indexterm><primary>network logon</primary></indexterm>
+ 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>.
+ <figure id="WME009"><title>The Network Panel.</title><imagefile>WME009</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>Client for Microsoft Networks</primary></indexterm>
+<indexterm><primary>Properties</primary></indexterm>
+ 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>
+<indexterm><primary>Networks Properties</primary></indexterm>
+<indexterm><primary>network logon</primary></indexterm>
+ The Client for Microsoft Networks Properties panel is the correct location to configure network logon
+ settings. See <link linkend="WME010"></link>.
+ <figure id="WME010"><title>Client for Microsoft Networks Properties Panel.</title><imagefile>WME010</imagefile></figure>
+ </para>
+
+ <para>
+<indexterm><primary>Windows NT domain name</primary></indexterm>
+<indexterm><primary>domain name</primary></indexterm>
+ Enter the Windows NT domain name, check the <guimenu>Log on to Windows NT domain</guimenu> box,
+ and click <guimenu>OK</guimenu>.
+ </para></step>
+
+ <step><para>
+<indexterm><primary>Identification</primary></indexterm>
+<indexterm><primary>workgroup</primary></indexterm>
+<indexterm><primary>computer name</primary></indexterm>
+ 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>.
+ <figure id="WME013"><title>Identification Panel.</title><imagefile>WME013</imagefile></figure>
+ </para></step>
+
+ <step><para>
+<indexterm><primary>Access Control</primary></indexterm>
+<indexterm><primary>group accounts</primary></indexterm>
+<indexterm><primary>domain user</primary></indexterm>
+<indexterm><primary>User-level access control</primary></indexterm>
+ 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>.
+ <figure id="WME014"><title>Access Control Panel.</title><imagefile>WME014</imagefile></figure>
+ </para></step>
+
+ </procedure>
+
+ </sect2>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+<indexterm><primary>networking systems</primary></indexterm>
+<indexterm><primary>errors that can afflict</primary></indexterm>
+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>
+<indexterm><primary>Windows NT/200x/XP Professional</primary></indexterm>
+<indexterm><primary>cannot join domain</primary></indexterm>
+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 the Samba server.</para></listitem>
+</itemizedlist>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-foreword-cargill.xml b/docs-xml/Samba3-HOWTO/TOSHARG-foreword-cargill.xml
new file mode 100644
index 0000000000..6331d2fd4e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-foreword-cargill.xml
@@ -0,0 +1,79 @@
+<?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>
+When John first asked me to write an introductory piece for his latest book, I was somewhat mystified as to
+why he chose me. A conversation with John provided some of the rationale, and he left it to me to fill in the
+<emphasis>rest</emphasis> of the story. So, if you are willing to endure a little bit of background, I will
+provide the part of the story that John wouldn't provide.
+</para>
+
+<para>
+I am the Director of Corporate Standards at Sun Microsystems, and manage Sun's standards portfolio. Before
+that, I was the Director of Standards at Netscape, which was when I met John. Before Sun, there was Digital
+Equipment Corporation, also standards. I've written several books on standards, and tend to observe (and
+occasionally help) the technical and business trends that drive standardization as a discipline. I tend to see
+standardization as a management tool, not as a technical discipline and this is part of the rationale that
+John provided.
+</para>
+
+<para>
+The book that you have before you focuses on a particular standardized way of doing something hence, it is a
+book about a standard. The most important thing to keep in mind about a standard is the rationale for its
+creation. Standards are created not for technical reasons, not for business reasons, but for a deeper and much
+more compelling reason. Standards are created and used to allow people to communicate in a meaningful way.
+Every standard, if it is a true standard, has as its entire (and only) goal set the increasing of relevant
+communication between people.
+</para>
+
+<para>
+This primary goal cannot be met however, unless the standard is documented. I have been involved in too many
+standardization efforts when it became apparent that <emphasis>everybody knows</emphasis> was the dominant
+emotion of those providing documentation. <emphasis>They</emphasis> of the ever present <emphasis>they
+say</emphasis> and <emphasis>they know</emphasis> are the bane of good standards. If <emphasis>they
+know</emphasis>, why are you doing a standard?
+</para>
+
+<para>
+A <emphasis>good standard</emphasis> survives because people know how to use it. People know how to use a
+standard when it is so transparent, so obvious, and so easy that it become invisible. And a standard becomes
+invisible only when the documentation describing how to deploy it is clear, unambiguous, and correct. These
+three elements must be present for a standard to be useful, allowing communication and interaction between two
+separate and distinct entities to occur without obvious effort. As you read this book, look for the evidence
+of these three characteristics and notice how they are seamlessly woven into John's text. Clarity and
+unambiguity without <emphasis>correctness</emphasis> provide a technical nightmare. Correctness and clarity
+with ambiguity create <emphasis>maybe bits,</emphasis> and correctness and unambiguity without clarity provide
+a <emphasis>muddle through</emphasis> scenario.
+</para>
+
+<para>
+And this is <emphasis>the rest of the story</emphasis> that John couldn't (or wouldn't) bring himself to
+state. This book provides a clear, concise, unambiguous, and technically valid presentation of Samba to make
+it useful to a user to someone who wants to use the standard to increase communication and the capability
+for communication between two or more entities whether person-machine, machine-machine, or person-person.
+The intent of this book is not to convince anyone of any agenda political, technical, or social. The intent
+is to provide documentation for users who need to know about Samba, how to use it, and how to get on with
+their primary responsibilities. While there is pride on John's part because of the tremendous success of
+the Samba documentation, he writes for the person who needs a tool to accomplish a particular job, and who has
+selected Samba to be that tool.
+</para>
+
+<para>
+The book is a monument to John's perseverance and dedication to Samba and in my opinion to the goal of
+standardization. By writing this book, John has provided the users of Samba those that want to deploy it to
+make things better a clear, easy, and ultimately valuable resource. Additionally, he has increased the
+understanding and utility of a highly useful standard, and for this, as much as for the documentation, he is
+owed a debt of gratitude by those of us who rely on standards to make our lives more manageable.
+</para>
+
+<para>
+<simplelist>
+ <member>Carl Cargill, Senior Director</member>
+ <member>Corporate Standardization, The Office of the CTO</member>
+ <member>Sun Microsystems</member>
+</simplelist>
+</para>
+
+</preface>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-foreword-tridge.xml b/docs-xml/Samba3-HOWTO/TOSHARG-foreword-tridge.xml
new file mode 100644
index 0000000000..34bc37314d
--- /dev/null
+++ b/docs-xml/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-xml/Samba3-HOWTO/TOSHARG-glossary.xml b/docs-xml/Samba3-HOWTO/TOSHARG-glossary.xml
new file mode 100644
index 0000000000..6410e3e0f7
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-glossary.xml
@@ -0,0 +1,254 @@
+<?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 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 hostnames 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 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 nonroutable
+ 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 1980s
+ 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 (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>
+
+ <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 distributes 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>
+ PPDs specify and control options supported by PostScript printers, such as duplexing, stapling,
+ and 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>Remote Procedure Call</glossterm>
+ <acronym>RPC</acronym>
+ <glossdef><para>
+ RPCs are a means for executing network operations. The RPC protocol is independent of transport protocols. RPC
+ does not try to implement any kind of reliability and the application that uses RPCs must be aware of the type
+ of transport protocol underneath RPC. An RPC is like a programmatic jump subroutine over a network. RPCs used
+ in the UNIX environment are specified in RFC 1050. RPC is a powerful technique for constructing distributed,
+ client-server based applications. It is based on extending the notion of conventional, or local procedure
+ calling, so that the called procedure need not exist in the same address space as the calling procedure. The
+ two processes may be on the same system, or they may be on different systems with a network connecting them.
+ By using RPC, programmers of distributed applications avoid the details of the interface with the network. The
+ transport independence of RPC isolates the application from the physical and logical elements of the data
+ communications mechanism and allows the application to use a variety of transports.
+ </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 1980s by IBM and adopted
+ and extended further by Microsoft. Microsoft
+ renamed the protocol to CIFS during the Internet hype in the
+ 1990s.
+ </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-xml/Samba3-HOWTO/TOSHARG-inside-cover.xml b/docs-xml/Samba3-HOWTO/TOSHARG-inside-cover.xml
new file mode 100644
index 0000000000..f1b1990d4c
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-inside-cover.xml
@@ -0,0 +1,43 @@
+<?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 lang="en-US">
+<title>About the Cover Artwork</title>
+
+ <para>
+ The cover artwork of this book continues the freedom theme of the first edition of <quote>The Official Samba-3
+ HOWTO and Reference Guide</quote>. We may look back upon the past to question the motives of those who have
+ gone before us. Seldom do we realise that the past owes us no answer, and despite what we may think of the
+ actions of those who have travelled lifes' road before us, we must feel a sense of pride and gratitude for
+ those who, in the past, have protected our liberties.
+ </para>
+
+ <para>
+ Developments in information technology continue to move at an alarming pace. Human nature causes us
+ to adopt and embrace new developments that appear to answer the needs of the moment, but that can entrap
+ us at a future date. There are many examples in the short history of information technology. MS-DOS was
+ seen as a tool that liberated users from the tyrany of large computer system operating costs, and that
+ made possible the rapid progres we are beneficiaries of today. Yet today we are inclined to look back with
+ disdain on MS-DOS as an obsolete and constraining technology that belongs are an era that is best
+ forgotten.
+ </para>
+
+ <para>
+ The embrace of Windows networking, Windows NT4, and MS Active Directory in more recent times, may seem
+ modern and progressive today, but sooner or later something better will replace them. The current
+ preoccupation with extended identity management solutions and with directories is not unexpected.
+ The day will come that these too will be evaluated, and what may seem refreshing and powerful may
+ be better recogized as the chilly winds of the night. To argue against progress is unthinkable,
+ no matter what may lie ahead.
+ </para>
+
+ <para>
+ The development of Samba is moving forwards. The changes since Samba 3.0.0 are amazing, yet many
+ users would like to see more and faster progress. The benefits of recent developments can be realized
+ quickly, but documentation is necessary to unlock the pandoras' box. It is our hope that this book
+ will help the network administrator to rapidly deploy the new features with minimum effort. As you
+ deploy and gain mileage from the new enablement, take the time to think through what may lie ahead.
+ Above all, take stock of the freedom of choice that Samba provides in your world, and enjoy the new
+ potential for seamless interoperability.
+ </para>
+
+</preface>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-locking.xml b/docs-xml/Samba3-HOWTO/TOSHARG-locking.xml
new file mode 100644
index 0000000000..ee48f8c90d
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-locking.xml
@@ -0,0 +1,1140 @@
+<?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>
+<indexterm><primary>locking</primary></indexterm>
+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>
+<indexterm><primary>locking semantics</primary></indexterm>
+Samba provides all the same locking semantics that MS Windows clients expect
+and that MS Windows NT4/200x servers also provide.
+</para>
+
+<para>
+<indexterm><primary>locking</primary></indexterm>
+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>
+<indexterm><primary>opportunistic locking</primary></indexterm>
+<indexterm><primary>locking protocol</primary></indexterm>
+<indexterm><primary>performance advantage</primary></indexterm>
+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>
+<indexterm><primary>registry</primary></indexterm>
+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>
+<indexterm><primary>disable locking</primary></indexterm>
+Sometimes it is necessary to disable locking control settings on the Samba
+server as well as on each MS Windows client!
+</para>
+</note>
+
+</sect1>
+
+<sect1>
+<title>Discussion</title>
+
+<para>
+<indexterm><primary>record locking</primary></indexterm>
+<indexterm><primary>deny modes</primary></indexterm>
+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 an open file. The second is the <emphasis>deny modes</emphasis>
+that are specified when a file is open.
+</para>
+
+<para>
+<indexterm><primary>locking semantics</primary></indexterm>
+<indexterm><primary>record locking</primary></indexterm>
+<indexterm><primary>locking</primary></indexterm>
+<indexterm><primary>byte ranges</primary></indexterm>
+<indexterm><primary>UNIX locking</primary></indexterm>
+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
+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>
+<indexterm><primary>record locking</primary></indexterm>
+<indexterm><primary>byte-range lock</primary></indexterm>
+Samba 2.2 and above implement record locking completely independently of the
+underlying UNIX system. If a byte-range lock that the client requests happens
+to fall into the range of 0 to 2^31, Samba hands this request down to the UNIX system.
+No other locks can be seen by UNIX, anyway.
+</para>
+
+<para>
+<indexterm><primary>check for locks</primary></indexterm>
+<indexterm><primary>rpc.lockd</primary></indexterm>
+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 because clients are
+independently supposed to 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>
+<indexterm><primary>byte-range locking</primary></indexterm>
+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 CD-ROMs). In this case, Samba fakes the return codes of locking calls to
+tell clients that everything is okay.
+</para>
+
+<para>
+<indexterm><primary>deny modes</primary></indexterm>
+<indexterm><primary>DENY_NONE</primary></indexterm>
+<indexterm><primary>DENY_READ</primary></indexterm>
+<indexterm><primary>DENY_WRITE</primary></indexterm>
+<indexterm><primary>DENY_ALL</primary></indexterm>
+<indexterm><primary>DENY_FCB</primary></indexterm>
+<indexterm><primary>DENY_DOS</primary></indexterm>
+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>
+<indexterm><primary>opportunistic locking</primary></indexterm>
+<indexterm><primary>oplocks</primary></indexterm>
+<indexterm><primary>caching</primary></indexterm>
+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 the following:
+</para>
+
+<variablelist>
+ <varlistentry><term>Read-ahead:</term>
+ <listitem><para>
+<indexterm><primary>Read-ahead</primary></indexterm>
+ The client reads the local copy of the file, eliminating network latency.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>Write caching:</term>
+ <listitem><para>
+<indexterm><primary>Write caching</primary></indexterm>
+ The client writes to the local copy of the file, eliminating network latency.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>Lock caching:</term>
+ <listitem><para>
+<indexterm><primary>Lock caching</primary></indexterm>
+ The client caches application locks locally, eliminating network latency.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<indexterm><primary>performance enhancement</primary></indexterm>
+<indexterm><primary>oplocks</primary></indexterm>
+<indexterm><primary>deny-none</primary></indexterm>
+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 Four Kinds of Oplocks:</title>
+
+ <varlistentry><term>Level1 Oplock</term>
+ <listitem><para>
+<indexterm><primary>Level1 Oplock</primary></indexterm>
+<indexterm><primary>redirector</primary></indexterm>
+<indexterm><primary>concurrent access</primary></indexterm>
+<indexterm><primary>cached local file</primary></indexterm>
+ 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>
+<indexterm><primary>oplock break</primary></indexterm>
+<indexterm><primary>flush local locks</primary></indexterm>
+<indexterm><primary>deferred open</primary></indexterm>
+<indexterm><primary>byte-range locking</primary></indexterm>
+ If a second process attempts to open the file, the open
+ is deferred while the redirector "breaks" the original
+ oplock. The oplock break signals the caching client to
+ write the local file back to the server, flush the
+ local locks, and discard read-ahead data. The break is
+ then complete, the deferred open is granted, and the
+ multiple processes can enjoy concurrent file access as
+ dictated by mandatory or byte-range locking options.
+ However, if the original opening process opened the
+ file with a share mode other than deny-none, then the
+ second process is granted limited or no access, despite
+ the oplock break.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>Level2 Oplock</term>
+ <listitem><para>
+<indexterm><primary>Level2 Oplock</primary></indexterm>
+<indexterm><primary>Level1 oplock</primary></indexterm>
+<indexterm><primary>caching</primary></indexterm>
+ 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>
+<indexterm><primary>Filter Oplock</primary></indexterm>
+ Does not allow write or delete file access.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>Batch Oplock</term>
+ <listitem><para>
+<indexterm><primary>Batch Oplock</primary></indexterm>
+ Manipulates file openings and closings and allows caching
+ of file attributes.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<indexterm><primary>oplocks</primary></indexterm>
+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>
+<indexterm><primary>Opportunistic locking</primary></indexterm>
+<indexterm><primary>client-side data caching</primary></indexterm>
+<indexterm><primary>data caching</primary></indexterm>
+<indexterm><primary>oplock break</primary></indexterm>
+<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 oplocks 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>
+<indexterm><primary>client-side caching</primary></indexterm>
+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
+oplocks 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 counterproductive.
+</para>
+
+<para>
+<indexterm><primary>oplocks</primary></indexterm>
+Oplocks 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 oplocks may be effectively configured.
+</para>
+
+<para>
+<indexterm><primary>oplocks</primary></indexterm>
+<indexterm><primary>high-availability</primary></indexterm>
+Windows oplocks is a lightweight performance-enhancing
+feature. It is not a robust and reliable protocol. Every
+implementation of oplocks should be evaluated as a
+trade-off 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 multiuser corporate database during a tropical
+storm. This configuration will likely encounter problems with oplocks.
+</para>
+
+<para>
+<indexterm><primary>mission-critical</primary></indexterm>
+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 oplocks 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
+oplocks 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
+failover replacement will be available immediately to provide
+continuous data availability.
+</para>
+
+<para>
+<indexterm><primary>Windows client failover</primary></indexterm>
+<indexterm><primary>transport connection loss</primary></indexterm>
+Windows client failover 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 failover &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>
+<indexterm><primary>caching writes</primary></indexterm>
+<indexterm><primary>caching reads</primary></indexterm>
+<indexterm><primary>oplock break</primary></indexterm>
+If a client session has been caching writes and reads locally due to
+oplocks, 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 failover 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 oplocks. Ideally, comprehensive
+testing should be done with all affected applications with oplocks
+enabled and disabled.
+</para>
+
+<sect3>
+<title>Exclusively Accessed Shares</title>
+
+<para>
+Oplocks 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 oplocks 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 oplocks 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 oplocks
+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>
+<indexterm><primary>NFS clients</primary></indexterm>
+<indexterm><primary>data corruption</primary></indexterm>
+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 oplocks off.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Slow and/or Unreliable Networks</title>
+
+<para>
+<indexterm><primary>performance improvement</primary></indexterm>
+<indexterm><primary>WAN</primary></indexterm>
+<indexterm><primary>latency</primary></indexterm>
+The biggest potential performance improvement for oplocks
+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 in which to utilize oplocks.
+</para>
+
+<para>
+If the network is slow, unreliable, or a WAN, then do not configure
+oplocks if there is any chance of multiple users
+regularly opening the same file.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Multiuser Databases</title>
+
+<para>
+<indexterm><primary>Multiuser databases</primary></indexterm>
+<indexterm><primary>management bottleneck</primary></indexterm>
+<indexterm><primary>oplocks disabled</primary></indexterm>
+Multiuser databases clearly pose a risk due to their very nature &smbmdash; they are typically heavily
+accessed by numerous users at random intervals. Placing a multiuser database on a share with oplocks 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 oplocks disabled.
+</para>
+
+</sect3>
+
+<sect3>
+<title>PDM Data Shares</title>
+
+<para>
+<indexterm><primary>PDM</primary></indexterm>
+<indexterm><primary>Process data management</primary></indexterm>
+<indexterm><primary>client-side data caching</primary></indexterm>
+<indexterm><primary>oplocks management</primary></indexterm>
+<indexterm><primary>disabling oplocks</primary></indexterm>
+Process data management (PDM) applications such as IMAN, Enovia, and Clearcase are increasing in usage with
+Windows client platforms and therefore with SMB datastores. PDM applications manage multiuser 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 oplocks management, by disabling oplocks on the share.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Beware of Force User</title>
+
+<para>
+<indexterm><primary>oplock break</primary></indexterm>
+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 oplocks 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>
+ Oplocks enabled.
+ </para></listitem>
+</itemizedlist>
+
+</sect3>
+
+<sect3>
+<title>Advanced Samba Oplocks Parameters</title>
+
+<para>
+<indexterm><primary>oplock parameters</primary></indexterm>
+<indexterm><primary>oplock mechanism</primary></indexterm>
+<indexterm><primary>implementing oplocks</primary></indexterm>
+Samba provides oplock 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"/>, and
+<smbconfoption name="oplock contention limit"/>.
+</para>
+
+<para>
+<indexterm><primary>turn oplocks off</primary></indexterm>
+For most users, administrators, and environments, if these parameters
+are required, then the better option is simply to 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
+failover replacement will be available immediately to provide
+continuous data availability.
+</para>
+
+<para>
+Windows client failover 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 failover &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
+oplocks, 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, if the client was writing data to the file server
+real-time, then the failover will provide the data on disk as it
+existed at the time of the disconnect.
+</para>
+
+<para>
+In mission-critical, high-availability environments, careful attention
+should be given to oplocks. Ideally, comprehensive
+testing should be done with all affected applications with oplocks
+enabled and disabled.
+</para>
+
+</sect3>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Samba Oplocks Control</title>
+
+<para>
+Oplocks 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.
+Oplocks 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 oplocks as a server-side
+component of the client caching mechanism. Because of the lightweight
+nature of the Windows feature design, effective configuration of
+oplocks 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>
+Oplocks essentially means that the client is allowed to download and cache
+a file on its 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, because 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>
+<emphasis>Veto oplocks</emphasis> 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>
+<example id="far1">
+<title>Share with Some Files Oplocked</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+</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:
+</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 enabled on a per-share basis, or globally for
+the entire server, in the &smb.conf; file as shown in <link linkend="far3"/>.
+</para>
+
+<para>
+<example id="far3">
+<title>Configuration with Oplock Break Contention Limit</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+</para>
+
+</sect3>
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>MS Windows Oplocks and Caching Controls</title>
+
+<para>
+There is a known issue when running applications (like Norton Antivirus) 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. 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 oplocks 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 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 oplocks 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 oplocks 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 oplocks 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 oplocks 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 follows:
+</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 oplocks 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 WANs.
+</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 I/O and oplocks 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 oplocks 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 oplocks (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/switches. 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 3 years)
+ and all attempts to reproduce the problem have failed. The Samba Team has been
+ unable to catch this happening and thus unable 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
+ 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 to 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 indicates 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>
+
+<indexterm><primary>KB 812937</primary></indexterm>
+ <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>
+
+<indexterm><primary>KB 811492</primary></indexterm>
+ <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 documentation regarding file and record locking issues on the Microsoft
+<ulink url="http://support.microsoft.com/">Support</ulink> web site. Additionally, search for the word
+<literal>locking</literal> on the Samba <ulink url="http://www.samba.org/">web</ulink> site.
+</para>
+
+<para>
+Section of the Microsoft MSDN Library on opportunistic locking:
+</para>
+
+<para>
+<indexterm><primary>KB 224992</primary></indexterm>
+Microsoft Knowledge Base, <quote>Maintaining Transactional Integrity with OPLOCKS</quote>,
+Microsoft Corporation, April 1999, <ulink noescape="1" url="http://support.microsoft.com/?id=224992">Microsoft
+KB Article 224992</ulink>.
+</para>
+
+<para>
+<indexterm><primary>KB 296264</primary></indexterm>
+Microsoft Knowledge Base, <quote>Configuring Opportunistic Locking in Windows 2000</quote>,
+Microsoft Corporation, April 2001 <ulink noescape="1" url="http://support.microsoft.com/?id=296264">Microsoft KB Article 296264</ulink>.
+</para>
+
+<para>
+<indexterm><primary>KB 129202</primary></indexterm>
+Microsoft Knowledge Base, <quote>PC Ext: Explanation of Opportunistic Locking on Windows NT</quote>,
+Microsoft Corporation, April 1995 <ulink noescape="1" url="http://support.microsoft.com/?id=129202">Microsoft
+KB Article 129202</ulink>.
+</para>
+
+</sect1>
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml b/docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml
new file mode 100644
index 0000000000..528f41d8cb
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml
@@ -0,0 +1,176 @@
+<?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 &amp; 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>
+<indexterm><primary>distributed file system</primary><see>DFS</see></indexterm>
+<indexterm><primary>physical locations</primary></indexterm>
+<indexterm><primary>higher availability</primary></indexterm>
+<indexterm><primary>load balancing</primary></indexterm>
+<indexterm><primary>logical directories</primary></indexterm>
+ 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>
+<indexterm><primary>DFS</primary></indexterm>
+<indexterm><primary>DFS tree</primary></indexterm>
+<indexterm><primary>DFS-aware</primary></indexterm>
+ 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>
+<indexterm><primary>DFS server</primary></indexterm>
+<indexterm><primary>share-level</primary></indexterm>
+<indexterm><primary>DFS junction</primary></indexterm>
+<indexterm><primary>DFS-aware</primary></indexterm>
+ 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-&gt;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>
+<indexterm><primary>DFS-aware</primary></indexterm>
+<indexterm><primary>DFS tree</primary></indexterm>
+<indexterm><primary>DFS links</primary></indexterm>
+<indexterm><primary>DFS</primary></indexterm>
+ DFS trees on Samba work with all DFS-aware clients ranging from Windows 95 to 200x.
+ <link linkend="dfscfg">The 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>
+
+<example id="dfscfg">
+<title>smb.conf with DFS Configured</title>
+<smbconfblock>
+<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>
+</smbconfblock>
+</example>
+
+ <para>
+<indexterm><primary>DFS root</primary></indexterm>
+<indexterm><primary>msdfs links</primary></indexterm>
+<indexterm><primary>symbolic links</primary></indexterm>
+ 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>
+<indexterm><primary>DFS-aware clients</primary></indexterm>
+<indexterm><primary>DFS tree</primary></indexterm>
+ Users on DFS-aware clients can now browse the DFS tree on the Samba server at
+ <constant>\\samba\dfs</constant>. 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 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>
+ <quote>For example, I had a share defined as such:</quote>
+ <smbconfblock>
+ <smbconfsection name="[pub]"/>
+ <smbconfoption name="path">/export/home/Shares/public_share</smbconfoption>
+ <smbconfoption name="msdfs root">yes</smbconfoption>
+ </smbconfblock>
+ <quote>and I could not make my Windows 9x/Me (with the dfs client installed) follow this symlink:</quote>
+ <screen>
+ damage1 -> msdfs:damage\test-share
+ </screen>
+ </para>
+
+ <para>
+ <quote>Running a debug level of 10 reveals:</quote>
+ <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>
+ <quote>Curious. So I changed the directory name from <constant>.../Shares/...</constant> to
+ <constant>.../shares/...</constant> (along with my service definition) and it worked!</quote>
+ </para>
+
+ </sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-preface.xml b/docs-xml/Samba3-HOWTO/TOSHARG-preface.xml
new file mode 100644
index 0000000000..43df53e523
--- /dev/null
+++ b/docs-xml/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-xml/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml b/docs-xml/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
new file mode 100644
index 0000000000..aa879aeb0a
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
@@ -0,0 +1,871 @@
+<?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>August 16, 2007</pubdate>
+</chapterinfo>
+
+<title>Updating and Upgrading Samba</title>
+<para>
+This chapter provides a detailed record of changes made during the 3.x series releases. At this time this
+series consists of the 3.0.x series that is under the GNU GPL version 2 license, and the Samba 3.2.x series
+that is being released under the terms of the GNU GPL version 3 license.
+</para>
+
+<sect1>
+<title>Key Update Requirements</title>
+<para>
+Samba is a fluid product in which there may be significant changes between releases. Some of these changes are
+brought about as a result of changes in the protocols that are used by Microsoft Windows network clients as a
+result of security or functionality updates through official Microsoft patches and updates. Samba must track
+such changes, particularly where they affect the internal operation of Samba itself.
+</para>
+
+<para>
+Please refer to any notes below that make explicit mention of the version of Samba you are using. In general,
+all changes that apply to a new release will apply to follow-on releases also. For example, changes to Samba
+3.0.23 affect all releases up to an including 3.0.25 and later. Samba 3.2.x was originaly cut from Samba
+3.0.25 before 3.2.0-specific changes were applied. Unless a 3.0.x series feature is specifically revoked, the
+behavior of the 3.2.x series can be expected to follow the earlier pattern.
+</para>
+
+<sect2>
+<title>Upgrading from Samba-3.0.x to Samba-3.2.0</title>
+<para>
+</para>
+</sect2>
+
+<sect2 id="oldupdatenotes">
+<title>Upgrading from Samba-2.x to Samba-3.0.25</title>
+<para>
+<indexterm><primary>Samba differences</primary></indexterm>
+<indexterm><primary>changed parameters</primary></indexterm>
+<indexterm><primary>simple guide</primary></indexterm>
+This chapter deals exclusively with the differences between Samba-3.0.25 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.25.
+</para>
+</sect2>
+
+<sect2>
+<title>Quick Migration Guide</title>
+
+<para>
+Samba-3.0.25 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>
+<indexterm><primary>behavior approximately same</primary></indexterm>
+<indexterm><primary>differing protocol</primary></indexterm>
+So why say that <emphasis>behavior should be approximately the same as Samba-2.2.x</emphasis>? Because
+Samba-3.0.25 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>
+<indexterm><primary>LDAP backend</primary></indexterm>
+<indexterm><primary>database</primary></indexterm>
+<indexterm><primary>pdbedit</primary></indexterm>
+<indexterm><primary>Samba-3-compatible LDAP backend</primary></indexterm>
+If the Samba-2.2.x system is 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>
+
+</sect2>
+</sect1>
+
+<sect1>
+<title>New Featuers in Samba-3.x Series</title>
+<para>
+</para>
+
+<sect2>
+<title>New Features in Samba-3.2.x Series</title>
+<para>
+</para>
+</sect2>
+
+<sect2>
+<title>New Features in Samba-3.0.x</title>
+
+<para>
+The major new features are:
+</para>
+
+<orderedlist numeration="arabic">
+ <listitem><para>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>LDAP/Kerberos</primary></indexterm>
+ 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>
+<indexterm><primary>Unicode</primary></indexterm>
+<indexterm><primary>multibyte character sets</primary></indexterm>
+ Unicode support. Samba will now negotiate Unicode on the wire, and
+ internally there is a much better infrastructure for multibyte
+ and Unicode character sets.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>authentication system</primary></indexterm>
+ 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>
+<indexterm><primary>filename mangling</primary></indexterm>
+ New filename mangling system. The filename mangling system has been
+ completely rewritten. An internal database now stores mangling maps
+ persistently.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>net command</primary></indexterm>
+ 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>
+<indexterm><primary>status32 codes</primary></indexterm>
+ Samba now negotiates NT-style status32 codes on the wire. This
+ considerably improves error handling.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>printer attributes publishing</primary></indexterm>
+ Better Windows 200x/XP printing support, including publishing
+ printer attributes in Active Directory.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>RPC modules</primary></indexterm>
+<indexterm><primary>passdb backends</primary></indexterm>
+<indexterm><primary>character sets</primary></indexterm>
+ New loadable RPC modules for passdb backends and character sets.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>dual-daemon winbindd</primary></indexterm>
+ New default dual-daemon winbindd support for better performance.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>migrating</primary></indexterm>
+<indexterm><primary>maintaining ids</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+ 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>
+<indexterm><primary>trust relationships</primary></indexterm>
+<indexterm><primary>domain controllers</primary></indexterm>
+ Support for establishing trust relationships with Windows NT 4.0
+ domain controllers.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>Winbind architecture</primary></indexterm>
+<indexterm><primary>LDAP directory</primary></indexterm>
+<indexterm><primary>ID mapping</primary></indexterm>
+ 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>
+<indexterm><primary>SMB signing</primary></indexterm>
+<indexterm><primary>security settings</primary></indexterm>
+ 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>
+
+
+<sect3>
+<title>Configuration Parameter Changes</title>
+
+<para>
+This section contains a brief listing of changes to &smb.conf; options since the Samba-2.2.x series up to and
+including Samba-3.0.25.
+</para>
+
+<para>
+Please refer to the smb.conf(5) man page for complete descriptions of new or modified
+parameters.
+</para>
+
+<para>
+Whenever a Samba update or upgrade is performed it is highly recommended to read the file called
+<emphasis>WHATSNEW.txt</emphasis> that is part of the Samba distribution tarball. This file may also
+be obtain on-line from the Samba <ulink url="http://www.samba.org/samba/">web site</ulink>, in
+the right column, under Current Stable Release, by clicking on <emphasis>Release Notes</emphasis>.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Removed Parameters</title>
+
+<indexterm><primary>deleted parameters</primary></indexterm>
+<para>
+In alphabetical order, these are the parameters eliminated from Samba-2.2.x through 3.0.25.
+</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>enable rid algorithm</para></listitem>
+ <listitem><para>enable svcctl</para></listitem>
+ <listitem><para>force unknown acl user</para></listitem>
+ <listitem><para>hosts equiv</para></listitem>
+ <listitem><para>ldap filter</para></listitem>
+ <listitem><para>min password length</para></listitem>
+ <listitem><para>nt smb support</para></listitem>
+ <listitem><para>post script</para></listitem>
+ <listitem><para>printer admin</para></listitem>
+ <listitem><para>printer driver</para></listitem>
+ <listitem><para>printer driver file</para></listitem>
+ <listitem><para>printer driver location</para></listitem>
+ <listitem><para>read size</para></listitem>
+ <listitem><para>source environment</para></listitem>
+ <listitem><para>status </para></listitem>
+ <listitem><para>strip dot </para></listitem>
+ <listitem><para>total print jobs</para></listitem>
+ <listitem><para>unicode</para></listitem>
+ <listitem><para>use rhosts</para></listitem>
+ <listitem><para>valid chars</para></listitem>
+ <listitem><para>vfs options</para></listitem>
+ <listitem><para>winbind enable local accounts</para></listitem>
+ <listitem><para>winbind max idle children</para></listitem>
+ <listitem><para>wins partners</para></listitem>
+</itemizedlist>
+
+</sect3>
+
+<sect3>
+<title>New Parameters</title>
+
+<para>The following new parameters have been released up to and including Samba 3.0.25 (grouped by function:)</para>
+
+<para>Remote Management</para>
+
+<indexterm><primary>new parameters</primary></indexterm>
+
+<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>rename user script</para></listitem>
+ <listitem><para>set primary group script</para></listitem>
+ <listitem><para>username map script</para></listitem>
+</itemizedlist>
+
+<para>Authentication</para>
+
+<itemizedlist>
+ <listitem><para>auth methods</para></listitem>
+ <listitem><para>ldap password sync</para></listitem>
+ <listitem><para>passdb expand explicit</para></listitem>
+ <listitem><para>realm</para></listitem>
+</itemizedlist>
+
+<para>Protocol Options</para>
+
+<itemizedlist>
+ <listitem><para>add port command</para></listitem>
+ <listitem><para>afs token lifetime</para></listitem>
+ <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>defer sharing violations</para></listitem>
+ <listitem><para>disable netbios</para></listitem>
+ <listitem><para>dmapi support</para></listitem>
+ <listitem><para>enable privileges</para></listitem>
+ <listitem><para>use kerberos keytab</para></listitem>
+ <listitem><para>log nt token command</para></listitem>
+ <listitem><para>ntlm auth</para></listitem>
+ <listitem><para>paranoid server security </para></listitem>
+ <listitem><para>sendfile</para></listitem>
+ <listitem><para>server schannel</para></listitem>
+ <listitem><para>server signing</para></listitem>
+ <listitem><para>smb ports</para></listitem>
+ <listitem><para>svcctl list</para></listitem>
+ <listitem><para>use spnego</para></listitem>
+</itemizedlist>
+
+<para>File Service</para>
+
+<itemizedlist>
+ <listitem><para>allocation roundup size</para></listitem>
+ <listitem><para>acl check permissions</para></listitem>
+ <listitem><para>acl group control</para></listitem>
+ <listitem><para>acl map full control</para></listitem>
+ <listitem><para>aio read size</para></listitem>
+ <listitem><para>aio write size</para></listitem>
+ <listitem><para>dfree cache time</para></listitem>
+ <listitem><para>dfree command</para></listitem>
+ <listitem><para>ea support</para></listitem>
+ <listitem><para>enable asu support</para></listitem>
+ <listitem><para>fam change notify</para></listitem>
+ <listitem><para>force unknown acl user</para></listitem>
+ <listitem><para>get quota command</para></listitem>
+ <listitem><para>hide special files</para></listitem>
+ <listitem><para>hide unwriteable files</para></listitem>
+ <listitem><para>inherit owner</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>map read only</para></listitem>
+ <listitem><para>max stat cache size</para></listitem>
+ <listitem><para>msdfs proxy</para></listitem>
+ <listitem><para>open files database hash size</para></listitem>
+ <listitem><para>set quota command</para></listitem>
+ <listitem><para>store dos attributes</para></listitem>
+ <listitem><para>use sendfile</para></listitem>
+ <listitem><para>usershare allow guests</para></listitem>
+ <listitem><para>usershare max shares</para></listitem>
+ <listitem><para>usershare owner only</para></listitem>
+ <listitem><para>usershare path</para></listitem>
+ <listitem><para>usershare prefix allow list</para></listitem>
+ <listitem><para>usershare prefix deny list</para></listitem>
+ <listitem><para>usershare template share</para></listitem>
+ <listitem><para>vfs objects</para></listitem>
+</itemizedlist>
+
+<para>Printing</para>
+
+<itemizedlist>
+ <listitem><para>cups options</para></listitem>
+ <listitem><para>cups server</para></listitem>
+ <listitem><para>force printername</para></listitem>
+ <listitem><para>iprint server</para></listitem>
+ <listitem><para>max reported print jobs</para></listitem>
+ <listitem><para>printcap cache time</para></listitem>
+</itemizedlist>
+
+
+<para>Unicode and Character Sets</para>
+
+<itemizedlist>
+ <listitem><para>display charset</para></listitem>
+ <listitem><para>dos charset</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>username map script</para></listitem>
+ <listitem><para>winbind nss info</para></listitem>
+ <listitem><para>winbind offline logon</para></listitem>
+ <listitem><para>winbind refresh tickets</para></listitem>
+ <listitem><para>winbind trusted domains only</para></listitem>
+ <listitem><para>template primary group</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 replication sleep</para></listitem>
+ <listitem><para>ldap timeout</para></listitem>
+ <listitem><para>ldap user suffix</para></listitem>
+</itemizedlist>
+
+<para>General Configuration</para>
+
+<itemizedlist>
+ <listitem><para>eventlog list</para></listitem>
+ <listitem><para>preload modules</para></listitem>
+ <listitem><para>reset on zero vc</para></listitem>
+ <listitem><para>privatedir</para></listitem>
+</itemizedlist>
+
+</sect3>
+
+<sect3>
+<title>Modified Parameters (Changes in Behavior)</title>
+
+<itemizedlist>
+ <listitem><para>acl group control (new default is No, deprecated parameter)</para></listitem>
+ <listitem><para>change notify timeout (scope changed)</para></listitem>
+ <listitem><para>dos filemode (disabled by default)</para></listitem>
+ <listitem><para>dos filetimes (enabled by default)</para></listitem>
+ <listitem><para>enable asu support (disabled by default)</para></listitem>
+ <listitem><para>enable privileges (enabled by default)</para></listitem>
+ <listitem><para>encrypt passwords (enabled by default) </para></listitem>
+ <listitem><para>host msdfs (enabled by default)</para></listitem>
+ <listitem><para>mangling method (set to hash2 by default) </para></listitem>
+ <listitem><para>map to guest</para></listitem>
+ <listitem><para>only user (deprecated)</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 (auto by default)</para></listitem>
+ <listitem><para>winbind cache time (increased to 5 minutes)</para></listitem>
+ <listitem><para>winbind enum groups (disabled by default)</para></listitem>
+ <listitem><para>winbind enum users (disabled by default)</para></listitem>
+ <listitem><para>winbind nested groups (enabled by default)</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>
+ <listitem><para>winbindd nss info</para></listitem>
+ <listitem><para>write cache (deprecated)</para></listitem>
+</itemizedlist>
+
+</sect3>
+
+</sect2>
+
+<sect2>
+<title>New Functionality</title>
+
+ <para>
+<indexterm><primary>major changes</primary></indexterm>
+ The major changes in behavior since that Samba-2.2.x series are documented in this section.
+ Please refer to the <filename>WHATSNEW.txt</filename> file that ships with every release of
+ Samba to obtain detailed information regarding the changes that have been made during the
+ life of the current Samba release.
+ </para>
+
+ <sect3>
+ <title>TDB Data Files</title>
+
+<indexterm><primary>tdb data files</primary></indexterm>
+ <para>
+ Refer to <link linkend="install">Installation, Chapter 1</link>, <link linkend="tdbdocs">Chapter 1</link>
+ for information pertaining to the Samba-3 data files, their location and the information that must be
+ preserved across server migrations, updates and upgrades.
+ </para>
+
+ <para>
+<indexterm><primary>tdb file backup</primary></indexterm>
+ Please remember to back up your existing ${lock directory}/*tdb before upgrading to Samba-3. If necessary,
+ Samba will upgrade databases as they are opened. Downgrading from Samba-3 to 2.2, or reversion to an earlier
+ version of Samba-3 from a later release, is an unsupported path.
+ </para>
+
+ <para>
+<indexterm><primary>tdb file descriptions</primary></indexterm>
+ The old Samba-2.2.x tdb files are described in <link linkend="oldtdbfiledesc">the next table</link>.
+ </para>
+
+
+ <table frame='all' id="oldtdbfiledesc"><title>Samba-2.2.x 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>brlock</entry>
+ <entry>Byte-range file locking information.</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>connections</entry>
+ <entry><para>Client connection information</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>locking</entry>
+ <entry>Temporary file locking data.</entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>messages</entry>
+ <entry><para>Temporary storage of messages being processed by smbd.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>ntdrivers</entry>
+ <entry><para>Stores per-printer driver information.</para></entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>ntforms</entry>
+ <entry><para>Stores per-printer forms information.</para></entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>ntprinters</entry>
+ <entry><para>Stores the per-printer devmode configuration settings.</para></entry>
+ <entry>yes</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 database tables via the winreg RPCs.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>sessionid</entry>
+ <entry><para>Temporary cache for miscellaneous session information.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>share_info</entry>
+ <entry>Share ACL settings.</entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+
+ <entry>unexpected</entry>
+ <entry><para>Packets received for which no process was listening.</para></entry>
+ <entry>no</entry>
+ </row>
+ <row>
+ <entry>winbindd_cache</entry>
+ <entry><para>Cache of identity information received from an NT4 or an ADS domain.</para></entry>
+ <entry>yes</entry>
+ </row>
+ <row>
+ <entry>winbindd_idmap</entry>
+ <entry><para>New ID map table from SIDS to UNIX UIDs/GIDs.</para></entry>
+ <entry>yes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect3>
+
+ <sect3>
+ <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>
+<indexterm><primary>Windows domain</primary></indexterm>
+<indexterm><primary>getpwnam() call</primary></indexterm>
+<indexterm><primary>NT_STATUS_LOGON_FAILURE</primary></indexterm>
+ 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 with the error message <quote>NT_STATUS_LOGON_FAILURE.</quote> There is no current workaround
+ to re-establish the Samba-2.2 behavior.
+ </para></listitem>
+
+ <listitem><para>
+<indexterm><primary>add user script</primary></indexterm>
+<indexterm><primary>add machine script</primary></indexterm>
+ 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>
+
+ </sect3>
+
+ <sect3>
+ <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>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+ 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>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>LDAP</primary></indexterm>
+ 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>
+<indexterm><primary>account storage backends</primary></indexterm>
+ 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>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>net tool</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>
+
+ </sect3>
+
+ <sect3>
+ <title>LDAP</title>
+
+ <para>
+ This section outlines the new features effecting Samba/LDAP integration.
+ </para>
+
+ <sect4>
+ <title>New Schema</title>
+
+ <para>
+<indexterm><primary>object class</primary></indexterm>
+<indexterm><primary>sambaSamAccount</primary></indexterm>
+<indexterm><primary>LDIF</primary></indexterm>
+<indexterm><primary>attributes</primary></indexterm>
+ A new object class (sambaSamAccount) has been introduced to replace
+ the old sambaAccount. This change aids 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:
+<indexterm><primary>ldapsearch</primary></indexterm>
+ </para>
+ <para><screen>
+ &prompt;ldapsearch .... -LLL -b "ou=people,dc=..." &gt; old.ldif
+ &prompt;convertSambaAccount --sid &lt;DOM SID&gt; --input old.ldif --output new.ldif
+ </screen></para>
+
+ <para>
+<indexterm><primary>net</primary><secondary>getlocalsid</secondary></indexterm>
+ The &lt;DOM SID&gt; can be obtained by running
+<screen>
+&prompt;<userinput>net getlocalsid &lt;DOMAINNAME&gt;</userinput>
+</screen>
+<indexterm><primary>PDC</primary></indexterm>
+ on the Samba PDC as root.
+ </para>
+
+ <para>
+ Under Samba-2.x the domain SID can be obtained by executing:
+<indexterm><primary>smbpasswd</primary></indexterm>
+<screen>
+&prompt;<userinput>smbpasswd -S &lt;DOMAINNAME&gt;</userinput>
+</screen>
+ </para>
+
+ <para>
+<indexterm><primary>old sambaAccount</primary></indexterm>
+<indexterm><primary>ldapsam_compat</primary></indexterm>
+<indexterm><primary>object class declaration</primary></indexterm>
+<indexterm><primary>samba.schema</primary></indexterm>
+ The old <literal>sambaAccount</literal> 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 <literal>sambaAccount</literal> has not changed
+ in the Samba-3 <filename>samba.schema</filename> file.
+ </para>
+
+ <para>
+ Other new object classes and their uses include:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+<indexterm><primary>sambaDomain</primary></indexterm>
+<indexterm><primary>domain information</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>ldap suffix</primary></indexterm>
+<indexterm><primary>ldapsam</primary></indexterm>
+<indexterm><primary>idmap</primary></indexterm>
+ <literal>sambaDomain</literal> &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>
+<indexterm><primary>sambaGroupMapping</primary></indexterm>
+<indexterm><primary>ldap group suffix</primary></indexterm>
+<indexterm><primary>net groupmap</primary></indexterm>
+ 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>
+<indexterm><primary>sambaUNIXIdPool</primary></indexterm>
+<indexterm><primary>ldap idmap suffix</primary></indexterm>
+<indexterm><primary>idmap UID</primary></indexterm>
+<indexterm><primary>idmap GID</primary></indexterm>
+ <literal>sambaUNIXIdPool</literal> &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>
+<indexterm><primary>sambaIdmapEntry</primary></indexterm>
+<indexterm><primary>idmap_ldap module</primary></indexterm>
+ <literal>sambaIdmapEntry</literal> &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>
+
+ </sect4>
+
+ <sect4>
+ <title>New Suffix for Searching</title>
+
+ <para>
+<indexterm><primary>LDAP queries</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>ldap suffix</primary></indexterm>
+<indexterm><primary>ldap user suffix</primary></indexterm>
+<indexterm><primary>ldap machine suffix</primary></indexterm>
+<indexterm><primary>ldap group suffix</primary></indexterm>
+<indexterm><primary>ldap idmap suffix</primary></indexterm>
+ 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>
+<indexterm><primary>ldap suffix</primary></indexterm>
+<indexterm><primary>subsuffix parameters</primary></indexterm>
+ If an <parameter>ldap suffix</parameter> is defined, it will be appended to all of the
+ remaining subsuffix 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 domain names with quotation marks.
+ </para>
+
+ </sect4>
+
+ <sect4>
+ <title>IdMap LDAP Support</title>
+
+ <para>
+<indexterm><primary>idmap backend</primary></indexterm>
+ 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 <emphasis>onterose</emphasis> 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</smbconfoption>
+ <smbconfoption name="idmap uid">40000-50000</smbconfoption>
+ <smbconfoption name="idmap gid">40000-50000</smbconfoption>
+ </smbconfblock>
+
+ <para>
+<indexterm><primary>NFS</primary></indexterm>
+ 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>
+
+ </sect4>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs-xml/Samba3-HOWTO/conventions.xml b/docs-xml/Samba3-HOWTO/conventions.xml
new file mode 100644
index 0000000000..1b3848405c
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/conventions.xml
@@ -0,0 +1,60 @@
+<?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>
+ TOSHARG2 is used as an abbreviation for the book, <quote>The Official Samba-3
+ HOWTO and Reference Guide, Second Edition</quote> Editors: John H. Terpstra and Jelmer R. Vernooij,
+ Publisher: Prentice Hall, ISBN: 0131882228.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ S3bE2 is used as an abbreviation for the book, <quote>Samba-3 by Example, Second Edition</quote>
+ Editors: John H. Terpstra, Publisher: Prentice Hall, ISBN: 013188221X.
+ </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-xml/Samba3-HOWTO/gpl-3.0.xml b/docs-xml/Samba3-HOWTO/gpl-3.0.xml
new file mode 100644
index 0000000000..559c89dc4f
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/gpl-3.0.xml
@@ -0,0 +1,836 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<appendix>
+ <title>
+ <acronym>GNU</acronym> General Public License version 3
+ </title>
+ <para>
+ Version 3, 29 June 2007
+ </para>
+ <para>
+ Copyright &copy; 2007 Free Software Foundation, Inc.
+ <ulink url="http://fsf.org/">http://fsf.org/</ulink>
+ </para>
+ <para>
+ Everyone is permitted to copy and distribute verbatim copies of this license
+ document, but changing it is not allowed.
+ </para>
+ <bridgehead renderas="sect1">
+ Preamble
+ </bridgehead>
+ <para>
+ The <acronym>GNU</acronym> General Public License is a free, copyleft
+ license for software and other kinds of works.
+ </para>
+ <para>
+ The licenses for most software and other practical works are designed to
+ take away your freedom to share and change the works. By contrast, the
+ <acronym>GNU</acronym> General Public License is intended to guarantee your
+ freedom to share and change all versions of a program&mdash;to make sure it
+ remains free software for all its users. We, the Free Software Foundation,
+ use the <acronym>GNU</acronym> General Public License for most of our
+ software; it applies also to any other work released this way by its
+ authors. You can apply it to your programs, too.
+ </para>
+ <para>
+ When we speak of free software, we are referring to freedom, not price. Our
+ General Public Licenses are designed to make sure that you have the freedom
+ to distribute copies of free software (and charge for them if you wish),
+ that you receive source code or can get it if you want it, that you can
+ change the software or use pieces of it in new free programs, and that you
+ know you can do these things.
+ </para>
+ <para>
+ To protect your rights, we need to prevent others from denying you these
+ rights or asking you to surrender the rights. Therefore, you have certain
+ responsibilities if you distribute copies of the software, or if you modify
+ it: responsibilities to respect the freedom of others.
+ </para>
+ <para>
+ For example, if you distribute copies of such a program, whether gratis or
+ for a fee, you must pass on to the recipients the same freedoms that you
+ received. You must make sure that they, too, receive or can get the source
+ code. And you must show them these terms so they know their rights.
+ </para>
+ <para>
+ Developers that use the <acronym>GNU</acronym> <acronym>GPL</acronym>
+ protect your rights with two steps: (1) assert copyright on the software,
+ and (2) offer you this License giving you legal permission to copy,
+ distribute and/or modify it.
+ </para>
+ <para>
+ For the developers&rsquo; and authors&rsquo; protection, the
+ <acronym>GPL</acronym> clearly explains that there is no warranty for this
+ free software. For both users&rsquo; and authors&rsquo; sake, the
+ <acronym>GPL</acronym> requires that modified versions be marked as changed,
+ so that their problems will not be attributed erroneously to authors of
+ previous versions.
+ </para>
+ <para>
+ Some devices are designed to deny users access to install or run modified
+ versions of the software inside them, although the manufacturer can do so.
+ This is fundamentally incompatible with the aim of protecting users&rsquo;
+ freedom to change the software. The systematic pattern of such abuse occurs
+ in the area of products for individuals to use, which is precisely where it
+ is most unacceptable. Therefore, we have designed this version of the
+ <acronym>GPL</acronym> to prohibit the practice for those products. If such
+ problems arise substantially in other domains, we stand ready to extend this
+ provision to those domains in future versions of the <acronym>GPL</acronym>,
+ as needed to protect the freedom of users.
+ </para>
+ <para>
+ Finally, every program is threatened constantly by software patents. States
+ should not allow patents to restrict development and use of software on
+ general-purpose computers, but in those that do, we wish to avoid the
+ special danger that patents applied to a free program could make it
+ effectively proprietary. To prevent this, the <acronym>GPL</acronym>
+ assures that patents cannot be used to render the program non-free.
+ </para>
+ <para>
+ The precise terms and conditions for copying, distribution and modification
+ follow.
+ </para>
+ <bridgehead>
+ TERMS AND CONDITIONS
+ </bridgehead>
+ <bridgehead renderas="sect1">
+ 0. Definitions.
+ </bridgehead>
+ <para>
+ &ldquo;This License&rdquo; refers to version 3 of the <acronym>GNU</acronym>
+ General Public License.
+ </para>
+ <para>
+ &ldquo;Copyright&rdquo; also means copyright-like laws that apply to other
+ kinds of works, such as semiconductor masks.
+ </para>
+ <para>
+ &ldquo;The Program&rdquo; refers to any copyrightable work licensed under
+ this License. Each licensee is addressed as &ldquo;you&rdquo;.
+ &ldquo;Licensees&rdquo; and &ldquo;recipients&rdquo; may be individuals or
+ organizations.
+ </para>
+ <para>
+ To &ldquo;modify&rdquo; a work means to copy from or adapt all or part of
+ the work in a fashion requiring copyright permission, other than the making
+ of an exact copy. The resulting work is called a &ldquo;modified
+ version&rdquo; of the earlier work or a work &ldquo;based on&rdquo; the
+ earlier work.
+ </para>
+ <para>
+ A &ldquo;covered work&rdquo; means either the unmodified Program or a work
+ based on the Program.
+ </para>
+ <para>
+ To &ldquo;propagate&rdquo; a work means to do anything with it that, without
+ permission, would make you directly or secondarily liable for infringement
+ under applicable copyright law, except executing it on a computer or
+ modifying a private copy. Propagation includes copying, distribution (with
+ or without modification), making available to the public, and in some
+ countries other activities as well.
+ </para>
+ <para>
+ To &ldquo;convey&rdquo; a work means any kind of propagation that enables
+ other parties to make or receive copies. Mere interaction with a user
+ through a computer network, with no transfer of a copy, is not conveying.
+ </para>
+ <para>
+ An interactive user interface displays &ldquo;Appropriate Legal
+ Notices&rdquo; to the extent that it includes a convenient and prominently
+ visible feature that (1) displays an appropriate copyright notice, and (2)
+ tells the user that there is no warranty for the work (except to the extent
+ that warranties are provided), that licensees may convey the work under this
+ License, and how to view a copy of this License. If the interface presents
+ a list of user commands or options, such as a menu, a prominent item in the
+ list meets this criterion.
+ </para>
+ <bridgehead renderas="sect1">
+ 1. Source Code.
+ </bridgehead>
+ <para>
+ The &ldquo;source code&rdquo; for a work means the preferred form of the
+ work for making modifications to it. &ldquo;Object code&rdquo; means any
+ non-source form of a work.
+ </para>
+ <para>
+ A &ldquo;Standard Interface&rdquo; means an interface that either is an
+ official standard defined by a recognized standards body, or, in the case of
+ interfaces specified for a particular programming language, one that is
+ widely used among developers working in that language.
+ </para>
+ <para>
+ The &ldquo;System Libraries&rdquo; of an executable work include anything,
+ other than the work as a whole, that (a) is included in the normal form of
+ packaging a Major Component, but which is not part of that Major Component,
+ and (b) serves only to enable use of the work with that Major Component, or
+ to implement a Standard Interface for which an implementation is available
+ to the public in source code form. A &ldquo;Major Component&rdquo;, in this
+ context, means a major essential component (kernel, window system, and so
+ on) of the specific operating system (if any) on which the executable work
+ runs, or a compiler used to produce the work, or an object code interpreter
+ used to run it.
+ </para>
+ <para>
+ The &ldquo;Corresponding Source&rdquo; for a work in object code form means
+ all the source code needed to generate, install, and (for an executable
+ work) run the object code and to modify the work, including scripts to
+ control those activities. However, it does not include the work&rsquo;s
+ System Libraries, or general-purpose tools or generally available free
+ programs which are used unmodified in performing those activities but which
+ are not part of the work. For example, Corresponding Source includes
+ interface definition files associated with source files for the work, and
+ the source code for shared libraries and dynamically linked subprograms that
+ the work is specifically designed to require, such as by intimate data
+ communication or control flow between those subprograms and other parts of
+ the work.
+ </para>
+ <para>
+ The Corresponding Source need not include anything that users can regenerate
+ automatically from other parts of the Corresponding Source.
+ </para>
+ <para>
+ The Corresponding Source for a work in source code form is that same work.
+ </para>
+ <bridgehead renderas="sect1">
+ 2. Basic Permissions.
+ </bridgehead>
+ <para>
+ All rights granted under this License are granted for the term of copyright
+ on the Program, and are irrevocable provided the stated conditions are met.
+ This License explicitly affirms your unlimited permission to run the
+ unmodified Program. The output from running a covered work is covered by
+ this License only if the output, given its content, constitutes a covered
+ work. This License acknowledges your rights of fair use or other
+ equivalent, as provided by copyright law.
+ </para>
+ <para>
+ You may make, run and propagate covered works that you do not convey,
+ without conditions so long as your license otherwise remains in force. You
+ may convey covered works to others for the sole purpose of having them make
+ modifications exclusively for you, or provide you with facilities for
+ running those works, provided that you comply with the terms of this License
+ in conveying all material for which you do not control copyright. Those
+ thus making or running the covered works for you must do so exclusively on
+ your behalf, under your direction and control, on terms that prohibit them
+ from making any copies of your copyrighted material outside their
+ relationship with you.
+ </para>
+ <para>
+ Conveying under any other circumstances is permitted solely under the
+ conditions stated below. Sublicensing is not allowed; section 10 makes it
+ unnecessary.
+ </para>
+ <bridgehead renderas="sect1">
+ 3. Protecting Users&rsquo; Legal Rights From Anti-Circumvention Law.
+ </bridgehead>
+ <para>
+ No covered work shall be deemed part of an effective technological measure
+ under any applicable law fulfilling obligations under article 11 of the WIPO
+ copyright treaty adopted on 20 December 1996, or similar laws prohibiting or
+ restricting circumvention of such measures.
+ </para>
+ <para>
+ When you convey a covered work, you waive any legal power to forbid
+ circumvention of technological measures to the extent such circumvention is
+ effected by exercising rights under this License with respect to the covered
+ work, and you disclaim any intention to limit operation or modification of
+ the work as a means of enforcing, against the work&rsquo;s users, your or
+ third parties&rsquo; legal rights to forbid circumvention of technological
+ measures.
+ </para>
+ <bridgehead renderas="sect1">
+ 4. Conveying Verbatim Copies.
+ </bridgehead>
+ <para>
+ You may convey verbatim copies of the Program&rsquo;s source code as you
+ receive it, in any medium, provided that you conspicuously and appropriately
+ publish on each copy an appropriate copyright notice; keep intact all
+ notices stating that this License and any non-permissive terms added in
+ accord with section 7 apply to the code; keep intact all notices of the
+ absence of any warranty; and give all recipients a copy of this License
+ along with the Program.
+ </para>
+ <para>
+ You may charge any price or no price for each copy that you convey, and you
+ may offer support or warranty protection for a fee.
+ </para>
+ <bridgehead renderas="sect1">
+ 5. Conveying Modified Source Versions.
+ </bridgehead>
+ <para>
+ You may convey a work based on the Program, or the modifications to produce
+ it from the Program, in the form of source code under the terms of section
+ 4, provided that you also meet all of these conditions:
+ </para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>
+ The work must carry prominent notices stating that you modified it, and
+ giving a relevant date.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The work must carry prominent notices stating that it is released under
+ this License and any conditions added under section 7. This requirement
+ modifies the requirement in section 4 to &ldquo;keep intact all
+ notices&rdquo;.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You must license the entire work, as a whole, under this License to
+ anyone who comes into possession of a copy. This License will therefore
+ apply, along with any applicable section 7 additional terms, to the
+ whole of the work, and all its parts, regardless of how they are
+ packaged. This License gives no permission to license the work in any
+ other way, but it does not invalidate such permission if you have
+ separately received it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the work has interactive user interfaces, each must display
+ Appropriate Legal Notices; however, if the Program has interactive
+ interfaces that do not display Appropriate Legal Notices, your work need
+ not make them do so.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ A compilation of a covered work with other separate and independent works,
+ which are not by their nature extensions of the covered work, and which are
+ not combined with it such as to form a larger program, in or on a volume of
+ a storage or distribution medium, is called an &ldquo;aggregate&rdquo; if
+ the compilation and its resulting copyright are not used to limit the access
+ or legal rights of the compilation&rsquo;s users beyond what the individual works
+ permit. Inclusion of a covered work in an aggregate does not cause
+ this License to apply to the other parts of the aggregate.
+ </para>
+ <bridgehead renderas="sect1">
+ 6. Conveying Non-Source Forms.
+ </bridgehead>
+ <para>
+ You may convey a covered work in object code form under the terms of
+ sections 4 and 5, provided that you also convey the machine-readable
+ Corresponding Source under the terms of this License, in one of these ways:
+ </para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>
+ Convey the object code in, or embodied in, a physical product (including
+ a physical distribution medium), accompanied by the Corresponding Source
+ fixed on a durable physical medium customarily used for software
+ interchange.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Convey the object code in, or embodied in, a physical product (including
+ a physical distribution medium), accompanied by a written offer, valid
+ for at least three years and valid for as long as you offer spare parts
+ or customer support for that product model, to give anyone who possesses
+ the object code either (1) a copy of the Corresponding Source for all
+ the software in the product that is covered by this License, on a
+ durable physical medium customarily used for software interchange, for a
+ price no more than your reasonable cost of physically performing this
+ conveying of source, or (2) access to copy the Corresponding Source from
+ a network server at no charge.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Convey individual copies of the object code with a copy of the written
+ offer to provide the Corresponding Source. This alternative is allowed
+ only occasionally and noncommercially, and only if you received the
+ object code with such an offer, in accord with subsection 6b.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Convey the object code by offering access from a designated place
+ (gratis or for a charge), and offer equivalent access to the
+ Corresponding Source in the same way through the same place at no
+ further charge. You need not require recipients to copy the
+ Corresponding Source along with the object code. If the place to copy
+ the object code is a network server, the Corresponding Source may be on
+ a different server (operated by you or a third party) that supports
+ equivalent copying facilities, provided you maintain clear directions
+ next to the object code saying where to find the Corresponding Source.
+ Regardless of what server hosts the Corresponding Source, you remain
+ obligated to ensure that it is available for as long as needed to
+ satisfy these requirements.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Convey the object code using peer-to-peer transmission, provided you
+ inform other peers where the object code and Corresponding Source of the
+ work are being offered to the general public at no charge under
+ subsection 6d.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ A separable portion of the object code, whose source code is excluded from
+ the Corresponding Source as a System Library, need not be included in
+ conveying the object code work.
+ </para>
+ <para>
+ A &ldquo;User Product&rdquo; is either (1) a &ldquo;consumer product&rdquo;,
+ which means any tangible personal property which is normally used for
+ personal, family, or household purposes, or (2) anything designed or sold
+ for incorporation into a dwelling. In determining whether a product is a
+ consumer product, doubtful cases shall be resolved in favor of coverage.
+ For a particular product received by a particular user, &ldquo;normally
+ used&rdquo; refers to a typical or common use of that class of product,
+ regardless of the status of the particular user or of the way in which the
+ particular user actually uses, or expects or is expected to use, the
+ product. A product is a consumer product regardless of whether the product
+ has substantial commercial, industrial or non-consumer uses, unless such
+ uses represent the only significant mode of use of the product.
+ </para>
+ <para>
+ &ldquo;Installation Information&rdquo; for a User Product means any methods,
+ procedures, authorization keys, or other information required to install and
+ execute modified versions of a covered work in that User Product from a
+ modified version of its Corresponding Source. The information must suffice
+ to ensure that the continued functioning of the modified object code is in
+ no case prevented or interfered with solely because modification has been
+ made.
+ </para>
+ <para>
+ If you convey an object code work under this section in, or with, or
+ specifically for use in, a User Product, and the conveying occurs as part of
+ a transaction in which the right of possession and use of the User Product
+ is transferred to the recipient in perpetuity or for a fixed term
+ (regardless of how the transaction is characterized), the Corresponding
+ Source conveyed under this section must be accompanied by the Installation
+ Information. But this requirement does not apply if neither you nor any
+ third party retains the ability to install modified object code on the User
+ Product (for example, the work has been installed in
+ <acronym>ROM</acronym>).
+ </para>
+ <para>
+ The requirement to provide Installation Information does not include a
+ requirement to continue to provide support service, warranty, or updates for
+ a work that has been modified or installed by the recipient, or for the User
+ Product in which it has been modified or installed. Access to a network may
+ be denied when the modification itself materially and adversely affects the
+ operation of the network or violates the rules and protocols for
+ communication across the network.
+ </para>
+ <para>
+ Corresponding Source conveyed, and Installation Information provided, in
+ accord with this section must be in a format that is publicly documented
+ (and with an implementation available to the public in source code form),
+ and must require no special password or key for unpacking, reading or
+ copying.
+ </para>
+ <bridgehead renderas="sect1">
+ 7. Additional Terms.
+ </bridgehead>
+ <para>
+ &ldquo;Additional permissions&rdquo; are terms that supplement the terms of
+ this License by making exceptions from one or more of its conditions.
+ Additional permissions that are applicable to the entire Program shall be
+ treated as though they were included in this License, to the extent that
+ they are valid under applicable law. If additional permissions apply only
+ to part of the Program, that part may be used separately under those
+ permissions, but the entire Program remains governed by this License
+ without regard to the additional permissions.
+ </para>
+ <para>
+ When you convey a copy of a covered work, you may at your option remove any
+ additional permissions from that copy, or from any part of it. (Additional
+ permissions may be written to require their own removal in certain cases
+ when you modify the work.) You may place additional permissions on
+ material, added by you to a covered work, for which you have or can give
+ appropriate copyright permission.
+ </para>
+ <para>
+ Notwithstanding any other provision of this License, for material you add
+ to a covered work, you may (if authorized by the copyright holders of that
+ material) supplement the terms of this License with terms:
+ </para>
+ <orderedlist numeration="loweralpha">
+ <listitem>
+ <para>
+ Disclaiming warranty or limiting liability differently from the terms
+ of sections 15 and 16 of this License; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Requiring preservation of specified reasonable legal notices or author
+ attributions in that material or in the Appropriate Legal Notices
+ displayed by works containing it; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Prohibiting misrepresentation of the origin of that material, or
+ requiring that modified versions of such material be marked in
+ reasonable ways as different from the original version; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Limiting the use for publicity purposes of names of licensors or
+ authors of the material; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Declining to grant rights under trademark law for use of some trade
+ names, trademarks, or service marks; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Requiring indemnification of licensors and authors of that material by
+ anyone who conveys the material (or modified versions of it) with
+ contractual assumptions of liability to the recipient, for any
+ liability that these contractual assumptions directly impose on those
+ licensors and authors.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ All other non-permissive additional terms are considered &ldquo;further
+ restrictions&rdquo; within the meaning of section 10. If the Program as
+ you received it, or any part of it, contains a notice stating that it is
+ governed by this License along with a term that is a further restriction,
+ you may remove that term. If a license document contains a further
+ restriction but permits relicensing or conveying under this License, you
+ may add to a covered work material governed by the terms of that license
+ document, provided that the further restriction does not survive such
+ relicensing or conveying.
+ </para>
+ <para>
+ If you add terms to a covered work in accord with this section, you must
+ place, in the relevant source files, a statement of the additional terms
+ that apply to those files, or a notice indicating where to find the
+ applicable terms.
+ </para>
+ <para>
+ Additional terms, permissive or non-permissive, may be stated in the form
+ of a separately written license, or stated as exceptions; the above
+ requirements apply either way.
+ </para>
+ <bridgehead renderas="sect1">
+ 8. Termination.
+ </bridgehead>
+ <para>
+ You may not propagate or modify a covered work except as expressly provided
+ under this License. Any attempt otherwise to propagate or modify it is
+ void, and will automatically terminate your rights under this License
+ (including any patent licenses granted under the third paragraph of section
+ 11).
+ </para>
+ <para>
+ However, if you cease all violation of this License, then your license from
+ a particular copyright holder is reinstated (a) provisionally, unless and
+ until the copyright holder explicitly and finally terminates your license,
+ and (b) permanently, if the copyright holder fails to notify you of the
+ violation by some reasonable means prior to 60 days after the cessation.
+ </para>
+ <para>
+ Moreover, your license from a particular copyright holder is reinstated
+ permanently if the copyright holder notifies you of the violation by some
+ reasonable means, this is the first time you have received notice of
+ violation of this License (for any work) from that copyright holder, and
+ you cure the violation prior to 30 days after your receipt of the notice.
+ </para>
+ <para>
+ Termination of your rights under this section does not terminate the
+ licenses of parties who have received copies or rights from you under this
+ License. If your rights have been terminated and not permanently
+ reinstated, you do not qualify to receive new licenses for the same
+ material under section 10.
+ </para>
+ <bridgehead renderas="sect1">
+ 9. Acceptance Not Required for Having Copies.
+ </bridgehead>
+ <para>
+ You are not required to accept this License in order to receive or run a
+ copy of the Program. Ancillary propagation of a covered work occurring
+ solely as a consequence of using peer-to-peer transmission to receive a
+ copy likewise does not require acceptance. However, nothing other than
+ this License grants you permission to propagate or modify any covered work.
+ These actions infringe copyright if you do not accept this License.
+ Therefore, by modifying or propagating a covered work, you indicate your
+ acceptance of this License to do so.
+ </para>
+ <bridgehead renderas="sect1">
+ 10. Automatic Licensing of Downstream Recipients.
+ </bridgehead>
+ <para>
+ Each time you convey a covered work, the recipient automatically receives a
+ license from the original licensors, to run, modify and propagate that
+ work, subject to this License. You are not responsible for enforcing
+ compliance by third parties with this License.
+ </para>
+ <para>
+ An &ldquo;entity transaction&rdquo; is a transaction transferring control
+ of an organization, or substantially all assets of one, or subdividing an
+ organization, or merging organizations. If propagation of a covered work
+ results from an entity transaction, each party to that transaction who
+ receives a copy of the work also receives whatever licenses to the work the
+ party&rsquo;s predecessor in interest had or could give under the previous
+ paragraph, plus a right to possession of the Corresponding Source of the
+ work from the predecessor in interest, if the predecessor has it or can get
+ it with reasonable efforts.
+ </para>
+ <para>
+ You may not impose any further restrictions on the exercise of the rights
+ granted or affirmed under this License. For example, you may not impose a
+ license fee, royalty, or other charge for exercise of rights granted under
+ this License, and you may not initiate litigation (including a cross-claim
+ or counterclaim in a lawsuit) alleging that any patent claim is infringed
+ by making, using, selling, offering for sale, or importing the Program or
+ any portion of it.
+ </para>
+ <bridgehead renderas="sect1">
+ 11. Patents.
+ </bridgehead>
+ <para>
+ A &ldquo;contributor&rdquo; is a copyright holder who authorizes use under
+ this License of the Program or a work on which the Program is based. The
+ work thus licensed is called the contributor&rsquo;s &ldquo;contributor
+ version&rdquo;.
+ </para>
+ <para>
+ A contributor&rsquo;s &ldquo;essential patent claims&rdquo; are all patent
+ claims owned or controlled by the contributor, whether already acquired or
+ hereafter acquired, that would be infringed by some manner, permitted by
+ this License, of making, using, or selling its contributor version, but do
+ not include claims that would be infringed only as a consequence of further
+ modification of the contributor version. For purposes of this definition,
+ &ldquo;control&rdquo; includes the right to grant patent sublicenses in a
+ manner consistent with the requirements of this License.
+ </para>
+ <para>
+ Each contributor grants you a non-exclusive, worldwide, royalty-free patent
+ license under the contributor&rsquo;s essential patent claims, to make, use,
+ sell, offer for sale, import and otherwise run, modify and propagate the
+ contents of its contributor version.
+ </para>
+ <para>
+ In the following three paragraphs, a &ldquo;patent license&rdquo; is any
+ express agreement or commitment, however denominated, not to enforce a
+ patent (such as an express permission to practice a patent or covenant not
+ to sue for patent infringement). To &ldquo;grant&rdquo; such a patent
+ license to a party means to make such an agreement or commitment not to
+ enforce a patent against the party.
+ </para>
+ <para>
+ If you convey a covered work, knowingly relying on a patent license, and the
+ Corresponding Source of the work is not available for anyone to copy, free
+ of charge and under the terms of this License, through a publicly available
+ network server or other readily accessible means, then you must either (1)
+ cause the Corresponding Source to be so available, or (2) arrange to deprive
+ yourself of the benefit of the patent license for this particular work, or
+ (3) arrange, in a manner consistent with the requirements of this License,
+ to extend the patent license to downstream recipients. &ldquo;Knowingly
+ relying&rdquo; means you have actual knowledge that, but for the patent
+ license, your conveying the covered work in a country, or your
+ recipient&rsquo;s use of the covered work in a country, would infringe one
+ or more identifiable patents in that country that you have reason to believe
+ are valid.
+ </para>
+ <para>
+ If, pursuant to or in connection with a single transaction or arrangement,
+ you convey, or propagate by procuring conveyance of, a covered work, and
+ grant a patent license to some of the parties receiving the covered work
+ authorizing them to use, propagate, modify or convey a specific copy of the
+ covered work, then the patent license you grant is automatically extended to
+ all recipients of the covered work and works based on it.
+ </para>
+ <para>
+ A patent license is &ldquo;discriminatory&rdquo; if it does not include
+ within the scope of its coverage, prohibits the exercise of, or is
+ conditioned on the non-exercise of one or more of the rights that are
+ specifically granted under this License. You may not convey a covered work
+ if you are a party to an arrangement with a third party that is in the
+ business of distributing software, under which you make payment to the third
+ party based on the extent of your activity of conveying the work, and under
+ which the third party grants, to any of the parties who would receive the
+ covered work from you, a discriminatory patent license (a) in connection
+ with copies of the covered work conveyed by you (or copies made from those
+ copies), or (b) primarily for and in connection with specific products or
+ compilations that contain the covered work, unless you entered into that
+ arrangement, or that patent license was granted, prior to 28 March 2007.
+ </para>
+ <para>
+ Nothing in this License shall be construed as excluding or limiting any
+ implied license or other defenses to infringement that may otherwise be
+ available to you under applicable patent law.
+ </para>
+ <bridgehead renderas="sect1">
+ 12. No Surrender of Others&rsquo; Freedom.
+ </bridgehead>
+ <para>
+ If conditions are imposed on you (whether by court order, agreement or
+ otherwise) that contradict the conditions of this License, they do not
+ excuse you from the conditions of this License. If you cannot convey a
+ covered work so as to satisfy simultaneously your obligations under this
+ License and any other pertinent obligations, then as a consequence you may
+ not convey it at all. For example, if you agree to terms that obligate you
+ to collect a royalty for further conveying from those to whom you convey the
+ Program, the only way you could satisfy both those terms and this License
+ would be to refrain entirely from conveying the Program.
+ </para>
+ <bridgehead renderas="sect1">
+ 13. Use with the <acronym>GNU</acronym> Affero General Public License.
+ </bridgehead>
+ <para>
+ Notwithstanding any other provision of this License, you have permission to
+ link or combine any covered work with a work licensed under version 3 of the
+ <acronym>GNU</acronym> Affero General Public License into a single combined
+ work, and to convey the resulting work. The terms of this License will
+ continue to apply to the part which is the covered work, but the special
+ requirements of the <acronym>GNU</acronym> Affero General Public License,
+ section 13, concerning interaction through a network will apply to the
+ combination as such.
+ </para>
+ <bridgehead renderas="sect1">
+ 14. Revised Versions of this License.
+ </bridgehead>
+ <para>
+ The Free Software Foundation may publish revised and/or new versions of the
+ <acronym>GNU</acronym> General Public License from time to time. Such new
+ versions will be similar in spirit to the present version, but may differ in
+ detail to address new problems or concerns.
+ </para>
+ <para>
+ Each version is given a distinguishing version number. If the Program
+ specifies that a certain numbered version of the <acronym>GNU</acronym>
+ General Public License &ldquo;or any later version&rdquo; applies to it, you
+ have the option of following the terms and conditions either of that
+ numbered version or of any later version published by the Free Software
+ Foundation. If the Program does not specify a version number of the
+ <acronym>GNU</acronym> General Public License, you may choose any version
+ ever published by the Free Software Foundation.
+ </para>
+ <para>
+ If the Program specifies that a proxy can decide which future versions of
+ the <acronym>GNU</acronym> General Public License can be used, that
+ proxy&rsquo;s public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Program.
+ </para>
+ <para>
+ Later license versions may give you additional or different permissions.
+ However, no additional obligations are imposed on any author or copyright
+ holder as a result of your choosing to follow a later version.
+ </para>
+ <bridgehead renderas="sect1">
+ 15. Disclaimer of Warranty.
+ </bridgehead>
+ <para>
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+ LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+ OTHER PARTIES PROVIDE THE PROGRAM &ldquo;AS IS&rdquo; WITHOUT WARRANTY OF
+ ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+ THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+ YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+ NECESSARY SERVICING, REPAIR OR CORRECTION.
+ </para>
+ <bridgehead renderas="sect1">
+ 16. Limitation of Liability.
+ </bridgehead>
+ <para>
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
+ ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE
+ PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+ GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
+ OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA
+ OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+ PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+ EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGES.
+ </para>
+ <bridgehead renderas="sect1">
+ 17. Interpretation of Sections 15 and 16.
+ </bridgehead>
+ <para>
+ If the disclaimer of warranty and limitation of liability provided above
+ cannot be given local legal effect according to their terms, reviewing
+ courts shall apply local law that most closely approximates an absolute
+ waiver of all civil liability in connection with the Program, unless a
+ warranty or assumption of liability accompanies a copy of the Program in
+ return for a fee.
+ </para>
+ <bridgehead>
+ END OF TERMS AND CONDITIONS
+ </bridgehead>
+ <bridgehead renderas="sect1">
+ How to Apply These Terms to Your New Programs
+ </bridgehead>
+ <para>
+ If you develop a new program, and you want it to be of the greatest possible
+ use to the public, the best way to achieve this is to make it free software
+ which everyone can redistribute and change under these terms.
+ </para>
+ <para>
+ To do so, attach the following notices to the program. It is safest to
+ attach them to the start of each source file to most effectively state the
+ exclusion of warranty; and each file should have at least the
+ &ldquo;copyright&rdquo; line and a pointer to where the full notice is
+ found.
+ </para>
+ <screen>
+<replaceable>one line to give the program&rsquo;s name and a brief idea of what it does.</replaceable>
+Copyright (C) <replaceable>year</replaceable> <replaceable>name of author</replaceable>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the <acronym>GNU</acronym> General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+<acronym>GNU</acronym> General Public License for more details.
+
+You should have received a copy of the <acronym>GNU</acronym> General Public License
+along with this program. If not, see <ulink url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>.
+ </screen>
+ <para>
+ Also add information on how to contact you by electronic and paper mail.
+ </para>
+ <para>
+ If the program does terminal interaction, make it output a short notice like
+ this when it starts in an interactive mode:
+ </para>
+ <screen>
+<replaceable>program</replaceable> Copyright (C) <replaceable>year</replaceable> <replaceable>name of author</replaceable>
+This program comes with ABSOLUTELY NO WARRANTY; for details type &lsquo;<literal>show w</literal>&rsquo;.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type &lsquo;<literal>show c</literal>&rsquo; for details.
+ </screen>
+ <para>
+ The hypothetical commands &lsquo;<literal>show w</literal>&rsquo; and
+ &lsquo;<literal>show c</literal>&rsquo; should show the appropriate parts of
+ the General Public License. Of course, your program&rsquo;s commands might be
+ different; for a GUI interface, you would use an &ldquo;about box&rdquo;.
+ </para>
+ <para>
+ You should also get your employer (if you work as a programmer) or school,
+ if any, to sign a &ldquo;copyright disclaimer&rdquo; for the program, if
+ necessary. For more information on this, and how to apply and follow the
+ <acronym>GNU</acronym> <acronym>GPL</acronym>, see <ulink
+ url="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</ulink>.
+ </para>
+ <para>
+ The <acronym>GNU</acronym> General Public License does not permit
+ incorporating your program into proprietary programs. If your program is a
+ subroutine library, you may consider it more useful to permit linking
+ proprietary applications with the library. If this is what you want to do,
+ use the <acronym>GNU</acronym> Lesser General Public License instead of this
+ License. But first, please read <ulink
+ url="http://www.gnu.org/philosophy/why-not-lgpl.html">http://www.gnu.org/philosophy/why-not-lgpl.html</ulink>.
+ </para>
+</appendix>
diff --git a/docs-xml/Samba3-HOWTO/hitlist-content b/docs-xml/Samba3-HOWTO/hitlist-content
new file mode 100644
index 0000000000..66f3b1a603
--- /dev/null
+++ b/docs-xml/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-xml/Samba3-HOWTO/images/10small.png b/docs-xml/Samba3-HOWTO/images/10small.png
new file mode 100644
index 0000000000..56a9b0cd67
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/10small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/11small.png b/docs-xml/Samba3-HOWTO/images/11small.png
new file mode 100644
index 0000000000..18f5d9e4dd
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/11small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/12small.png b/docs-xml/Samba3-HOWTO/images/12small.png
new file mode 100644
index 0000000000..5bdf809c1b
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/12small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/13small.png b/docs-xml/Samba3-HOWTO/images/13small.png
new file mode 100644
index 0000000000..536b2fc2c2
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/13small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/14small.png b/docs-xml/Samba3-HOWTO/images/14small.png
new file mode 100644
index 0000000000..89054249c0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/14small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/1small.png b/docs-xml/Samba3-HOWTO/images/1small.png
new file mode 100644
index 0000000000..c4905163c9
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/1small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/2small.png b/docs-xml/Samba3-HOWTO/images/2small.png
new file mode 100644
index 0000000000..5fd9071349
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/2small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/3small.png b/docs-xml/Samba3-HOWTO/images/3small.png
new file mode 100644
index 0000000000..22a39bae52
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/3small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/4small.png b/docs-xml/Samba3-HOWTO/images/4small.png
new file mode 100644
index 0000000000..6b7f1b1fd4
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/4small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/5small.png b/docs-xml/Samba3-HOWTO/images/5small.png
new file mode 100644
index 0000000000..b23e1fc2c7
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/5small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/6small.png b/docs-xml/Samba3-HOWTO/images/6small.png
new file mode 100644
index 0000000000..35a646d826
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/6small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/7small.png b/docs-xml/Samba3-HOWTO/images/7small.png
new file mode 100644
index 0000000000..d182677510
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/7small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/8small.png b/docs-xml/Samba3-HOWTO/images/8small.png
new file mode 100644
index 0000000000..08aca66386
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/8small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/9small.png b/docs-xml/Samba3-HOWTO/images/9small.png
new file mode 100644
index 0000000000..90c2cde327
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/9small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME001.png b/docs-xml/Samba3-HOWTO/images/WME001.png
new file mode 100644
index 0000000000..c5db7570bc
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME001.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME002.png b/docs-xml/Samba3-HOWTO/images/WME002.png
new file mode 100644
index 0000000000..641f2179a0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME002.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME003.png b/docs-xml/Samba3-HOWTO/images/WME003.png
new file mode 100644
index 0000000000..073c58eddd
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME003.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME004.png b/docs-xml/Samba3-HOWTO/images/WME004.png
new file mode 100644
index 0000000000..5053adeeec
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME004.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME005.png b/docs-xml/Samba3-HOWTO/images/WME005.png
new file mode 100644
index 0000000000..5e4e72e498
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME005.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME006.png b/docs-xml/Samba3-HOWTO/images/WME006.png
new file mode 100644
index 0000000000..cbd3183696
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME006.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME007.png b/docs-xml/Samba3-HOWTO/images/WME007.png
new file mode 100644
index 0000000000..e0a113b080
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME007.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME008.png b/docs-xml/Samba3-HOWTO/images/WME008.png
new file mode 100644
index 0000000000..b03a7853b4
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME008.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME009.png b/docs-xml/Samba3-HOWTO/images/WME009.png
new file mode 100644
index 0000000000..f851876cee
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME009.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME010.png b/docs-xml/Samba3-HOWTO/images/WME010.png
new file mode 100644
index 0000000000..589be02b22
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME010.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME011.png b/docs-xml/Samba3-HOWTO/images/WME011.png
new file mode 100644
index 0000000000..f15399b4a2
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME011.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME012.png b/docs-xml/Samba3-HOWTO/images/WME012.png
new file mode 100644
index 0000000000..d2e46212f6
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME012.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME013.png b/docs-xml/Samba3-HOWTO/images/WME013.png
new file mode 100644
index 0000000000..0f0a70d062
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME013.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WME014.png b/docs-xml/Samba3-HOWTO/images/WME014.png
new file mode 100644
index 0000000000..73f1dde37c
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WME014.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WXPP002.png b/docs-xml/Samba3-HOWTO/images/WXPP002.png
new file mode 100644
index 0000000000..b87001bca4
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WXPP002.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WXPP003.png b/docs-xml/Samba3-HOWTO/images/WXPP003.png
new file mode 100644
index 0000000000..a60d6c413a
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WXPP003.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WXPP005.png b/docs-xml/Samba3-HOWTO/images/WXPP005.png
new file mode 100644
index 0000000000..4aa091767b
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WXPP005.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WXPP009.png b/docs-xml/Samba3-HOWTO/images/WXPP009.png
new file mode 100644
index 0000000000..b540e238b8
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WXPP009.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/WXPP014.png b/docs-xml/Samba3-HOWTO/images/WXPP014.png
new file mode 100644
index 0000000000..f1e02d3ce3
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/WXPP014.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/a_small.png b/docs-xml/Samba3-HOWTO/images/a_small.png
new file mode 100644
index 0000000000..a6622ef6cf
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/a_small.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/access1.svg b/docs-xml/Samba3-HOWTO/images/access1.svg
new file mode 100644
index 0000000000..486686f780
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/access1.svg
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="30.1cm"
+ height="13.348cm"
+ viewBox="1.35 1.15 31.45 14.498"
+ id="svg2">
+ <defs
+ id="defs99" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="1.4"
+ y="1.2"
+ id="rect4"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="1.4"
+ y="1.2"
+ id="rect6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3"
+ y="2"
+ id="text8"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">type</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="6.5"
+ y="1.2"
+ id="rect10"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="6.5"
+ y="1.2"
+ id="rect12"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="7.8000002"
+ y="2"
+ id="text14"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">users</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="11.5"
+ y="1.2"
+ id="rect16"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="11.5"
+ y="1.2"
+ id="rect18"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="12.6"
+ y="2"
+ id="text20"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">group</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="16.5"
+ y="1.2"
+ id="rect22"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="16.5"
+ y="1.2"
+ id="rect24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="17.700001"
+ y="2"
+ id="text26"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">others</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="1.4"
+ y="2.7"
+ id="rect28"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="1.4"
+ y="2.7"
+ id="rect30"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.2"
+ y="3.5"
+ id="text32"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">d l</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="6.5"
+ y="2.7"
+ id="rect34"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="6.5"
+ y="2.7"
+ id="rect36"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="7.9000001"
+ y="3.5"
+ id="text38"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">r w x</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="11.5"
+ y="2.7"
+ id="rect40"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="11.5"
+ y="2.7"
+ id="rect42"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="13"
+ y="3.5"
+ id="text44"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">r w x</text>
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="16.5"
+ y="2.7"
+ id="rect46"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4000001"
+ height="1.1"
+ x="16.5"
+ y="2.7"
+ id="rect48"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="17.9"
+ y="3.5"
+ id="text50"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">r w x</text>
+ <text
+ x="22.700001"
+ y="6.0999999"
+ id="text52"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Execute, List files</text>
+ <text
+ x="22.700001"
+ y="6.9000001"
+ id="text54"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Write, Create files</text>
+ <text
+ x="22.700001"
+ y="7.6999998"
+ id="text56"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Read, Read files</text>
+ <text
+ x="22.700001"
+ y="8.5"
+ id="text58"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Execute, List files</text>
+ <text
+ x="22.700001"
+ y="9.3000002"
+ id="text60"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Write, Create files</text>
+ <text
+ x="22.700001"
+ y="10.1"
+ id="text62"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Read, Read files</text>
+ <text
+ x="22.700001"
+ y="10.9"
+ id="text64"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Execute, List files</text>
+ <text
+ x="22.700001"
+ y="11.7"
+ id="text66"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Write, Create files</text>
+ <text
+ x="22.700001"
+ y="12.5"
+ id="text68"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Can Read, Read files</text>
+ <text
+ x="22.700001"
+ y="13.3"
+ id="text70"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Is a symbolic link</text>
+ <text
+ x="22.700001"
+ y="14.1"
+ id="text72"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:monospace">Is a directory</text>
+ <line
+ x1="18.700001"
+ y1="3.8"
+ x2="18.700001"
+ y2="6.6999998"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line74"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="18.700001"
+ y1="6.6999998"
+ x2="22.1"
+ y2="6.6999998"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line76"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="18.000,3.800 18.000,3.800 18.000,7.500 22.100,7.500 "
+ id="polyline78"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="14.400,3.700 14.400,3.700 14.400,8.300 22.100,8.300 "
+ id="polyline80"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="13.700,3.800 13.700,3.800 13.700,9.100 22.100,9.100 "
+ id="polyline82"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="13.100,3.800 13.000,3.800 13.000,9.900 22.100,9.900 "
+ id="polyline84"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="9.200,3.800 9.300,3.800 9.300,10.700 22.100,10.700 "
+ id="polyline86"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="8.700,3.800 8.800,3.800 8.800,11.500 22.100,11.500 "
+ id="polyline88"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="8.000,3.800 8.100,3.800 8.100,12.300 22.100,12.300 "
+ id="polyline90"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="3.900,3.800 3.900,3.800 3.900,13.100 22.100,13.100 "
+ id="polyline92"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="3.300,3.800 3.300,3.800 3.300,13.900 22.100,13.900 "
+ id="polyline94"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="19.200,3.800 19.200,3.800 19.200,5.900 22.100,5.900 "
+ id="polyline96"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/browsing1.svg b/docs-xml/Samba3-HOWTO/images/browsing1.svg
new file mode 100644
index 0000000000..181ea21871
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/browsing1.svg
@@ -0,0 +1,2025 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="29.107cm"
+ height="18.84cm"
+ viewBox="-2.808 0.758 26.299 19.598"
+ id="svg2">
+ <defs
+ id="defs689" />
+ <rect
+ width="1.534"
+ height="3.5799999"
+ x="2.007"
+ y="2.0139999"
+ id="rect4"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.534"
+ height="3.5799999"
+ x="2.007"
+ y="2.0139999"
+ id="rect6"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.227"
+ height="0.40900001"
+ x="2.1600001"
+ y="2.2279999"
+ id="rect8"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.227"
+ height="0.40900001"
+ x="2.1600001"
+ y="2.638"
+ id="rect10"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.227"
+ height="0.40900001"
+ x="2.1600001"
+ y="3.0469999"
+ id="rect12"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.227"
+ height="0.40900001"
+ x="2.1600001"
+ y="3.4560001"
+ id="rect14"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.245"
+ x="2.1600001"
+ y="3.947"
+ id="rect16"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="3.3110001"
+ cy="3.9879999"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse18"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="3.3110001"
+ cy="3.9879999"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse20"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="3.3110001"
+ cy="4.151"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse22"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="3.3110001"
+ cy="4.151"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse24"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="3.0039999"
+ y="4.0279999"
+ id="rect26"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="3.0039999"
+ y="4.0279999"
+ id="rect28"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 2.263,4.519 L 2.263,5.414"
+ id="path30"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 2.518,4.519 L 2.518,5.414"
+ id="path32"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 2.774,4.519 L 2.774,5.414"
+ id="path34"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 3.03,4.519 L 3.03,5.414"
+ id="path36"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 3.285,4.519 L 3.285,5.414"
+ id="path38"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 3.541,4.519 L 3.541,5.414"
+ id="path40"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="1.7,5.9 2.007,5.286 2.007,5.593 3.541,5.593 3.541,5.286 3.95,5.9 1.7,5.9 "
+ id="polygon42"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="1.7,5.9 2.007,5.286 2.007,5.593 3.541,5.593 3.541,5.286 3.95,5.9 1.7,5.9 "
+ id="polygon44"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.595"
+ height="3.7219999"
+ x="6.119"
+ y="2"
+ id="rect46"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.595"
+ height="3.7219999"
+ x="6.119"
+ y="2"
+ id="rect48"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.276"
+ height="0.42500001"
+ x="6.2789998"
+ y="2.223"
+ id="rect50"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.276"
+ height="0.42500001"
+ x="6.2789998"
+ y="2.6489999"
+ id="rect52"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.276"
+ height="0.42500001"
+ x="6.2789998"
+ y="3.0739999"
+ id="rect54"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.276"
+ height="0.42500001"
+ x="6.2789998"
+ y="3.4990001"
+ id="rect56"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.79799998"
+ height="0.255"
+ x="6.2789998"
+ y="4.0100002"
+ id="rect58"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="7.4749999"
+ cy="4.052"
+ rx="0.056000002"
+ ry="0.056000002"
+ id="ellipse60"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="7.4749999"
+ cy="4.052"
+ rx="0.056000002"
+ ry="0.056000002"
+ id="ellipse62"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="7.4749999"
+ cy="4.223"
+ rx="0.056000002"
+ ry="0.056000002"
+ id="ellipse64"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="7.4749999"
+ cy="4.223"
+ rx="0.056000002"
+ ry="0.056000002"
+ id="ellipse66"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.191"
+ height="0.17"
+ x="7.1560001"
+ y="4.0949998"
+ id="rect68"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.191"
+ height="0.17"
+ x="7.1560001"
+ y="4.0949998"
+ id="rect70"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 6.385,4.605 L 6.385,5.536"
+ id="path72"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 6.651,4.605 L 6.651,5.536"
+ id="path74"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 6.917,4.605 L 6.917,5.536"
+ id="path76"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 7.182,4.605 L 7.182,5.536"
+ id="path78"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 7.448,4.605 L 7.448,5.536"
+ id="path80"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 7.714,4.605 L 7.714,5.536"
+ id="path82"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="5.8,6.041 6.119,5.403 6.119,5.722 7.714,5.722 7.714,5.403 8.139,6.041 5.8,6.041 "
+ id="polygon84"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="5.8,6.041 6.119,5.403 6.119,5.722 7.714,5.722 7.714,5.403 8.139,6.041 5.8,6.041 "
+ id="polygon86"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.618"
+ height="3.776"
+ x="10.124"
+ y="1.9"
+ id="rect88"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.618"
+ height="3.776"
+ x="10.124"
+ y="1.9"
+ id="rect90"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.295"
+ height="0.43200001"
+ x="10.286"
+ y="2.1270001"
+ id="rect92"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.295"
+ height="0.43200001"
+ x="10.286"
+ y="2.5580001"
+ id="rect94"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.295"
+ height="0.43200001"
+ x="10.286"
+ y="2.99"
+ id="rect96"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.295"
+ height="0.43200001"
+ x="10.286"
+ y="3.421"
+ id="rect98"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.80900002"
+ height="0.259"
+ x="10.286"
+ y="3.9389999"
+ id="rect100"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="11.499"
+ cy="3.9820001"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse102"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="11.499"
+ cy="3.9820001"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse104"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="11.499"
+ cy="4.1550002"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse106"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="11.499"
+ cy="4.1550002"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse108"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.19400001"
+ height="0.17299999"
+ x="11.176"
+ y="4.026"
+ id="rect110"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.19400001"
+ height="0.17299999"
+ x="11.176"
+ y="4.026"
+ id="rect112"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 10.393,4.543 L 10.393,5.487"
+ id="path114"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 10.663,4.543 L 10.663,5.487"
+ id="path116"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 10.933,4.543 L 10.933,5.487"
+ id="path118"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 11.203,4.543 L 11.203,5.487"
+ id="path120"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 11.472,4.543 L 11.472,5.487"
+ id="path122"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 11.742,4.543 L 11.742,5.487"
+ id="path124"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="9.8,6 10.124,5.353 10.124,5.676 11.742,5.676 11.742,5.353 12.174,6 9.8,6 "
+ id="polygon126"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="9.8,6 10.124,5.353 10.124,5.676 11.742,5.676 11.742,5.353 12.174,6 9.8,6 "
+ id="polygon128"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="2.2"
+ y="1.4"
+ id="text130"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N1_A</text>
+ <text
+ x="6.1999998"
+ y="1.4"
+ id="text132"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N1_B</text>
+ <text
+ x="10.1"
+ y="1.3"
+ id="text134"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N1_C (DMB)</text>
+ <rect
+ width="1.631"
+ height="3.806"
+ x="14.726"
+ y="1.8"
+ id="rect136"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.631"
+ height="3.806"
+ x="14.726"
+ y="1.8"
+ id="rect138"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.3049999"
+ height="0.435"
+ x="14.889"
+ y="2.0280001"
+ id="rect140"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.3049999"
+ height="0.435"
+ x="14.889"
+ y="2.4630001"
+ id="rect142"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.3049999"
+ height="0.435"
+ x="14.889"
+ y="2.898"
+ id="rect144"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.3049999"
+ height="0.435"
+ x="14.889"
+ y="3.3329999"
+ id="rect146"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.815"
+ height="0.26100001"
+ x="14.889"
+ y="3.855"
+ id="rect148"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="16.113001"
+ cy="3.8989999"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse150"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="16.113001"
+ cy="3.8989999"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse152"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="16.113001"
+ cy="4.073"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse154"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="16.113001"
+ cy="4.073"
+ rx="0.057"
+ ry="0.057"
+ id="ellipse156"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.19599999"
+ height="0.17399999"
+ x="15.786"
+ y="3.9419999"
+ id="rect158"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.19599999"
+ height="0.17399999"
+ x="15.786"
+ y="3.9419999"
+ id="rect160"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 14.998,4.464 L 14.998,5.415"
+ id="path162"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.27,4.464 L 15.27,5.415"
+ id="path164"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.542,4.464 L 15.542,5.415"
+ id="path166"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.814,4.464 L 15.814,5.415"
+ id="path168"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 16.085,4.464 L 16.085,5.415"
+ id="path170"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 16.357,4.464 L 16.357,5.415"
+ id="path172"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="14.4,5.932 14.726,5.279 14.726,5.606 16.357,5.606 16.357,5.279 16.792,5.932 14.4,5.932 "
+ id="polygon174"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="14.4,5.932 14.726,5.279 14.726,5.606 16.357,5.606 16.357,5.279 16.792,5.932 14.4,5.932 "
+ id="polygon176"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.9"
+ y1="7.0999999"
+ x2="2.5999999"
+ y2="7.0999999"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line178"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="2.825"
+ y1="5.9000001"
+ x2="2.8"
+ y2="7"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line180"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="6.9699998"
+ y1="6.0409999"
+ x2="6.9000001"
+ y2="7"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line182"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="10.987"
+ y1="6"
+ x2="11"
+ y2="7.0999999"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line184"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="15.596"
+ y1="5.9320002"
+ x2="15.6"
+ y2="7.0999999"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line186"
+ style="stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.645"
+ height="3.839"
+ x="18.929001"
+ y="1.85"
+ id="rect188"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.645"
+ height="3.839"
+ x="18.929001"
+ y="1.85"
+ id="rect190"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.316"
+ height="0.43900001"
+ x="19.094"
+ y="2.0799999"
+ id="rect192"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.316"
+ height="0.43900001"
+ x="19.094"
+ y="2.5190001"
+ id="rect194"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.316"
+ height="0.43900001"
+ x="19.094"
+ y="2.9579999"
+ id="rect196"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.316"
+ height="0.43900001"
+ x="19.094"
+ y="3.3970001"
+ id="rect198"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.82300001"
+ height="0.26300001"
+ x="19.094"
+ y="3.9230001"
+ id="rect200"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="20.327999"
+ cy="3.967"
+ rx="0.057999998"
+ ry="0.057999998"
+ id="ellipse202"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="20.327999"
+ cy="3.967"
+ rx="0.057999998"
+ ry="0.057999998"
+ id="ellipse204"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="20.327999"
+ cy="4.1420002"
+ rx="0.057999998"
+ ry="0.057999998"
+ id="ellipse206"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="20.327999"
+ cy="4.1420002"
+ rx="0.057999998"
+ ry="0.057999998"
+ id="ellipse208"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.197"
+ height="0.176"
+ x="19.999001"
+ y="4.0110002"
+ id="rect210"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.197"
+ height="0.176"
+ x="19.999001"
+ y="4.0110002"
+ id="rect212"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 19.203,4.537 L 19.203,5.497"
+ id="path214"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 19.478,4.537 L 19.478,5.497"
+ id="path216"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 19.752,4.537 L 19.752,5.497"
+ id="path218"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 20.026,4.537 L 20.026,5.497"
+ id="path220"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 20.3,4.537 L 20.3,5.497"
+ id="path222"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 20.574,4.537 L 20.574,5.497"
+ id="path224"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="18.6,6.018 18.929,5.36 18.929,5.689 20.574,5.689 20.574,5.36 21.013,6.018 18.6,6.018 "
+ id="polygon226"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="18.6,6.018 18.929,5.36 18.929,5.689 20.574,5.689 20.574,5.36 21.013,6.018 18.6,6.018 "
+ id="polygon228"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.799999"
+ y1="7.0999999"
+ x2="19.806999"
+ y2="6.0180001"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line230"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="14.6"
+ y="1.3"
+ id="text232"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N1_D</text>
+ <text
+ x="18.9"
+ y="1.3"
+ id="text234"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N1_E</text>
+ <line
+ x1="2.5999999"
+ y1="7"
+ x2="2.5999999"
+ y2="8.6000004"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line236"
+ style="stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.3499999"
+ height="2.3499999"
+ x="1.4"
+ y="8.6000004"
+ id="rect238"
+ style="fill:#9f9f9f;stroke:none;stroke-width:0" />
+ <rect
+ width="2.3499999"
+ height="2.3499999"
+ x="1.4"
+ y="8.6000004"
+ id="rect240"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.3499999"
+ height="2.3499999"
+ x="1.4"
+ y="8.6000004"
+ id="rect242"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <path
+ d="M 2.72,8.98 C 2.72,10.155 2.955,9.92 1.78,9.92"
+ id="path244"
+ style="fill:none;stroke:#ffffff;stroke-width:0.13" />
+ <path
+ d="M 2.72,8.98 C 2.72,10.155 2.955,9.92 1.78,9.92"
+ id="path246"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <polygon
+ points="2.833,9.164 2.716,8.929 2.599,9.164 2.833,9.164 "
+ id="polygon248"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="2.833,9.164 2.716,8.929 2.599,9.164 2.833,9.164 "
+ id="polygon250"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="1.964,9.798 1.729,9.916 1.964,10.034 1.964,9.798 "
+ id="polygon252"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="1.964,9.798 1.729,9.916 1.964,10.034 1.964,9.798 "
+ id="polygon254"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <path
+ d="M 3.418,9.641 C 2.243,9.641 2.478,9.406 2.478,10.581"
+ id="path256"
+ style="fill:none;stroke:#ffffff;stroke-width:0.13" />
+ <path
+ d="M 3.418,9.641 C 2.243,9.641 2.478,9.406 2.478,10.581"
+ id="path258"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <polygon
+ points="3.21,9.752 3.445,9.634 3.21,9.516 3.21,9.752 "
+ id="polygon260"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.21,9.752 3.445,9.634 3.21,9.516 3.21,9.752 "
+ id="polygon262"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="2.34,10.386 2.458,10.621 2.575,10.386 2.34,10.386 "
+ id="polygon264"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="2.34,10.386 2.458,10.621 2.575,10.386 2.34,10.386 "
+ id="polygon266"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="4.5"
+ y="10.1"
+ id="text268"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Router 1</text>
+ <text
+ x="9.8999996"
+ y="8.1000004"
+ id="text270"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Subnet 1</text>
+ <line
+ x1="19.9"
+ y1="7"
+ x2="19.9"
+ y2="8.6999998"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line272"
+ style="stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.4000001"
+ height="2.4000001"
+ x="18.700001"
+ y="8.6999998"
+ id="rect274"
+ style="fill:#9f9f9f;stroke:none;stroke-width:0" />
+ <rect
+ width="2.4000001"
+ height="2.4000001"
+ x="18.700001"
+ y="8.6999998"
+ id="rect276"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.4000001"
+ height="2.4000001"
+ x="18.700001"
+ y="8.6999998"
+ id="rect278"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <path
+ d="M 20.048,9.088 C 20.048,10.288 20.288,10.048 19.088,10.048"
+ id="path280"
+ style="fill:none;stroke:#ffffff;stroke-width:0.13" />
+ <path
+ d="M 20.048,9.088 C 20.048,10.288 20.288,10.048 19.088,10.048"
+ id="path282"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <polygon
+ points="20.164,9.276 20.044,9.036 19.924,9.276 20.164,9.276 "
+ id="polygon284"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="20.164,9.276 20.044,9.036 19.924,9.276 20.164,9.276 "
+ id="polygon286"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="19.276,9.924 19.036,10.044 19.276,10.164 19.276,9.924 "
+ id="polygon288"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="19.276,9.924 19.036,10.044 19.276,10.164 19.276,9.924 "
+ id="polygon290"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <path
+ d="M 20.761,9.764 C 19.561,9.764 19.801,9.524 19.801,10.724"
+ id="path292"
+ style="fill:none;stroke:#ffffff;stroke-width:0.13" />
+ <path
+ d="M 20.761,9.764 C 19.561,9.764 19.801,9.524 19.801,10.724"
+ id="path294"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <polygon
+ points="20.548,9.876 20.788,9.756 20.548,9.636 20.548,9.876 "
+ id="polygon296"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="20.548,9.876 20.788,9.756 20.548,9.636 20.548,9.876 "
+ id="polygon298"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="19.66,10.524 19.78,10.764 19.9,10.524 19.66,10.524 "
+ id="polygon300"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="19.66,10.524 19.78,10.764 19.9,10.524 19.66,10.524 "
+ id="polygon302"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="15.5"
+ y="10.1"
+ id="text304"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Router 2</text>
+ <line
+ x1="2.575"
+ y1="10.95"
+ x2="2.5999999"
+ y2="12.4"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line306"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="8"
+ y1="12.4"
+ x2="-1.7"
+ y2="12.4"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line308"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.4000001"
+ y="12"
+ id="text310"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Subnet 2</text>
+ <rect
+ width="1.493"
+ height="3.483"
+ x="7.099"
+ y="13.5"
+ id="rect312"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.493"
+ height="3.483"
+ x="7.099"
+ y="13.5"
+ id="rect314"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="7.2480001"
+ y="13.709"
+ id="rect316"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="7.2480001"
+ y="14.107"
+ id="rect318"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="7.2480001"
+ y="14.505"
+ id="rect320"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="7.2480001"
+ y="14.903"
+ id="rect322"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.74599999"
+ height="0.23899999"
+ x="7.2480001"
+ y="15.381"
+ id="rect324"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="8.3669996"
+ cy="15.421"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse326"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="8.3669996"
+ cy="15.421"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse328"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="8.3669996"
+ cy="15.58"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse330"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="8.3669996"
+ cy="15.58"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse332"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.17900001"
+ height="0.15899999"
+ x="8.0690002"
+ y="15.461"
+ id="rect334"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.17900001"
+ height="0.15899999"
+ x="8.0690002"
+ y="15.461"
+ id="rect336"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 7.347,15.938 L 7.347,16.809"
+ id="path338"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 7.596,15.938 L 7.596,16.809"
+ id="path340"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 7.845,15.938 L 7.845,16.809"
+ id="path342"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 8.094,15.938 L 8.094,16.809"
+ id="path344"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 8.343,15.938 L 8.343,16.809"
+ id="path346"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 8.591,15.938 L 8.591,16.809"
+ id="path348"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="6.8,17.282 7.099,16.685 7.099,16.983 8.591,16.983 8.591,16.685 8.989,17.282 6.8,17.282 "
+ id="polygon350"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="6.8,17.282 7.099,16.685 7.099,16.983 8.591,16.983 8.591,16.685 8.989,17.282 6.8,17.282 "
+ id="polygon352"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="7.895"
+ y1="13.5"
+ x2="7.9000001"
+ y2="12.3"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line354"
+ style="stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="3.707"
+ y="13.489"
+ id="rect356"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="3.707"
+ y="13.489"
+ id="rect358"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="3.8599999"
+ y="13.703"
+ id="rect360"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="3.8599999"
+ y="14.113"
+ id="rect362"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="3.8599999"
+ y="14.522"
+ id="rect364"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="3.8599999"
+ y="14.931"
+ id="rect366"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.24600001"
+ x="3.8599999"
+ y="15.423"
+ id="rect368"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="5.0120001"
+ cy="15.464"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse370"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="5.0120001"
+ cy="15.464"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse372"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="5.0120001"
+ cy="15.627"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse374"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="5.0120001"
+ cy="15.627"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse376"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="4.7049999"
+ y="15.505"
+ id="rect378"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="4.7049999"
+ y="15.505"
+ id="rect380"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 3.963,15.996 L 3.963,16.891"
+ id="path382"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 4.219,15.996 L 4.219,16.891"
+ id="path384"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 4.474,15.996 L 4.474,16.891"
+ id="path386"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 4.73,15.996 L 4.73,16.891"
+ id="path388"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 4.986,15.996 L 4.986,16.891"
+ id="path390"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 5.242,15.996 L 5.242,16.891"
+ id="path392"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="3.4,17.377 3.707,16.763 3.707,17.07 5.242,17.07 5.242,16.763 5.651,17.377 3.4,17.377 "
+ id="polygon394"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="3.4,17.377 3.707,16.763 3.707,17.07 5.242,17.07 5.242,16.763 5.651,17.377 3.4,17.377 "
+ id="polygon396"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.526"
+ y1="13.489"
+ x2="4.5999999"
+ y2="12.4"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line398"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="7"
+ y="18.4"
+ id="text400"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N2_D</text>
+ <text
+ x="7"
+ y="19.200001"
+ id="text402"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">(WINS)</text>
+ <text
+ x="3.9000001"
+ y="18.4"
+ id="text404"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N2_C</text>
+ <rect
+ width="1.535"
+ height="3.582"
+ x="0.60699999"
+ y="13.5"
+ id="rect406"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="0.60699999"
+ y="13.5"
+ id="rect408"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="0.75999999"
+ y="13.715"
+ id="rect410"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="0.75999999"
+ y="14.124"
+ id="rect412"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="0.75999999"
+ y="14.534"
+ id="rect414"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="0.75999999"
+ y="14.943"
+ id="rect416"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.24600001"
+ x="0.75999999"
+ y="15.434"
+ id="rect418"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="1.9119999"
+ cy="15.475"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse420"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="1.9119999"
+ cy="15.475"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse422"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="1.9119999"
+ cy="15.639"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse424"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="1.9119999"
+ cy="15.639"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse426"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="1.605"
+ y="15.516"
+ id="rect428"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="1.605"
+ y="15.516"
+ id="rect430"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 0.863,16.007 L 0.863,16.903"
+ id="path432"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 1.119,16.007 L 1.119,16.903"
+ id="path434"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 1.374,16.007 L 1.374,16.903"
+ id="path436"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 1.63,16.007 L 1.63,16.903"
+ id="path438"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 1.886,16.007 L 1.886,16.903"
+ id="path440"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 2.142,16.007 L 2.142,16.903"
+ id="path442"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="0.3,17.389 0.607,16.775 0.607,17.082 2.142,17.082 2.142,16.775 2.551,17.389 0.3,17.389 "
+ id="polygon444"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="0.3,17.389 0.607,16.775 0.607,17.082 2.142,17.082 2.142,16.775 2.551,17.389 0.3,17.389 "
+ id="polygon446"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.426"
+ y1="13.5"
+ x2="1.5"
+ y2="12.411"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line448"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="0.80000001"
+ y="18.410999"
+ id="text450"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N2_B</text>
+ <rect
+ width="1.535"
+ height="3.582"
+ x="-2.493"
+ y="13.5"
+ id="rect452"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="-2.493"
+ y="13.5"
+ id="rect454"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="-2.3399999"
+ y="13.715"
+ id="rect456"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="-2.3399999"
+ y="14.124"
+ id="rect458"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="-2.3399999"
+ y="14.534"
+ id="rect460"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="-2.3399999"
+ y="14.943"
+ id="rect462"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.24600001"
+ x="-2.3399999"
+ y="15.434"
+ id="rect464"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="-1.188"
+ cy="15.475"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse466"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="-1.188"
+ cy="15.475"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse468"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="-1.188"
+ cy="15.639"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse470"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="-1.188"
+ cy="15.639"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse472"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="-1.495"
+ y="15.516"
+ id="rect474"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="-1.495"
+ y="15.516"
+ id="rect476"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M -2.237,16.007 L -2.237,16.903"
+ id="path478"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M -1.981,16.007 L -1.981,16.903"
+ id="path480"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M -1.726,16.007 L -1.726,16.903"
+ id="path482"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M -1.47,16.007 L -1.47,16.903"
+ id="path484"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M -1.214,16.007 L -1.214,16.903"
+ id="path486"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M -0.958,16.007 L -0.958,16.903"
+ id="path488"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="-2.8,17.389 -2.493,16.775 -2.493,17.082 -0.958,17.082 -0.958,16.775 -0.549,17.389 -2.8,17.389 "
+ id="polygon490"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="-2.8,17.389 -2.493,16.775 -2.493,17.082 -0.958,17.082 -0.958,16.775 -0.549,17.389 -2.8,17.389 "
+ id="polygon492"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="-1.674"
+ y1="13.5"
+ x2="-1.6"
+ y2="12.411"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line494"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="-2.4000001"
+ y="18.4"
+ id="text496"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N2_A</text>
+ <line
+ x1="19.9"
+ y1="11.1"
+ x2="19.9"
+ y2="12.6"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line498"
+ style="stroke:#000000;stroke-width:0.1" />
+ <line
+ x1="25.299999"
+ y1="12.6"
+ x2="15.6"
+ y2="12.6"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line500"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="20.700001"
+ y="12.2"
+ id="text502"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Subnet 3</text>
+ <rect
+ width="1.493"
+ height="3.483"
+ x="24.399"
+ y="13.7"
+ id="rect504"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.493"
+ height="3.483"
+ x="24.399"
+ y="13.7"
+ id="rect506"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="24.548"
+ y="13.909"
+ id="rect508"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="24.548"
+ y="14.307"
+ id="rect510"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="24.548"
+ y="14.705"
+ id="rect512"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.194"
+ height="0.398"
+ x="24.548"
+ y="15.103"
+ id="rect514"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.74599999"
+ height="0.23899999"
+ x="24.548"
+ y="15.581"
+ id="rect516"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="25.667"
+ cy="15.621"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse518"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="25.667"
+ cy="15.621"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse520"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="25.667"
+ cy="15.78"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse522"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="25.667"
+ cy="15.78"
+ rx="0.052000001"
+ ry="0.052000001"
+ id="ellipse524"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.17900001"
+ height="0.15899999"
+ x="25.368999"
+ y="15.661"
+ id="rect526"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.17900001"
+ height="0.15899999"
+ x="25.368999"
+ y="15.661"
+ id="rect528"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 24.647,16.138 L 24.647,17.009"
+ id="path530"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 24.896,16.138 L 24.896,17.009"
+ id="path532"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 25.145,16.138 L 25.145,17.009"
+ id="path534"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 25.394,16.138 L 25.394,17.009"
+ id="path536"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 25.643,16.138 L 25.643,17.009"
+ id="path538"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 25.891,16.138 L 25.891,17.009"
+ id="path540"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="24.1,17.482 24.399,16.885 24.399,17.183 25.891,17.183 25.891,16.885 26.289,17.482 24.1,17.482 "
+ id="polygon542"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="24.1,17.482 24.399,16.885 24.399,17.183 25.891,17.183 25.891,16.885 26.289,17.482 24.1,17.482 "
+ id="polygon544"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="25.195"
+ y1="13.7"
+ x2="25.200001"
+ y2="12.5"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line546"
+ style="stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="21.007"
+ y="13.689"
+ id="rect548"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="21.007"
+ y="13.689"
+ id="rect550"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="21.16"
+ y="13.903"
+ id="rect552"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="21.16"
+ y="14.313"
+ id="rect554"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="21.16"
+ y="14.722"
+ id="rect556"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="21.16"
+ y="15.131"
+ id="rect558"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.24600001"
+ x="21.16"
+ y="15.623"
+ id="rect560"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="22.312"
+ cy="15.664"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse562"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="22.312"
+ cy="15.664"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse564"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="22.312"
+ cy="15.827"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse566"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="22.312"
+ cy="15.827"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse568"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="22.004999"
+ y="15.705"
+ id="rect570"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="22.004999"
+ y="15.705"
+ id="rect572"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 21.263,16.196 L 21.263,17.091"
+ id="path574"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 21.519,16.196 L 21.519,17.091"
+ id="path576"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 21.774,16.196 L 21.774,17.091"
+ id="path578"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 22.03,16.196 L 22.03,17.091"
+ id="path580"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 22.286,16.196 L 22.286,17.091"
+ id="path582"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 22.542,16.196 L 22.542,17.091"
+ id="path584"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="20.7,17.577 21.007,16.963 21.007,17.27 22.542,17.27 22.542,16.963 22.951,17.577 20.7,17.577 "
+ id="polygon586"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="20.7,17.577 21.007,16.963 21.007,17.27 22.542,17.27 22.542,16.963 22.951,17.577 20.7,17.577 "
+ id="polygon588"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="21.826"
+ y1="13.689"
+ x2="21.9"
+ y2="12.6"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line590"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="24.299999"
+ y="18.6"
+ id="text592"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N3_D</text>
+ <text
+ x="21.200001"
+ y="18.6"
+ id="text594"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N3_C</text>
+ <rect
+ width="1.535"
+ height="3.582"
+ x="17.907"
+ y="13.7"
+ id="rect596"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="17.907"
+ y="13.7"
+ id="rect598"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="18.059999"
+ y="13.915"
+ id="rect600"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="18.059999"
+ y="14.324"
+ id="rect602"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="18.059999"
+ y="14.734"
+ id="rect604"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="18.059999"
+ y="15.143"
+ id="rect606"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.24600001"
+ x="18.059999"
+ y="15.634"
+ id="rect608"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="19.212"
+ cy="15.675"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse610"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="19.212"
+ cy="15.675"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse612"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="19.212"
+ cy="15.839"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse614"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="19.212"
+ cy="15.839"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse616"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="18.905001"
+ y="15.716"
+ id="rect618"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="18.905001"
+ y="15.716"
+ id="rect620"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 18.163,16.207 L 18.163,17.103"
+ id="path622"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 18.419,16.207 L 18.419,17.103"
+ id="path624"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 18.674,16.207 L 18.674,17.103"
+ id="path626"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 18.93,16.207 L 18.93,17.103"
+ id="path628"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 19.186,16.207 L 19.186,17.103"
+ id="path630"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 19.442,16.207 L 19.442,17.103"
+ id="path632"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="17.6,17.589 17.907,16.975 17.907,17.282 19.442,17.282 19.442,16.975 19.851,17.589 17.6,17.589 "
+ id="polygon634"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="17.6,17.589 17.907,16.975 17.907,17.282 19.442,17.282 19.442,16.975 19.851,17.589 17.6,17.589 "
+ id="polygon636"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="18.726"
+ y1="13.7"
+ x2="18.799999"
+ y2="12.611"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line638"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="18.1"
+ y="18.611"
+ id="text640"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N3_B</text>
+ <rect
+ width="1.535"
+ height="3.582"
+ x="14.807"
+ y="13.7"
+ id="rect642"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.535"
+ height="3.582"
+ x="14.807"
+ y="13.7"
+ id="rect644"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="14.96"
+ y="13.915"
+ id="rect646"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="14.96"
+ y="14.324"
+ id="rect648"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="14.96"
+ y="14.734"
+ id="rect650"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.228"
+ height="0.40900001"
+ x="14.96"
+ y="15.143"
+ id="rect652"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.76700002"
+ height="0.24600001"
+ x="14.96"
+ y="15.634"
+ id="rect654"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="16.112"
+ cy="15.675"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse656"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="16.112"
+ cy="15.675"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse658"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="16.112"
+ cy="15.839"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse660"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="16.112"
+ cy="15.839"
+ rx="0.054000001"
+ ry="0.054000001"
+ id="ellipse662"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="15.805"
+ y="15.716"
+ id="rect664"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.184"
+ height="0.164"
+ x="15.805"
+ y="15.716"
+ id="rect666"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.063,16.207 L 15.063,17.103"
+ id="path668"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.319,16.207 L 15.319,17.103"
+ id="path670"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.574,16.207 L 15.574,17.103"
+ id="path672"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.83,16.207 L 15.83,17.103"
+ id="path674"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 16.086,16.207 L 16.086,17.103"
+ id="path676"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 16.342,16.207 L 16.342,17.103"
+ id="path678"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="14.5,17.589 14.807,16.975 14.807,17.282 16.342,17.282 16.342,16.975 16.751,17.589 14.5,17.589 "
+ id="polygon680"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="14.5,17.589 14.807,16.975 14.807,17.282 16.342,17.282 16.342,16.975 16.751,17.589 14.5,17.589 "
+ id="polygon682"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="15.626"
+ y1="13.7"
+ x2="15.7"
+ y2="12.611"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line684"
+ style="stroke:#000000;stroke-width:0.1" />
+ <text
+ x="14.9"
+ y="18.6"
+ id="text686"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">N3_A</text>
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/cups1.svg b/docs-xml/Samba3-HOWTO/images/cups1.svg
new file mode 100644
index 0000000000..18b7e4f2a6
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/cups1.svg
@@ -0,0 +1,274 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="27.950001cm"
+ height="23.34cm"
+ viewBox="0.8 0.857 28.75 24.198"
+ id="svg2">
+ <defs
+ id="defs117" />
+ <text
+ x="0.80000001"
+ y="1.4"
+ id="text4"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">CUPS in and of itself has this (general) filter chain (italic letters</text>
+ <text
+ x="0.80000001"
+ y="2.2"
+ id="text6"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">are file-formats or MIME types, other are filters (this is</text>
+ <text
+ x="0.80000001"
+ y="3"
+ id="text8"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">true for pre-1.1.15 of pre-4.3 versions of CUPS and ESP PrintPro):</text>
+ <text
+ x="2.0999999"
+ y="4.9000001"
+ id="text10"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">something-fileformat</text>
+ <polygon
+ points="4.625,5.6 4.625,6.45 4.2,6.45 5.05,7.3 5.9,6.45 5.475,6.45 5.475,5.6 4.625,5.6 "
+ id="polygon12"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.625,5.6 4.625,6.45 4.2,6.45 5.05,7.3 5.9,6.45 5.475,6.45 5.475,5.6 4.625,5.6 "
+ id="polygon14"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.625,5.6 4.625,6.45 4.2,6.45 5.05,7.3 5.9,6.45 5.475,6.45 5.475,5.6 4.625,5.6 "
+ id="polygon16"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="2.0999999"
+ y="11.9"
+ id="text18"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/postscript</text>
+ <polygon
+ points="4.725,12.6 4.725,13.45 4.3,13.45 5.15,14.3 6,13.45 5.575,13.45 5.575,12.6 4.725,12.6 "
+ id="polygon20"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.725,12.6 4.725,13.45 4.3,13.45 5.15,14.3 6,13.45 5.575,13.45 5.575,12.6 4.725,12.6 "
+ id="polygon22"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.725,12.6 4.725,13.45 4.3,13.45 5.15,14.3 6,13.45 5.575,13.45 5.575,12.6 4.725,12.6 "
+ id="polygon24"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="4.625,9 4.625,9.85 4.2,9.85 5.05,10.7 5.9,9.85 5.475,9.85 5.475,9 4.625,9 "
+ id="polygon26"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.625,9 4.625,9.85 4.2,9.85 5.05,10.7 5.9,9.85 5.475,9.85 5.475,9 4.625,9 "
+ id="polygon28"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.625,9 4.625,9.85 4.2,9.85 5.05,10.7 5.9,9.85 5.475,9.85 5.475,9 4.625,9 "
+ id="polygon30"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="2.8"
+ y="8.3000002"
+ id="text32"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">somethingtops</text>
+ <text
+ x="4.0999999"
+ y="15.3"
+ id="text34"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstops</text>
+ <polygon
+ points="4.725,15.8 4.725,16.65 4.3,16.65 5.15,17.5 6,16.65 5.575,16.65 5.575,15.8 4.725,15.8 "
+ id="polygon36"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.725,15.8 4.725,16.65 4.3,16.65 5.15,17.5 6,16.65 5.575,16.65 5.575,15.8 4.725,15.8 "
+ id="polygon38"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.725,15.8 4.725,16.65 4.3,16.65 5.15,17.5 6,16.65 5.575,16.65 5.575,15.8 4.725,15.8 "
+ id="polygon40"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="1.2"
+ y="18.4"
+ id="text42"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/vnd.cups-postscript</text>
+ <text
+ x="14.8"
+ y="18.4"
+ id="text44"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstoraster</text>
+ <text
+ x="13.4"
+ y="14.8"
+ id="text46"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/vnd.cups-raster</text>
+ <text
+ x="14.2"
+ y="11.2"
+ id="text48"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">rastertosomething</text>
+ <text
+ x="13.3"
+ y="7.6999998"
+ id="text50"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">something-device-specific</text>
+ <text
+ x="25.6"
+ y="7.6999998"
+ id="text52"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">backend</text>
+ <polygon
+ points="11.2,17.625 12.5,17.625 12.5,17.2 13.8,18.05 12.5,18.9 12.5,18.475 11.2,18.475 11.2,17.625 "
+ id="polygon54"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="11.2,17.625 12.5,17.625 12.5,17.2 13.8,18.05 12.5,18.9 12.5,18.475 11.2,18.475 11.2,17.625 "
+ id="polygon56"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="11.2,17.625 12.5,17.625 12.5,17.2 13.8,18.05 12.5,18.9 12.5,18.475 11.2,18.475 11.2,17.625 "
+ id="polygon58"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="16.35,17.5 16.35,16.35 15.9,16.35 16.8,15.2 17.7,16.35 17.25,16.35 17.25,17.5 16.35,17.5 "
+ id="polygon60"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="16.35,17.5 16.35,16.35 15.9,16.35 16.8,15.2 17.7,16.35 17.25,16.35 17.25,17.5 16.35,17.5 "
+ id="polygon62"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="16.35,17.5 16.35,16.35 15.9,16.35 16.8,15.2 17.7,16.35 17.25,16.35 17.25,17.5 16.35,17.5 "
+ id="polygon64"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="16.35,14 16.35,12.85 15.9,12.85 16.8,11.7 17.7,12.85 17.25,12.85 17.25,14 16.35,14 "
+ id="polygon66"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="16.35,14 16.35,12.85 15.9,12.85 16.8,11.7 17.7,12.85 17.25,12.85 17.25,14 16.35,14 "
+ id="polygon68"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="16.35,14 16.35,12.85 15.9,12.85 16.8,11.7 17.7,12.85 17.25,12.85 17.25,14 16.35,14 "
+ id="polygon70"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="16.35,10.3 16.35,9.15 15.9,9.15 16.8,8 17.7,9.15 17.25,9.15 17.25,10.3 16.35,10.3 "
+ id="polygon72"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="16.35,10.3 16.35,9.15 15.9,9.15 16.8,8 17.7,9.15 17.25,9.15 17.25,10.3 16.35,10.3 "
+ id="polygon74"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="16.35,10.3 16.35,9.15 15.9,9.15 16.8,8 17.7,9.15 17.25,9.15 17.25,10.3 16.35,10.3 "
+ id="polygon76"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="21.9,7.025 23.2,7.025 23.2,6.6 24.5,7.45 23.2,8.3 23.2,7.875 21.9,7.875 21.9,7.025 "
+ id="polygon78"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="21.9,7.025 23.2,7.025 23.2,6.6 24.5,7.45 23.2,8.3 23.2,7.875 21.9,7.875 21.9,7.025 "
+ id="polygon80"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="21.9,7.025 23.2,7.025 23.2,6.6 24.5,7.45 23.2,8.3 23.2,7.875 21.9,7.875 21.9,7.025 "
+ id="polygon82"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="8.1000004"
+ height="2.7"
+ x="20.200001"
+ y="10"
+ id="rect84"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="8.1000004"
+ height="2.7"
+ x="20.200001"
+ y="10"
+ id="rect86"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="20.5"
+ y="10.7"
+ id="text88"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">e.g. Gimp-Print filters</text>
+ <text
+ x="20.5"
+ y="11.5"
+ id="text90"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">may be plugged in here</text>
+ <text
+ x="20.5"
+ y="12.3"
+ id="text92"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">(= &quot;raster driver&quot;)</text>
+ <text
+ x="1.5"
+ y="20.700001"
+ id="text94"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">ESP PrintPro has some enhanced &quot;rastertosomething&quot; filters as compared to</text>
+ <text
+ x="1.5"
+ y="21.5"
+ id="text96"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">CUPS, and also a somewhat improved &quot;pstoraster&quot; filter.</text>
+ <text
+ x="1.6"
+ y="23"
+ id="text98"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to</text>
+ <text
+ x="1.6"
+ y="23.799999"
+ id="text100"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">CUPS and ESP PrintPro plug-in where rastertosomething is noted.</text>
+ <rect
+ width="10.1"
+ height="4.4000001"
+ x="18.6"
+ y="15.5"
+ id="rect102"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="10.1"
+ height="4.4000001"
+ x="18.6"
+ y="15.5"
+ id="rect104"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="19"
+ y="16.4"
+ id="text106"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">as shipped with CUPS,</text>
+ <text
+ x="19"
+ y="17.200001"
+ id="text108"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">independent from any</text>
+ <text
+ x="19"
+ y="18"
+ id="text110"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">GhostScript installation on the</text>
+ <text
+ x="19"
+ y="18.799999"
+ id="text112"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">system</text>
+ <text
+ x="19"
+ y="19.6"
+ id="text114"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">(= &quot;postscript interpreter&quot;)</text>
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/cups2.svg b/docs-xml/Samba3-HOWTO/images/cups2.svg
new file mode 100644
index 0000000000..8cddd339c0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/cups2.svg
@@ -0,0 +1,320 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="24.681999cm"
+ height="42.34cm"
+ viewBox="0.268 0.758 24.95 43.098"
+ id="svg2">
+ <defs
+ id="defs139" />
+ <text
+ x="1"
+ y="1.3"
+ id="text4"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">something-fileformat</text>
+ <polygon
+ points="3.163,1.9 3.163,2.825 2.7,2.825 3.625,3.75 4.55,2.825 4.088,2.825 4.088,1.9 3.163,1.9 "
+ id="polygon6"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.163,1.9 3.163,2.825 2.7,2.825 3.625,3.75 4.55,2.825 4.088,2.825 4.088,1.9 3.163,1.9 "
+ id="polygon8"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.163,1.9 3.163,2.825 2.7,2.825 3.625,3.75 4.55,2.825 4.088,2.825 4.088,1.9 3.163,1.9 "
+ id="polygon10"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="1.7"
+ y="4.8000002"
+ id="text12"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">somethingtops</text>
+ <text
+ x="1.4"
+ y="8.3000002"
+ id="text14"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/postscript</text>
+ <polygon
+ points="3.262,5.4 3.262,6.325 2.8,6.325 3.725,7.25 4.65,6.325 4.188,6.325 4.188,5.4 3.262,5.4 "
+ id="polygon16"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.262,5.4 3.262,6.325 2.8,6.325 3.725,7.25 4.65,6.325 4.188,6.325 4.188,5.4 3.262,5.4 "
+ id="polygon18"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.262,5.4 3.262,6.325 2.8,6.325 3.725,7.25 4.65,6.325 4.188,6.325 4.188,5.4 3.262,5.4 "
+ id="polygon20"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="2.8"
+ y="11.5"
+ id="text22"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstops</text>
+ <polygon
+ points="3.262,8.7 3.262,9.625 2.8,9.625 3.725,10.55 4.65,9.625 4.188,9.625 4.188,8.7 3.262,8.7 "
+ id="polygon24"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.262,8.7 3.262,9.625 2.8,9.625 3.725,10.55 4.65,9.625 4.188,9.625 4.188,8.7 3.262,8.7 "
+ id="polygon26"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.262,8.7 3.262,9.625 2.8,9.625 3.725,10.55 4.65,9.625 4.188,9.625 4.188,8.7 3.262,8.7 "
+ id="polygon28"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="3.362,12.1 3.362,13.025 2.9,13.025 3.825,13.95 4.75,13.025 4.287,13.025 4.287,12.1 3.362,12.1 "
+ id="polygon30"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.362,12.1 3.362,13.025 2.9,13.025 3.825,13.95 4.75,13.025 4.287,13.025 4.287,12.1 3.362,12.1 "
+ id="polygon32"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.362,12.1 3.362,13.025 2.9,13.025 3.825,13.95 4.75,13.025 4.287,13.025 4.287,12.1 3.362,12.1 "
+ id="polygon34"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="0.30000001"
+ y="15"
+ id="text36"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/vnd.cups-postscript</text>
+ <polygon
+ points="10.5,14.275 12,14.275 12,13.8 13.5,14.75 12,15.7 12,15.225 10.5,15.225 10.5,14.275 "
+ id="polygon38"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="10.5,14.275 12,14.275 12,13.8 13.5,14.75 12,15.7 12,15.225 10.5,15.225 10.5,14.275 "
+ id="polygon40"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="10.5,14.275 12,14.275 12,13.8 13.5,14.75 12,15.7 12,15.225 10.5,15.225 10.5,14.275 "
+ id="polygon42"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="14.2"
+ y="14.9"
+ id="text44"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">cupsomatic</text>
+ <rect
+ width="10.5"
+ height="3.8"
+ x="14.4"
+ y="10"
+ id="rect46"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="10.5"
+ height="3.8"
+ x="14.4"
+ y="10"
+ id="rect48"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="14.9"
+ y="11"
+ id="text50"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">(constructs complicated</text>
+ <text
+ x="14.9"
+ y="11.8"
+ id="text52"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Ghostscript commandline</text>
+ <text
+ x="14.9"
+ y="12.6"
+ id="text54"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">to let the file be processed by a</text>
+ <text
+ x="14.9"
+ y="13.4"
+ id="text56"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">&quot;-sDEVICE-s.th.&quot; call...)</text>
+ <polygon
+ points="3.462,15.7 3.462,16.625 3,16.625 3.925,17.55 4.85,16.625 4.388,16.625 4.388,15.7 3.462,15.7 "
+ id="polygon58"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.462,15.7 3.462,16.625 3,16.625 3.925,17.55 4.85,16.625 4.388,16.625 4.388,15.7 3.462,15.7 "
+ id="polygon60"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.462,15.7 3.462,16.625 3,16.625 3.925,17.55 4.85,16.625 4.388,16.625 4.388,15.7 3.462,15.7 "
+ id="polygon62"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="2.6159999"
+ y="18.299999"
+ id="text64"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstoraster</text>
+ <text
+ x="0.26800001"
+ y="19.1"
+ id="text66"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">(= &quot;postscript interpreter&quot;)</text>
+ <polygon
+ points="3.562,19.4 3.562,20.325 3.1,20.325 4.025,21.25 4.95,20.325 4.487,20.325 4.487,19.4 3.562,19.4 "
+ id="polygon68"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.562,19.4 3.562,20.325 3.1,20.325 4.025,21.25 4.95,20.325 4.487,20.325 4.487,19.4 3.562,19.4 "
+ id="polygon70"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.562,19.4 3.562,20.325 3.1,20.325 4.025,21.25 4.95,20.325 4.487,20.325 4.487,19.4 3.562,19.4 "
+ id="polygon72"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="0.80000001"
+ y="22.299999"
+ id="text74"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/vnd.cups-raster</text>
+ <polygon
+ points="3.663,23 3.663,23.925 3.2,23.925 4.125,24.85 5.05,23.925 4.588,23.925 4.588,23 3.663,23 "
+ id="polygon76"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.663,23 3.663,23.925 3.2,23.925 4.125,24.85 5.05,23.925 4.588,23.925 4.588,23 3.663,23 "
+ id="polygon78"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.663,23 3.663,23.925 3.2,23.925 4.125,24.85 5.05,23.925 4.588,23.925 4.588,23 3.663,23 "
+ id="polygon80"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="1.7"
+ y="25.5"
+ id="text82"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">rastertosomething</text>
+ <text
+ x="1.7"
+ y="26.299999"
+ id="text84"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">(= &quot;raster driver&quot;)</text>
+ <polygon
+ points="16.915,16.1 16.915,17.129 16.4,17.129 17.429,18.159 18.459,17.129 17.944,17.129 17.944,16.1 16.915,16.1 "
+ id="polygon86"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="16.915,16.1 16.915,17.129 16.4,17.129 17.429,18.159 18.459,17.129 17.944,17.129 17.944,16.1 16.915,16.1 "
+ id="polygon88"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="16.915,16.1 16.915,17.129 16.4,17.129 17.429,18.159 18.459,17.129 17.944,17.129 17.944,16.1 16.915,16.1 "
+ id="polygon90"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="3.762,26.8 3.762,27.725 3.3,27.725 4.225,28.65 5.15,27.725 4.688,27.725 4.688,26.8 3.762,26.8 "
+ id="polygon92"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.762,26.8 3.762,27.725 3.3,27.725 4.225,28.65 5.15,27.725 4.688,27.725 4.688,26.8 3.762,26.8 "
+ id="polygon94"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.762,26.8 3.762,27.725 3.3,27.725 4.225,28.65 5.15,27.725 4.688,27.725 4.688,26.8 3.762,26.8 "
+ id="polygon96"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="1"
+ y="29.6"
+ id="text98"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">something device specific</text>
+ <polygon
+ points="3.762,30.3 3.762,31.225 3.3,31.225 4.225,32.15 5.15,31.225 4.688,31.225 4.688,30.3 3.762,30.3 "
+ id="polygon100"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="3.762,30.3 3.762,31.225 3.3,31.225 4.225,32.15 5.15,31.225 4.688,31.225 4.688,30.3 3.762,30.3 "
+ id="polygon102"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="3.762,30.3 3.762,31.225 3.3,31.225 4.225,32.15 5.15,31.225 4.688,31.225 4.688,30.3 3.762,30.3 "
+ id="polygon104"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="3.2"
+ y="33.299999"
+ id="text106"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">backend</text>
+ <polygon
+ points="11.65,32.413 10.625,32.413 10.625,31.9 9.6,32.925 10.625,33.95 10.625,33.438 11.65,33.438 11.65,32.413 "
+ id="polygon108"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="11.65,32.413 10.625,32.413 10.625,31.9 9.6,32.925 10.625,33.95 10.625,33.438 11.65,33.438 11.65,32.413 "
+ id="polygon110"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="11.65,32.413 10.625,32.413 10.625,31.9 9.6,32.925 10.625,33.95 10.625,33.438 11.65,33.438 11.65,32.413 "
+ id="polygon112"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="7.5"
+ height="14.3"
+ x="14.6"
+ y="19.4"
+ id="rect114"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="7.5"
+ height="14.3"
+ x="14.6"
+ y="19.4"
+ id="rect116"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="15.28"
+ y="26.6"
+ id="text118"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Ghostscript at work....</text>
+ <text
+ x="1.2"
+ y="35.5"
+ id="text120"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Note, that cupsomatic &quot;kidnaps&quot; the printfile after the</text>
+ <text
+ x="1.2"
+ y="36.299999"
+ id="text122"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">application/vnd.cups-postscript stage and deviates it gh</text>
+ <text
+ x="1.2"
+ y="37.099998"
+ id="text124"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">the CUPS-external, systemwide Ghostscript installation, bypassing the</text>
+ <text
+ x="1.2"
+ y="37.900002"
+ id="text126"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">&quot;pstoraster&quot; filter (therefore also bypassing the CUPS-raster-drivers</text>
+ <text
+ x="1.2"
+ y="38.700001"
+ id="text128"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">&quot;rastertosomething&quot;, and hands the rasterized file directly to the CUPS</text>
+ <text
+ x="1.2"
+ y="39.5"
+ id="text130"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">backend...</text>
+ <text
+ x="1.2"
+ y="41.099998"
+ id="text132"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">cupsomatic is not made by the CUPS developers. It is an independent</text>
+ <text
+ x="1.2"
+ y="41.900002"
+ id="text134"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">contribution to printing development, made by people from</text>
+ <text
+ x="1.2"
+ y="42.700001"
+ id="text136"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Linuxprinting.org. (see also http://www.cups.org/cups-help.html)</text>
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/domain.svg b/docs-xml/Samba3-HOWTO/images/domain.svg
new file mode 100644
index 0000000000..aca5d4be42
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/domain.svg
@@ -0,0 +1,2288 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="30cm"
+ height="19.163cm"
+ viewBox="0.15 0.887 30.15 20.05"
+ id="svg2">
+ <defs
+ id="defs603" />
+ <ellipse
+ cx="15.15"
+ cy="11.2"
+ rx="14.95"
+ ry="8.8000002"
+ id="ellipse4"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.1830001"
+ height="6.5500002"
+ x="8.1999998"
+ y="3.9000001"
+ id="rect6"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.1830001"
+ height="6.5500002"
+ x="8.1999998"
+ y="3.9000001"
+ id="rect8"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.1830001"
+ height="6.5500002"
+ x="8.1999998"
+ y="3.9000001"
+ id="rect10"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.747"
+ height="2.6199999"
+ x="8.4180002"
+ y="4.118"
+ id="rect12"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="1.747"
+ height="2.6199999"
+ x="8.4180002"
+ y="4.118"
+ id="rect14"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.747"
+ height="2.6199999"
+ x="8.4180002"
+ y="4.118"
+ id="rect16"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.4180002"
+ y1="4.5549998"
+ x2="10.165"
+ y2="4.5549998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line18"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.165"
+ y1="4.9920001"
+ x2="8.4180002"
+ y2="4.9920001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line20"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.4180002"
+ y1="5.428"
+ x2="10.165"
+ y2="5.428"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line22"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.4180002"
+ y1="5.8649998"
+ x2="10.165"
+ y2="5.8649998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line24"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.165"
+ y1="6.302"
+ x2="8.4180002"
+ y2="6.302"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line26"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.201"
+ height="0.65499997"
+ x="8.4180002"
+ y="6.9569998"
+ id="rect28"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="1.201"
+ height="0.65499997"
+ x="8.4180002"
+ y="6.9569998"
+ id="rect30"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.201"
+ height="0.65499997"
+ x="8.4180002"
+ y="6.9569998"
+ id="rect32"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.1999998"
+ y1="8.0480003"
+ x2="10.383"
+ y2="8.0480003"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line34"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="9.1820002"
+ y="8.2670002"
+ id="rect36"
+ style="fill:#00cd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="9.1820002"
+ y="8.2670002"
+ id="rect38"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="9.1820002"
+ y="8.2670002"
+ id="rect40"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="9.6190004"
+ y="8.2670002"
+ id="rect42"
+ style="fill:#cdcd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="9.6190004"
+ y="8.2670002"
+ id="rect44"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="9.6190004"
+ y="8.2670002"
+ id="rect46"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="10.056"
+ y="8.2670002"
+ id="rect48"
+ style="fill:#cd0000;stroke:none;stroke-width:0" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="10.056"
+ y="8.2670002"
+ id="rect50"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.109"
+ height="0.109"
+ x="10.056"
+ y="8.2670002"
+ id="rect52"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.21799999"
+ height="0.21799999"
+ x="9.9469995"
+ y="7.612"
+ id="rect54"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.21799999"
+ height="0.21799999"
+ x="9.9469995"
+ y="7.612"
+ id="rect56"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.21799999"
+ height="0.21799999"
+ x="9.9469995"
+ y="7.612"
+ id="rect58"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.4180002"
+ y1="7.2839999"
+ x2="9.6190004"
+ y2="7.2839999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line60"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.32800001"
+ height="0.32800001"
+ x="8.4180002"
+ y="8.1569996"
+ id="rect62"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.32800001"
+ height="0.32800001"
+ x="8.4180002"
+ y="8.1569996"
+ id="rect64"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.32800001"
+ height="0.32800001"
+ x="8.4180002"
+ y="8.1569996"
+ id="rect66"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.528"
+ height="0.109"
+ x="8.5270004"
+ y="6.4109998"
+ id="rect68"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="1.528"
+ height="0.109"
+ x="8.5270004"
+ y="6.4109998"
+ id="rect70"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.528"
+ height="0.109"
+ x="8.5270004"
+ y="6.4109998"
+ id="rect72"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.5270004"
+ y1="7.066"
+ x2="9.5100002"
+ y2="7.066"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line74"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="9.5100002"
+ y1="7.1750002"
+ x2="9.401"
+ y2="7.1750002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line76"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.5270004"
+ y1="7.1750002"
+ x2="8.6370001"
+ y2="7.1750002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line78"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.546"
+ height="0.109"
+ x="8.7460003"
+ y="7.066"
+ id="rect80"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="0.546"
+ height="0.109"
+ x="8.7460003"
+ y="7.066"
+ id="rect82"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.546"
+ height="0.109"
+ x="8.7460003"
+ y="7.066"
+ id="rect84"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.5270004"
+ y1="6.6290002"
+ x2="8.6370001"
+ y2="6.6290002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line86"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.7460003"
+ y1="6.6290002"
+ x2="8.8549995"
+ y2="6.6290002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line88"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="9.8369999"
+ y1="6.6290002"
+ x2="10.056"
+ y2="6.6290002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line90"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="10.341"
+ x2="10.274"
+ y2="10.341"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line92"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="10.232"
+ x2="8.309"
+ y2="10.232"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line94"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="10.123"
+ x2="10.274"
+ y2="10.123"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line96"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="10.013"
+ x2="8.309"
+ y2="10.013"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line98"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="9.9040003"
+ x2="10.274"
+ y2="9.9040003"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line100"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="9.7950001"
+ x2="8.309"
+ y2="9.7950001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line102"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="9.6859999"
+ x2="10.274"
+ y2="9.6859999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line104"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="9.5769997"
+ x2="8.309"
+ y2="9.5769997"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line106"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="9.467"
+ x2="10.274"
+ y2="9.467"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line108"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="9.3579998"
+ x2="8.309"
+ y2="9.3579998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line110"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="9.2489996"
+ x2="10.274"
+ y2="9.2489996"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line112"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="9.1400003"
+ x2="8.309"
+ y2="9.1400003"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line114"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="8.309"
+ y1="9.0310001"
+ x2="10.274"
+ y2="9.0310001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line116"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="10.274"
+ y1="8.9219999"
+ x2="8.309"
+ y2="8.9219999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line118"
+ style="stroke:#000000;stroke-width:0.01" />
+ <text
+ x="4.9000001"
+ y="5.6999998"
+ id="text120"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Primary</text>
+ <text
+ x="4.9000001"
+ y="6.5"
+ id="text122"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Domain</text>
+ <text
+ x="4.9000001"
+ y="7.3000002"
+ id="text124"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Controller</text>
+ <rect
+ width="2.6359999"
+ height="5.2709999"
+ x="1.7"
+ y="9.1000004"
+ id="rect126"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.6359999"
+ height="5.2709999"
+ x="1.7"
+ y="9.1000004"
+ id="rect128"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.6359999"
+ height="5.2709999"
+ x="1.7"
+ y="9.1000004"
+ id="rect130"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="2.108"
+ height="2.108"
+ x="1.964"
+ y="9.3640003"
+ id="rect132"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.108"
+ height="2.108"
+ x="1.964"
+ y="9.3640003"
+ id="rect134"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.108"
+ height="2.108"
+ x="1.964"
+ y="9.3640003"
+ id="rect136"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.072"
+ y1="9.8909998"
+ x2="1.964"
+ y2="9.8909998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line138"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.964"
+ y1="10.418"
+ x2="4.072"
+ y2="10.418"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line140"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.072"
+ y1="10.813"
+ x2="1.964"
+ y2="10.813"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line142"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.45"
+ height="0.79100001"
+ x="1.964"
+ y="11.736"
+ id="rect144"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="1.45"
+ height="0.79100001"
+ x="1.964"
+ y="11.736"
+ id="rect146"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.45"
+ height="0.79100001"
+ x="1.964"
+ y="11.736"
+ id="rect148"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.7"
+ y1="12.658"
+ x2="4.336"
+ y2="12.658"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line150"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="2.8859999"
+ y="12.922"
+ id="rect152"
+ style="fill:#00cd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="2.8859999"
+ y="12.922"
+ id="rect154"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="2.8859999"
+ y="12.922"
+ id="rect156"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="3.4130001"
+ y="12.922"
+ id="rect158"
+ style="fill:#cdcd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="3.4130001"
+ y="12.922"
+ id="rect160"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="3.4130001"
+ y="12.922"
+ id="rect162"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="3.9400001"
+ y="12.922"
+ id="rect164"
+ style="fill:#cd0000;stroke:none;stroke-width:0" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="3.9400001"
+ y="12.922"
+ id="rect166"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="3.9400001"
+ y="12.922"
+ id="rect168"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.264"
+ height="0.132"
+ x="3.8080001"
+ y="12.131"
+ id="rect170"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.264"
+ height="0.132"
+ x="3.8080001"
+ y="12.131"
+ id="rect172"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.264"
+ height="0.132"
+ x="3.8080001"
+ y="12.131"
+ id="rect174"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.964"
+ y1="12.131"
+ x2="3.4130001"
+ y2="12.131"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line176"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.39500001"
+ height="0.39500001"
+ x="1.964"
+ y="12.79"
+ id="rect178"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.39500001"
+ height="0.39500001"
+ x="1.964"
+ y="12.79"
+ id="rect180"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.39500001"
+ height="0.39500001"
+ x="1.964"
+ y="12.79"
+ id="rect182"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.845"
+ height="0.132"
+ x="2.095"
+ y="10.945"
+ id="rect184"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="1.845"
+ height="0.132"
+ x="2.095"
+ y="10.945"
+ id="rect186"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.845"
+ height="0.132"
+ x="2.095"
+ y="10.945"
+ id="rect188"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="2.095"
+ y1="11.867"
+ x2="3.2809999"
+ y2="11.867"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line190"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="3.2809999"
+ y1="11.999"
+ x2="3.1500001"
+ y2="11.999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line192"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="2.095"
+ y1="11.999"
+ x2="2.227"
+ y2="11.999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line194"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.65899998"
+ height="0.132"
+ x="2.359"
+ y="11.867"
+ id="rect196"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="0.65899998"
+ height="0.132"
+ x="2.359"
+ y="11.867"
+ id="rect198"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.65899998"
+ height="0.132"
+ x="2.359"
+ y="11.867"
+ id="rect200"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="2.095"
+ y1="11.208"
+ x2="2.227"
+ y2="11.208"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line202"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="2.359"
+ y1="11.208"
+ x2="2.4909999"
+ y2="11.208"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line204"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="3.677"
+ y1="11.208"
+ x2="3.9400001"
+ y2="11.208"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line206"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.204"
+ y1="14.239"
+ x2="1.832"
+ y2="14.239"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line208"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.832"
+ y1="14.108"
+ x2="4.204"
+ y2="14.108"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line210"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.204"
+ y1="13.976"
+ x2="1.832"
+ y2="13.976"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line212"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.832"
+ y1="13.844"
+ x2="4.204"
+ y2="13.844"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line214"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.204"
+ y1="13.712"
+ x2="1.832"
+ y2="13.712"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line216"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="1.832"
+ y1="13.58"
+ x2="4.204"
+ y2="13.58"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line218"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="4.204"
+ y1="13.449"
+ x2="1.832"
+ y2="13.449"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line220"
+ style="stroke:#000000;stroke-width:0.01" />
+ <text
+ x="3.5"
+ y="15.5"
+ id="text222"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Backup Domain</text>
+ <text
+ x="3.5"
+ y="16.299999"
+ id="text224"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Controller 1</text>
+ <rect
+ width="2.6359999"
+ height="5.2709999"
+ x="13.6"
+ y="13.5"
+ id="rect226"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.6359999"
+ height="5.2709999"
+ x="13.6"
+ y="13.5"
+ id="rect228"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.6359999"
+ height="5.2709999"
+ x="13.6"
+ y="13.5"
+ id="rect230"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="2.108"
+ height="2.108"
+ x="13.864"
+ y="13.764"
+ id="rect232"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.108"
+ height="2.108"
+ x="13.864"
+ y="13.764"
+ id="rect234"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.108"
+ height="2.108"
+ x="13.864"
+ y="13.764"
+ id="rect236"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="15.972"
+ y1="14.291"
+ x2="13.864"
+ y2="14.291"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line238"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.864"
+ y1="14.818"
+ x2="15.972"
+ y2="14.818"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line240"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="15.972"
+ y1="15.213"
+ x2="13.864"
+ y2="15.213"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line242"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.45"
+ height="0.79100001"
+ x="13.864"
+ y="16.136"
+ id="rect244"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="1.45"
+ height="0.79100001"
+ x="13.864"
+ y="16.136"
+ id="rect246"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.45"
+ height="0.79100001"
+ x="13.864"
+ y="16.136"
+ id="rect248"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.6"
+ y1="17.058001"
+ x2="16.236"
+ y2="17.058001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line250"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="14.786"
+ y="17.322001"
+ id="rect252"
+ style="fill:#00cd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="14.786"
+ y="17.322001"
+ id="rect254"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="14.786"
+ y="17.322001"
+ id="rect256"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="15.313"
+ y="17.322001"
+ id="rect258"
+ style="fill:#cdcd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="15.313"
+ y="17.322001"
+ id="rect260"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="15.313"
+ y="17.322001"
+ id="rect262"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="15.84"
+ y="17.322001"
+ id="rect264"
+ style="fill:#cd0000;stroke:none;stroke-width:0" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="15.84"
+ y="17.322001"
+ id="rect266"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.132"
+ height="0.132"
+ x="15.84"
+ y="17.322001"
+ id="rect268"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.264"
+ height="0.132"
+ x="15.708"
+ y="16.531"
+ id="rect270"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.264"
+ height="0.132"
+ x="15.708"
+ y="16.531"
+ id="rect272"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.264"
+ height="0.132"
+ x="15.708"
+ y="16.531"
+ id="rect274"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.864"
+ y1="16.531"
+ x2="15.313"
+ y2="16.531"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line276"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.39500001"
+ height="0.39500001"
+ x="13.864"
+ y="17.190001"
+ id="rect278"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.39500001"
+ height="0.39500001"
+ x="13.864"
+ y="17.190001"
+ id="rect280"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.39500001"
+ height="0.39500001"
+ x="13.864"
+ y="17.190001"
+ id="rect282"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.845"
+ height="0.132"
+ x="13.995"
+ y="15.345"
+ id="rect284"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="1.845"
+ height="0.132"
+ x="13.995"
+ y="15.345"
+ id="rect286"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.845"
+ height="0.132"
+ x="13.995"
+ y="15.345"
+ id="rect288"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.995"
+ y1="16.267"
+ x2="15.181"
+ y2="16.267"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line290"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="15.181"
+ y1="16.399"
+ x2="15.05"
+ y2="16.399"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line292"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.995"
+ y1="16.399"
+ x2="14.127"
+ y2="16.399"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line294"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.65899998"
+ height="0.132"
+ x="14.259"
+ y="16.267"
+ id="rect296"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="0.65899998"
+ height="0.132"
+ x="14.259"
+ y="16.267"
+ id="rect298"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.65899998"
+ height="0.132"
+ x="14.259"
+ y="16.267"
+ id="rect300"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.995"
+ y1="15.608"
+ x2="14.127"
+ y2="15.608"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line302"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="14.259"
+ y1="15.608"
+ x2="14.391"
+ y2="15.608"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line304"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="15.577"
+ y1="15.608"
+ x2="15.84"
+ y2="15.608"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line306"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="16.104"
+ y1="18.639"
+ x2="13.732"
+ y2="18.639"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line308"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.732"
+ y1="18.507999"
+ x2="16.104"
+ y2="18.507999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line310"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="16.104"
+ y1="18.375999"
+ x2="13.732"
+ y2="18.375999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line312"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.732"
+ y1="18.243999"
+ x2="16.104"
+ y2="18.243999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line314"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="16.104"
+ y1="18.112"
+ x2="13.732"
+ y2="18.112"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line316"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="13.732"
+ y1="17.98"
+ x2="16.104"
+ y2="17.98"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line318"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="16.104"
+ y1="17.849001"
+ x2="13.732"
+ y2="17.849001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line320"
+ style="stroke:#000000;stroke-width:0.01" />
+ <text
+ x="16.9"
+ y="14.7"
+ id="text322"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Backup Domain</text>
+ <text
+ x="16.9"
+ y="15.5"
+ id="text324"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Controller 2</text>
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="4.336,11.736 4.336,12.000 9.292,12.000 9.292,10.450 "
+ id="polyline326"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="14.918,13.500 14.918,11.975 9.292,11.975 9.292,10.450 "
+ id="polyline328"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="5.3000002"
+ height="1.767"
+ x="17.4"
+ y="4.9000001"
+ id="rect330"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="5.3000002"
+ height="1.767"
+ x="17.4"
+ y="4.9000001"
+ id="rect332"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="5.3000002"
+ height="1.767"
+ x="17.4"
+ y="4.9000001"
+ id="rect334"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="2.0190001"
+ height="1.01"
+ x="20.555"
+ y="5.4050002"
+ id="rect336"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.0190001"
+ height="1.01"
+ x="20.555"
+ y="5.4050002"
+ id="rect338"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.0190001"
+ height="1.01"
+ x="20.555"
+ y="5.4050002"
+ id="rect340"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="22.573999"
+ y1="5.9099998"
+ x2="20.555"
+ y2="5.9099998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line342"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.37900001"
+ height="1.388"
+ x="20.049999"
+ y="5.026"
+ id="rect344"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.37900001"
+ height="1.388"
+ x="20.049999"
+ y="5.026"
+ id="rect346"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.37900001"
+ height="1.388"
+ x="20.049999"
+ y="5.026"
+ id="rect348"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="18.662001"
+ y="5.152"
+ id="rect350"
+ style="fill:#00cd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="18.662001"
+ y="5.152"
+ id="rect352"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="18.662001"
+ y="5.152"
+ id="rect354"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="18.914"
+ y="5.152"
+ id="rect356"
+ style="fill:#cdcd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="18.914"
+ y="5.152"
+ id="rect358"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="18.914"
+ y="5.152"
+ id="rect360"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="19.167"
+ y="5.152"
+ id="rect362"
+ style="fill:#cd0000;stroke:none;stroke-width:0" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="19.167"
+ y="5.152"
+ id="rect364"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.126"
+ height="0.126"
+ x="19.167"
+ y="5.152"
+ id="rect366"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.252"
+ height="0.252"
+ x="19.545"
+ y="5.026"
+ id="rect368"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.252"
+ height="0.252"
+ x="19.545"
+ y="5.026"
+ id="rect370"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.252"
+ height="0.252"
+ x="19.545"
+ y="5.026"
+ id="rect372"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.37900001"
+ height="0.37900001"
+ x="17.652"
+ y="5.026"
+ id="rect374"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.37900001"
+ height="0.37900001"
+ x="17.652"
+ y="5.026"
+ id="rect376"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.37900001"
+ height="0.37900001"
+ x="17.652"
+ y="5.026"
+ id="rect378"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.767"
+ height="0.126"
+ x="20.681"
+ y="6.0359998"
+ id="rect380"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="1.767"
+ height="0.126"
+ x="20.681"
+ y="6.0359998"
+ id="rect382"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.767"
+ height="0.126"
+ x="20.681"
+ y="6.0359998"
+ id="rect384"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.176001"
+ y1="5.152"
+ x2="20.176001"
+ y2="6.2880001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line386"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.126"
+ height="0.63099998"
+ x="20.176001"
+ y="5.4050002"
+ id="rect388"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="0.126"
+ height="0.63099998"
+ x="20.176001"
+ y="5.4050002"
+ id="rect390"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.126"
+ height="0.63099998"
+ x="20.176001"
+ y="5.4050002"
+ id="rect392"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="22.195"
+ y1="6.2880001"
+ x2="22.448"
+ y2="6.2880001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line394"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.525999"
+ y1="5.783"
+ x2="19.798"
+ y2="5.783"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line396"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.798"
+ y1="5.9099998"
+ x2="17.525999"
+ y2="5.9099998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line398"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.525999"
+ y1="6.0359998"
+ x2="19.798"
+ y2="6.0359998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line400"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.798"
+ y1="6.414"
+ x2="17.525999"
+ y2="6.414"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line402"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.525999"
+ y1="6.2880001"
+ x2="19.798"
+ y2="6.2880001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line404"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.798"
+ y1="6.1620002"
+ x2="17.525999"
+ y2="6.1620002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line406"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.681"
+ y1="6.2880001"
+ x2="20.806999"
+ y2="6.2880001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line408"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.933001"
+ y1="6.2880001"
+ x2="21.059999"
+ y2="6.2880001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line410"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.302"
+ y1="6.2880001"
+ x2="20.302"
+ y2="6.1620002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line412"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.302"
+ y1="5.2789998"
+ x2="20.302"
+ y2="5.152"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line414"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="5.4000001"
+ height="1.8"
+ x="17.4"
+ y="7.4000001"
+ id="rect416"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="5.4000001"
+ height="1.8"
+ x="17.4"
+ y="7.4000001"
+ id="rect418"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="5.4000001"
+ height="1.8"
+ x="17.4"
+ y="7.4000001"
+ id="rect420"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="2.0569999"
+ height="1.029"
+ x="20.614"
+ y="7.914"
+ id="rect422"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.0569999"
+ height="1.029"
+ x="20.614"
+ y="7.914"
+ id="rect424"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.0569999"
+ height="1.029"
+ x="20.614"
+ y="7.914"
+ id="rect426"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="22.671"
+ y1="8.4289999"
+ x2="20.614"
+ y2="8.4289999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line428"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.38600001"
+ height="1.414"
+ x="20.1"
+ y="7.5289998"
+ id="rect430"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.38600001"
+ height="1.414"
+ x="20.1"
+ y="7.5289998"
+ id="rect432"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.38600001"
+ height="1.414"
+ x="20.1"
+ y="7.5289998"
+ id="rect434"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="18.686001"
+ y="7.6570001"
+ id="rect436"
+ style="fill:#00cd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="18.686001"
+ y="7.6570001"
+ id="rect438"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="18.686001"
+ y="7.6570001"
+ id="rect440"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="18.943001"
+ y="7.6570001"
+ id="rect442"
+ style="fill:#cdcd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="18.943001"
+ y="7.6570001"
+ id="rect444"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="18.943001"
+ y="7.6570001"
+ id="rect446"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="19.200001"
+ y="7.6570001"
+ id="rect448"
+ style="fill:#cd0000;stroke:none;stroke-width:0" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="19.200001"
+ y="7.6570001"
+ id="rect450"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.12899999"
+ height="0.12899999"
+ x="19.200001"
+ y="7.6570001"
+ id="rect452"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.257"
+ height="0.257"
+ x="19.586"
+ y="7.5289998"
+ id="rect454"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.257"
+ height="0.257"
+ x="19.586"
+ y="7.5289998"
+ id="rect456"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.257"
+ height="0.257"
+ x="19.586"
+ y="7.5289998"
+ id="rect458"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.38600001"
+ height="0.38600001"
+ x="17.657"
+ y="7.5289998"
+ id="rect460"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.38600001"
+ height="0.38600001"
+ x="17.657"
+ y="7.5289998"
+ id="rect462"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.38600001"
+ height="0.38600001"
+ x="17.657"
+ y="7.5289998"
+ id="rect464"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.8"
+ height="0.12899999"
+ x="20.743"
+ y="8.5570002"
+ id="rect466"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="1.8"
+ height="0.12899999"
+ x="20.743"
+ y="8.5570002"
+ id="rect468"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.8"
+ height="0.12899999"
+ x="20.743"
+ y="8.5570002"
+ id="rect470"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.229"
+ y1="7.6570001"
+ x2="20.229"
+ y2="8.8140001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line472"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.12899999"
+ height="0.64300001"
+ x="20.229"
+ y="7.914"
+ id="rect474"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="0.12899999"
+ height="0.64300001"
+ x="20.229"
+ y="7.914"
+ id="rect476"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.12899999"
+ height="0.64300001"
+ x="20.229"
+ y="7.914"
+ id="rect478"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="22.285999"
+ y1="8.8140001"
+ x2="22.542999"
+ y2="8.8140001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line480"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.528999"
+ y1="8.3000002"
+ x2="19.843"
+ y2="8.3000002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line482"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.843"
+ y1="8.4289999"
+ x2="17.528999"
+ y2="8.4289999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line484"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.528999"
+ y1="8.5570002"
+ x2="19.843"
+ y2="8.5570002"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line486"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.843"
+ y1="8.9429998"
+ x2="17.528999"
+ y2="8.9429998"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line488"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.528999"
+ y1="8.8140001"
+ x2="19.843"
+ y2="8.8140001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line490"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.843"
+ y1="8.6859999"
+ x2="17.528999"
+ y2="8.6859999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line492"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.743"
+ y1="8.8140001"
+ x2="20.871"
+ y2="8.8140001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line494"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="21"
+ y1="8.8140001"
+ x2="21.129"
+ y2="8.8140001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line496"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.357"
+ y1="8.8140001"
+ x2="20.357"
+ y2="8.6859999"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line498"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.357"
+ y1="7.7859998"
+ x2="20.357"
+ y2="7.6570001"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line500"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="5.4499998"
+ height="1.817"
+ x="17.5"
+ y="9.8000002"
+ id="rect502"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="5.4499998"
+ height="1.817"
+ x="17.5"
+ y="9.8000002"
+ id="rect504"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="5.4499998"
+ height="1.817"
+ x="17.5"
+ y="9.8000002"
+ id="rect506"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="2.076"
+ height="1.038"
+ x="20.743999"
+ y="10.319"
+ id="rect508"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="2.076"
+ height="1.038"
+ x="20.743999"
+ y="10.319"
+ id="rect510"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="2.076"
+ height="1.038"
+ x="20.743999"
+ y="10.319"
+ id="rect512"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="22.82"
+ y1="10.838"
+ x2="20.743999"
+ y2="10.838"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line514"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.389"
+ height="1.427"
+ x="20.225"
+ y="9.9300003"
+ id="rect516"
+ style="fill:#d9d9cd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.389"
+ height="1.427"
+ x="20.225"
+ y="9.9300003"
+ id="rect518"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.389"
+ height="1.427"
+ x="20.225"
+ y="9.9300003"
+ id="rect520"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="18.798"
+ y="10.06"
+ id="rect522"
+ style="fill:#00cd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="18.798"
+ y="10.06"
+ id="rect524"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="18.798"
+ y="10.06"
+ id="rect526"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="19.056999"
+ y="10.06"
+ id="rect528"
+ style="fill:#cdcd00;stroke:none;stroke-width:0" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="19.056999"
+ y="10.06"
+ id="rect530"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="19.056999"
+ y="10.06"
+ id="rect532"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="19.316999"
+ y="10.06"
+ id="rect534"
+ style="fill:#cd0000;stroke:none;stroke-width:0" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="19.316999"
+ y="10.06"
+ id="rect536"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.13"
+ height="0.13"
+ x="19.316999"
+ y="10.06"
+ id="rect538"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.25999999"
+ height="0.25999999"
+ x="19.705999"
+ y="9.9300003"
+ id="rect540"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.25999999"
+ height="0.25999999"
+ x="19.705999"
+ y="9.9300003"
+ id="rect542"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.25999999"
+ height="0.25999999"
+ x="19.705999"
+ y="9.9300003"
+ id="rect544"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.389"
+ height="0.389"
+ x="17.76"
+ y="9.9300003"
+ id="rect546"
+ style="fill:#cdcdbd;stroke:none;stroke-width:0" />
+ <rect
+ width="0.389"
+ height="0.389"
+ x="17.76"
+ y="9.9300003"
+ id="rect548"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.389"
+ height="0.389"
+ x="17.76"
+ y="9.9300003"
+ id="rect550"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.817"
+ height="0.13"
+ x="20.874001"
+ y="10.968"
+ id="rect552"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="1.817"
+ height="0.13"
+ x="20.874001"
+ y="10.968"
+ id="rect554"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.817"
+ height="0.13"
+ x="20.874001"
+ y="10.968"
+ id="rect556"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.355"
+ y1="10.06"
+ x2="20.355"
+ y2="11.227"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line558"
+ style="stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.13"
+ height="0.64899999"
+ x="20.355"
+ y="10.319"
+ id="rect560"
+ style="fill:#cdcdc1;stroke:none;stroke-width:0" />
+ <rect
+ width="0.13"
+ height="0.64899999"
+ x="20.355"
+ y="10.319"
+ id="rect562"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="0.13"
+ height="0.64899999"
+ x="20.355"
+ y="10.319"
+ id="rect564"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="22.431"
+ y1="11.227"
+ x2="22.690001"
+ y2="11.227"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line566"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.629999"
+ y1="10.708"
+ x2="19.965"
+ y2="10.708"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line568"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.965"
+ y1="10.838"
+ x2="17.629999"
+ y2="10.838"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line570"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.629999"
+ y1="10.968"
+ x2="19.965"
+ y2="10.968"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line572"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.965"
+ y1="11.357"
+ x2="17.629999"
+ y2="11.357"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line574"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="17.629999"
+ y1="11.227"
+ x2="19.965"
+ y2="11.227"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line576"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="19.965"
+ y1="11.098"
+ x2="17.629999"
+ y2="11.098"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line578"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.874001"
+ y1="11.227"
+ x2="21.004"
+ y2="11.227"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line580"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="21.132999"
+ y1="11.227"
+ x2="21.263"
+ y2="11.227"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line582"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.485001"
+ y1="11.227"
+ x2="20.485001"
+ y2="11.098"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line584"
+ style="stroke:#000000;stroke-width:0.01" />
+ <line
+ x1="20.485001"
+ y1="10.189"
+ x2="20.485001"
+ y2="10.06"
+ stroke="#000000"
+ stroke-width="0.010"
+ id="line586"
+ style="stroke:#000000;stroke-width:0.01" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="9.300,12.000 13.992,12.000 13.992,5.783 17.400,5.783 "
+ id="polyline588"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="17.400,8.300 14.000,8.300 14.000,12.000 10.200,12.000 "
+ id="polyline590"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="17.500,10.708 14.000,10.708 14.000,12.000 10.300,12.000 "
+ id="polyline592"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="17.700001"
+ y="4.3000002"
+ id="text594"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Workstation A</text>
+ <text
+ x="23.799999"
+ y="8.6000004"
+ id="text596"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Workstation B</text>
+ <text
+ x="23.799999"
+ y="10.9"
+ id="text598"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Workstation C</text>
+ <text
+ x="13.1"
+ y="1.7"
+ id="text600"
+ style="font-size:1.20000005px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">DOMAIN</text>
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/ethereal1.png b/docs-xml/Samba3-HOWTO/images/ethereal1.png
new file mode 100644
index 0000000000..c8655389d0
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/ethereal1.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/ethereal2.png b/docs-xml/Samba3-HOWTO/images/ethereal2.png
new file mode 100644
index 0000000000..f366772d3b
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/ethereal2.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/idmap-gid2sid.svg b/docs-xml/Samba3-HOWTO/images/idmap-gid2sid.svg
new file mode 100644
index 0000000000..61181b75c8
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap-gid2sid.svg
@@ -0,0 +1,277 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="24.174cm"
+ height="19.486cm"
+ viewBox="-0.49 0.171 23.684 19.657"
+ id="svg2">
+ <defs
+ id="defs97" />
+ <path
+ d="M 3.333,0.221 L 5.667,0.221 C 5.989,0.221 6.25,0.626 6.25,1.125 C 6.25,1.624 5.989,2.029 5.667,2.029 L 3.333,2.029 C 3.011,2.029 2.75,1.624 2.75,1.125 C 2.75,0.626 3.011,0.221 3.333,0.221"
+ id="path4"
+ style="fill:#c9c9c9;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 3.333,0.221 L 5.667,0.221 C 5.989,0.221 6.25,0.626 6.25,1.125 C 6.25,1.624 5.989,2.029 5.667,2.029 L 3.333,2.029 C 3.011,2.029 2.75,1.624 2.75,1.125 C 2.75,0.626 3.011,0.221 3.333,0.221"
+ id="path6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.7609999"
+ y="1.303"
+ id="text8"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">GID</text>
+ <line
+ x1="4.5040002"
+ y1="5.5"
+ x2="4.5019999"
+ y2="6.1500001"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line10"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.102,6.149 4.5,6.95 4.902,6.151 4.102,6.149 "
+ id="polygon12"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 5.883,16.8 L 9.117,16.8 C 9.564,16.8 9.926,17.428 9.926,18.204 C 9.926,18.979 9.564,19.607 9.117,19.607 L 5.883,19.607 C 5.436,19.607 5.074,18.979 5.074,18.204 C 5.074,17.428 5.436,16.8 5.883,16.8"
+ id="path14"
+ style="fill:#d5d5d5;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 5.883,16.8 L 9.117,16.8 C 9.564,16.8 9.926,17.428 9.926,18.204 C 9.926,18.979 9.564,19.607 9.117,19.607 L 5.883,19.607 C 5.436,19.607 5.074,18.979 5.074,18.204 C 5.074,17.428 5.436,16.8 5.883,16.8"
+ id="path16"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="6.2859998"
+ y="17.881001"
+ id="text18"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">group</text>
+ <text
+ x="6.7989998"
+ y="18.881001"
+ id="text20"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">SID</text>
+ <path
+ d="M 16.083,11.65 L 18.417,11.65 C 18.739,11.65 19,12.055 19,12.554 C 19,13.053 18.739,13.457 18.417,13.457 L 16.083,13.457 C 15.761,13.457 15.5,13.053 15.5,12.554 C 15.5,12.055 15.761,11.65 16.083,11.65"
+ id="path22"
+ style="fill:#dbd8d8;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 16.083,11.65 L 18.417,11.65 C 18.739,11.65 19,12.055 19,12.554 C 19,13.053 18.739,13.457 18.417,13.457 L 16.083,13.457 C 15.761,13.457 15.5,13.053 15.5,12.554 C 15.5,12.055 15.761,11.65 16.083,11.65"
+ id="path24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="16.525999"
+ y="12.731"
+ id="text26"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Fail</text>
+ <line
+ x1="13"
+ y1="12.5"
+ x2="14.65"
+ y2="12.5"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line28"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="14.65,12.9 15.45,12.5 14.65,12.1 14.65,12.9 "
+ id="polygon30"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="11,11 13,12.5 11,14 9,12.5 11,11 "
+ id="polygon32"
+ style="fill:#abfafe;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="11,11 13,12.5 11,14 9,12.5 11,11 "
+ id="polygon34"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="9.5229998"
+ y="12.75"
+ id="text36"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="11.531"
+ y="15"
+ id="text38"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <line
+ x1="10.989"
+ y1="9.3999996"
+ x2="10.994"
+ y2="10.15"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line40"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="10.594,10.153 11,10.95 11.394,10.147 10.594,10.153 "
+ id="polygon42"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <text
+ x="13.104"
+ y="12.25"
+ id="text44"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="7.5"
+ y1="15.25"
+ x2="7.5"
+ y2="15.95"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line46"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="7.1,15.95 7.5,16.75 7.9,15.95 7.1,15.95 "
+ id="polygon48"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.5,7 6.5,8.5 4.5,10 2.5,8.5 4.5,7 "
+ id="polygon50"
+ style="fill:#c5effb;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.5,7 6.5,8.5 4.5,10 2.5,8.5 4.5,7 "
+ id="polygon52"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.0220001"
+ y="8.75"
+ id="text54"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="5.0310001"
+ y="10.75"
+ id="text56"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <line
+ x1="4.5"
+ y1="2.029"
+ x2="4.5009999"
+ y2="2.55"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line58"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.101,2.551 4.503,3.35 4.901,2.549 4.101,2.551 "
+ id="polygon60"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <text
+ x="6.6040001"
+ y="8.25"
+ id="text62"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="6.5"
+ y1="8.5"
+ x2="8.1499996"
+ y2="8.5"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line64"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="8.15,8.9 8.95,8.5 8.15,8.1 8.15,8.9 "
+ id="polygon66"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="8.7440004"
+ y="7.4000001"
+ id="rect68"
+ style="fill:#d5d5d5;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="8.7440004"
+ y="7.4000001"
+ id="rect70"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="9.2939997"
+ y="8.6280003"
+ id="text72"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Winbind</text>
+ <line
+ x1="13.25"
+ y1="8.75"
+ x2="15.25"
+ y2="9.5"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line74"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="13.25"
+ y1="8.25"
+ x2="15.25"
+ y2="7.5"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line76"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="8"
+ height="2"
+ x="15.5"
+ y="7.5"
+ id="rect78"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="8"
+ height="2"
+ x="15.5"
+ y="7.5"
+ id="rect80"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="15.316"
+ y="8.25"
+ id="text82"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">winbindd_idmap.tdb</text>
+ <text
+ x="17.761999"
+ y="9.25"
+ id="text84"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <line
+ x1="23.5"
+ y1="8.5"
+ x2="15.5"
+ y2="8.5"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line86"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="9.8870001"
+ height="2.0999999"
+ x="-0.44"
+ y="3.4000001"
+ id="rect88"
+ style="fill:#dcdcdc;stroke:none;stroke-width:0" />
+ <rect
+ width="9.8870001"
+ height="2.0999999"
+ x="-0.44"
+ y="3.4000001"
+ id="rect90"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="0.11"
+ y="4.6269999"
+ id="text92"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">groupmap_idmap.tdb</text>
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="4.500,10.000 4.500,15.250 11.000,15.250 11.000,14.000 "
+ id="polyline94"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap-groups.svg b/docs-xml/Samba3-HOWTO/images/idmap-groups.svg
new file mode 100644
index 0000000000..58b1dc6be6
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap-groups.svg
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="9.6999998cm"
+ height="17.848cm"
+ viewBox="2.95 0.95 12.65 18.798"
+ id="svg2">
+ <defs
+ id="defs49" />
+ <text
+ x="3.7"
+ y="1.9"
+ id="text4"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Grou</text>
+ <text
+ x="3.7"
+ y="2"
+ id="text6"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">group</text>
+ <rect
+ width="9.6000004"
+ height="3"
+ x="3"
+ y="1"
+ id="rect8"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="9.6000004"
+ height="3"
+ x="3"
+ y="1"
+ id="rect10"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="9.5500002"
+ height="3.3"
+ x="3"
+ y="15.4"
+ id="rect12"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="9.5500002"
+ height="3.3"
+ x="3"
+ y="15.4"
+ id="rect14"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="9.5500002"
+ height="3.5"
+ x="3"
+ y="8"
+ id="rect16"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="9.5500002"
+ height="3.5"
+ x="3"
+ y="8"
+ id="rect18"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.75"
+ y="2.05"
+ id="text20"
+ style="font-size:0.80000001px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:sans">group_mapping tdb</text>
+ <text
+ x="3.6500001"
+ y="3.5"
+ id="text22"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">contains samba groups</text>
+ <text
+ x="5.5999999"
+ y="9.0620003"
+ id="text24"
+ style="font-size:0.80000001px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:sans">idmap gid</text>
+ <text
+ x="4.25"
+ y="10.25"
+ id="text26"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">maps UNIX groups to</text>
+ <text
+ x="4.25"
+ y="11.05"
+ id="text28"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">samba groups</text>
+ <text
+ x="5.0500002"
+ y="16.5"
+ id="text30"
+ style="font-size:0.80000001px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:sans">UNIX groups</text>
+ <text
+ x="4.8499999"
+ y="17.6"
+ id="text32"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">/etc/group or other</text>
+ <text
+ x="4.8499999"
+ y="18.4"
+ id="text34"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">NSS backend</text>
+ <polygon
+ points="7.183,6.963 7.183,5.01 6.694,5.01 7.671,4.034 8.647,5.01 8.159,5.01 8.159,6.963 8.647,6.963 7.671,7.939 6.694,6.963 7.183,6.963 "
+ id="polygon36"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="7.183,6.963 7.183,5.01 6.694,5.01 7.671,4.034 8.647,5.01 8.159,5.01 8.159,6.963 8.647,6.963 7.671,7.939 6.694,6.963 7.183,6.963 "
+ id="polygon38"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="7.183,6.963 7.183,5.01 6.694,5.01 7.671,4.034 8.647,5.01 8.159,5.01 8.159,6.963 8.647,6.963 7.671,7.939 6.694,6.963 7.183,6.963 "
+ id="polygon40"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="7.196,14.421 7.196,12.521 6.721,12.521 7.671,11.571 8.621,12.521 8.146,12.521 8.146,14.421 8.621,14.421 7.671,15.371 6.721,14.421 7.196,14.421 "
+ id="polygon42"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="7.196,14.421 7.196,12.521 6.721,12.521 7.671,11.571 8.621,12.521 8.146,12.521 8.146,14.421 8.621,14.421 7.671,15.371 6.721,14.421 7.196,14.421 "
+ id="polygon44"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="7.196,14.421 7.196,12.521 6.721,12.521 7.671,11.571 8.621,12.521 8.146,12.521 8.146,14.421 8.621,14.421 7.671,15.371 6.721,14.421 7.196,14.421 "
+ id="polygon46"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap-sid2gid.svg b/docs-xml/Samba3-HOWTO/images/idmap-sid2gid.svg
new file mode 100644
index 0000000000..95944e9851
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap-sid2gid.svg
@@ -0,0 +1,277 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="23.674999cm"
+ height="19.329cm"
+ viewBox="-0.492 0 23.184 19.329"
+ id="svg2">
+ <defs
+ id="defs97" />
+ <path
+ d="M 6.333,17.471 L 8.667,17.471 C 8.989,17.471 9.25,17.876 9.25,18.375 C 9.25,18.874 8.989,19.279 8.667,19.279 L 6.333,19.279 C 6.011,19.279 5.75,18.874 5.75,18.375 C 5.75,17.876 6.011,17.471 6.333,17.471"
+ id="path4"
+ style="fill:#dcdcdc;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 6.333,17.471 L 8.667,17.471 C 8.989,17.471 9.25,17.876 9.25,18.375 C 9.25,18.874 8.989,19.279 8.667,19.279 L 6.333,19.279 C 6.011,19.279 5.75,18.874 5.75,18.375 C 5.75,17.876 6.011,17.471 6.333,17.471"
+ id="path6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="6.7610002"
+ y="18.552"
+ id="text8"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">GID</text>
+ <line
+ x1="4.5019999"
+ y1="6"
+ x2="4.5009999"
+ y2="6.6500001"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line10"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.101,6.649 4.5,7.45 4.901,6.651 4.101,6.649 "
+ id="polygon12"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 2.883,0.05 L 6.117,0.05 C 6.564,0.05 6.926,0.678 6.926,1.454 C 6.926,2.229 6.564,2.857 6.117,2.857 L 2.883,2.857 C 2.436,2.857 2.074,2.229 2.074,1.454 C 2.074,0.678 2.436,0.05 2.883,0.05"
+ id="path14"
+ style="fill:#cfcfcf;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 2.883,0.05 L 6.117,0.05 C 6.564,0.05 6.926,0.678 6.926,1.454 C 6.926,2.229 6.564,2.857 6.117,2.857 L 2.883,2.857 C 2.436,2.857 2.074,2.229 2.074,1.454 C 2.074,0.678 2.436,0.05 2.883,0.05"
+ id="path16"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.286"
+ y="1.131"
+ id="text18"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">group</text>
+ <text
+ x="3.799"
+ y="2.131"
+ id="text20"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">SID</text>
+ <path
+ d="M 15.181,12.15 L 17.435,12.15 C 17.746,12.15 17.999,12.555 17.999,13.054 C 17.999,13.553 17.746,13.957 17.435,13.957 L 15.181,13.957 C 14.869,13.957 14.617,13.553 14.617,13.054 C 14.617,12.555 14.869,12.15 15.181,12.15"
+ id="path22"
+ style="fill:#dcdcdc;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 15.181,12.15 L 17.435,12.15 C 17.746,12.15 17.999,12.555 17.999,13.054 C 17.999,13.553 17.746,13.957 17.435,13.957 L 15.181,13.957 C 14.869,13.957 14.617,13.553 14.617,13.054 C 14.617,12.555 14.869,12.15 15.181,12.15"
+ id="path24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="15.584"
+ y="13.231"
+ id="text26"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Fail</text>
+ <line
+ x1="12.5"
+ y1="13"
+ x2="13.9"
+ y2="13"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line28"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="13.9,13.4 14.7,13 13.9,12.6 13.9,13.4 "
+ id="polygon30"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="10.5,11.5 12.5,13 10.5,14.5 8.5,13 10.5,11.5 "
+ id="polygon32"
+ style="fill:#bef2ff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="10.5,11.5 12.5,13 10.5,14.5 8.5,13 10.5,11.5 "
+ id="polygon34"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="9.0229998"
+ y="13.25"
+ id="text36"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="11.031"
+ y="15.5"
+ id="text38"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <line
+ x1="10.489"
+ y1="10"
+ x2="10.494"
+ y2="10.65"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line40"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="10.094,10.653 10.5,11.45 10.894,10.647 10.094,10.653 "
+ id="polygon42"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <text
+ x="12.604"
+ y="12.75"
+ id="text44"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="7.5"
+ y1="15.75"
+ x2="7.5"
+ y2="16.65"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line46"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="7.1,16.65 7.5,17.45 7.9,16.65 7.1,16.65 "
+ id="polygon48"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.5,7.5 6.5,9 4.5,10.5 2.5,9 4.5,7.5 "
+ id="polygon50"
+ style="fill:#acedff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.5,7.5 6.5,9 4.5,10.5 2.5,9 4.5,7.5 "
+ id="polygon52"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="3.0220001"
+ y="9.25"
+ id="text54"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="5.0310001"
+ y="11.25"
+ id="text56"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <line
+ x1="4.5"
+ y1="2.8570001"
+ x2="4.5"
+ y2="3.05"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line58"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.1,3.051 4.502,3.85 4.9,3.049 4.1,3.051 "
+ id="polygon60"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <text
+ x="6.6040001"
+ y="8.75"
+ id="text62"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="6.5"
+ y1="9"
+ x2="7.6500001"
+ y2="9"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line64"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="7.65,9.4 8.45,9 7.65,8.6 7.65,9.4 "
+ id="polygon66"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="8.2440004"
+ y="7.9000001"
+ id="rect68"
+ style="fill:#dcdcdc;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="8.2440004"
+ y="7.9000001"
+ id="rect70"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="8.7939997"
+ y="9.1280003"
+ id="text72"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Winbind</text>
+ <line
+ x1="12.75"
+ y1="9.25"
+ x2="14.75"
+ y2="10"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line74"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="12.75"
+ y1="8.75"
+ x2="14.75"
+ y2="8"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line76"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="8"
+ height="2"
+ x="15"
+ y="8"
+ id="rect78"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="8"
+ height="2"
+ x="15"
+ y="8"
+ id="rect80"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="14.816"
+ y="8.75"
+ id="text82"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">winbindd_idmap.tdb</text>
+ <text
+ x="17.261999"
+ y="9.75"
+ id="text84"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <line
+ x1="23"
+ y1="9"
+ x2="15"
+ y2="9"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line86"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="9.8870001"
+ height="2.0999999"
+ x="-0.442"
+ y="3.9000001"
+ id="rect88"
+ style="fill:#d3d3d3;stroke:none;stroke-width:0" />
+ <rect
+ width="9.8870001"
+ height="2.0999999"
+ x="-0.442"
+ y="3.9000001"
+ id="rect90"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="0.108"
+ y="5.1269999"
+ id="text92"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">groupmap_idmap.tdb</text>
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="4.500,10.500 4.500,15.500 10.500,15.500 10.500,14.500 "
+ id="polyline94"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap-sid2uid.svg b/docs-xml/Samba3-HOWTO/images/idmap-sid2uid.svg
new file mode 100644
index 0000000000..84faf099f6
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap-sid2uid.svg
@@ -0,0 +1,365 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="33.234001cm"
+ height="20.391001cm"
+ viewBox="0.066 0.921 33.3 21.312"
+ id="svg2">
+ <defs
+ id="defs121" />
+ <line
+ x1="12.5"
+ y1="2.779"
+ x2="12.5"
+ y2="4.9000001"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line4"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="12.1,4.9 12.5,5.7 12.9,4.9 12.1,4.9 "
+ id="polygon6"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 11.333,0.971 L 13.667,0.971 C 13.989,0.971 14.25,1.376 14.25,1.875 C 14.25,2.374 13.989,2.779 13.667,2.779 L 11.333,2.779 C 11.011,2.779 10.75,2.374 10.75,1.875 C 10.75,1.376 11.011,0.971 11.333,0.971"
+ id="path8"
+ style="fill:#d9d9d9;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 11.333,0.971 L 13.667,0.971 C 13.989,0.971 14.25,1.376 14.25,1.875 C 14.25,2.374 13.989,2.779 13.667,2.779 L 11.333,2.779 C 11.011,2.779 10.75,2.374 10.75,1.875 C 10.75,1.376 11.011,0.971 11.333,0.971"
+ id="path10"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="11.799"
+ y="2.053"
+ id="text12"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">SID</text>
+ <polygon
+ points="12.5,5.75 15.5,7.75 12.5,9.75 9.5,7.75 12.5,5.75 "
+ id="polygon14"
+ style="fill:#aff3f6;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="12.5,5.75 15.5,7.75 12.5,9.75 9.5,7.75 12.5,5.75 "
+ id="polygon16"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="9.8459997"
+ y="8"
+ id="text18"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Our Domain?</text>
+ <line
+ x1="15.5"
+ y1="7.75"
+ x2="17.65"
+ y2="7.75"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line20"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="17.65,8.15 18.45,7.75 17.65,7.35 17.65,8.15 "
+ id="polygon22"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <text
+ x="16.031"
+ y="7.5"
+ id="text24"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <line
+ x1="12.5"
+ y1="9.75"
+ x2="12.493"
+ y2="11.55"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line26"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="12.093,11.548 12.49,12.35 12.893,11.552 12.093,11.548 "
+ id="polygon28"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <text
+ x="12.854"
+ y="10.75"
+ id="text30"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="16.5"
+ y1="15.25"
+ x2="16.5"
+ y2="17.4"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line32"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="16.1,17.4 16.5,18.2 16.9,17.4 16.1,17.4 "
+ id="polygon34"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 21.833,18.9 L 24.167,18.9 C 24.489,18.9 24.75,19.305 24.75,19.804 C 24.75,20.303 24.489,20.707 24.167,20.707 L 21.833,20.707 C 21.511,20.707 21.25,20.303 21.25,19.804 C 21.25,19.305 21.511,18.9 21.833,18.9"
+ id="path36"
+ style="fill:#d9d9d9;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 21.833,18.9 L 24.167,18.9 C 24.489,18.9 24.75,19.305 24.75,19.804 C 24.75,20.303 24.489,20.707 24.167,20.707 L 21.833,20.707 C 21.511,20.707 21.25,20.303 21.25,19.804 C 21.25,19.305 21.511,18.9 21.833,18.9"
+ id="path38"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="22.264999"
+ y="19.981001"
+ id="text40"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">UID</text>
+ <polygon
+ points="16.5,18.25 18.5,19.75 16.5,21.25 14.5,19.75 16.5,18.25 "
+ id="polygon42"
+ style="fill:#a1fdfb;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="16.5,18.25 18.5,19.75 16.5,21.25 14.5,19.75 16.5,18.25 "
+ id="polygon44"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="15.023"
+ y="20"
+ id="text46"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="18.781"
+ y="19.5"
+ id="text48"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <text
+ x="13.354"
+ y="19.5"
+ id="text50"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="18.5"
+ y1="19.75"
+ x2="20.4"
+ y2="19.75"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line52"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="20.4,20.15 21.2,19.75 20.4,19.35 20.4,20.15 "
+ id="polygon54"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <line
+ x1="14.5"
+ y1="19.75"
+ x2="12.6"
+ y2="19.75"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line56"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="12.6,19.35 11.8,19.75 12.6,20.15 12.6,19.35 "
+ id="polygon58"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 8.833,18.9 L 11.167,18.9 C 11.489,18.9 11.75,19.305 11.75,19.804 C 11.75,20.303 11.489,20.707 11.167,20.707 L 8.833,20.707 C 8.511,20.707 8.25,20.303 8.25,19.804 C 8.25,19.305 8.511,18.9 8.833,18.9"
+ id="path60"
+ style="fill:#d7d7d7;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 8.833,18.9 L 11.167,18.9 C 11.489,18.9 11.75,19.305 11.75,19.804 C 11.75,20.303 11.489,20.707 11.167,20.707 L 8.833,20.707 C 8.511,20.707 8.25,20.303 8.25,19.804 C 8.25,19.305 8.511,18.9 8.833,18.9"
+ id="path62"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="9.276"
+ y="19.981001"
+ id="text64"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Fail</text>
+ <rect
+ width="4.1399999"
+ height="2.0999999"
+ x="18.419001"
+ y="6.6500001"
+ id="rect66"
+ style="fill:#d9d6d6;stroke:none;stroke-width:0" />
+ <rect
+ width="4.1399999"
+ height="2.0999999"
+ x="18.419001"
+ y="6.6500001"
+ id="rect68"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="18.969"
+ y="7.8779998"
+ id="text70"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">PassDB</text>
+ <line
+ x1="22.75"
+ y1="6.5"
+ x2="25"
+ y2="5.25"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line72"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="22.75"
+ y1="8.75"
+ x2="25"
+ y2="10"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line74"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="8"
+ height="5.25"
+ x="25.25"
+ y="5"
+ id="rect76"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="8"
+ height="5.25"
+ x="25.25"
+ y="5"
+ id="rect78"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="28.089001"
+ y="5.75"
+ id="text80"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">guest</text>
+ <text
+ x="26.85"
+ y="6.75"
+ id="text82"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">smbpasswd</text>
+ <text
+ x="27.709"
+ y="7.75"
+ id="text84"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">tdbsam</text>
+ <text
+ x="27.511999"
+ y="8.75"
+ id="text86"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <text
+ x="25.799999"
+ y="9.75"
+ id="text88"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam_compat</text>
+ <line
+ x1="25.25"
+ y1="6"
+ x2="33.25"
+ y2="6"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line90"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="25.25"
+ y1="7"
+ x2="33.25"
+ y2="7"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line92"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="25.25"
+ y1="8"
+ x2="33.25"
+ y2="8"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line94"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="25.25"
+ y1="9"
+ x2="33.25"
+ y2="9"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line96"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="10.244"
+ y="12.4"
+ id="rect98"
+ style="fill:#d7d7d7;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="10.244"
+ y="12.4"
+ id="rect100"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="10.794"
+ y="13.628"
+ id="text102"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Winbind</text>
+ <rect
+ width="7.5"
+ height="2.75"
+ x="0.5"
+ y="12"
+ id="rect104"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="7.5"
+ height="2.75"
+ x="0.5"
+ y="12"
+ id="rect106"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="0.066"
+ y="13"
+ id="text108"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">winbindd_idmap.tdb</text>
+ <text
+ x="2.513"
+ y="14.25"
+ id="text110"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <line
+ x1="8"
+ y1="13.375"
+ x2="0.5"
+ y2="13.375"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line112"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="8.25"
+ y1="12"
+ x2="10.25"
+ y2="12.75"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line114"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="8.25"
+ y1="14.75"
+ x2="10.25"
+ y2="14"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line116"
+ style="stroke:#000000;stroke-width:0.05" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="12.489,14.500 12.489,15.500 20.489,15.500 20.489,8.750 "
+ id="polyline118"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap-store-gid2sid.svg b/docs-xml/Samba3-HOWTO/images/idmap-store-gid2sid.svg
new file mode 100644
index 0000000000..bf15504974
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap-store-gid2sid.svg
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="26.294001cm"
+ height="2.4000001cm"
+ viewBox="0.45 1.35 26.744 3.75"
+ id="svg2">
+ <defs
+ id="defs41" />
+ <path
+ d="M 13.02,1.721 L 15.23,1.721 C 15.535,1.721 15.782,2.126 15.782,2.625 C 15.782,3.124 15.535,3.529 15.23,3.529 L 13.02,3.529 C 12.715,3.529 12.468,3.124 12.468,2.625 C 12.468,2.126 12.715,1.721 13.02,1.721"
+ id="path4"
+ style="fill:#d7d7d7;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 13.02,1.721 L 15.23,1.721 C 15.535,1.721 15.782,2.126 15.782,2.625 C 15.782,3.124 15.535,3.529 15.23,3.529 L 13.02,3.529 C 12.715,3.529 12.468,3.124 12.468,2.625 C 12.468,2.126 12.715,1.721 13.02,1.721"
+ id="path6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="13.424"
+ y="2.803"
+ id="text8"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">SID</text>
+ <path
+ d="M 1.083,1.65 L 3.417,1.65 C 3.739,1.65 4,2.055 4,2.554 C 4,3.053 3.739,3.457 3.417,3.457 L 1.083,3.457 C 0.761,3.457 0.5,3.053 0.5,2.554 C 0.5,2.055 0.761,1.65 1.083,1.65"
+ id="path10"
+ style="fill:#d7d7d7;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 1.083,1.65 L 3.417,1.65 C 3.739,1.65 4,2.055 4,2.554 C 4,3.053 3.739,3.457 3.417,3.457 L 1.083,3.457 C 0.761,3.457 0.5,3.053 0.5,2.554 C 0.5,2.055 0.761,1.65 1.083,1.65"
+ id="path12"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="1.511"
+ y="2.7309999"
+ id="text14"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">GID</text>
+ <line
+ x1="16"
+ y1="3"
+ x2="18"
+ y2="3.5"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line16"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="16"
+ y1="2"
+ x2="18"
+ y2="1.5"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line18"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="4"
+ y1="2.5539999"
+ x2="11.65"
+ y2="2.618"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line20"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="11.647,3.018 12.45,2.625 11.653,2.218 11.647,3.018 "
+ id="polygon22"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <rect
+ width="6.9219999"
+ height="2.0999999"
+ x="4.572"
+ y="1.4"
+ id="rect24"
+ style="fill:#d7d7d7;stroke:none;stroke-width:0" />
+ <rect
+ width="6.9219999"
+ height="2.0999999"
+ x="4.572"
+ y="1.4"
+ id="rect26"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="5.1220002"
+ y="2.6270001"
+ id="text28"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">net groupmap</text>
+ <rect
+ width="8.1999998"
+ height="2.2"
+ x="18.25"
+ y="1.5"
+ id="rect30"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="8.1999998"
+ height="2.2"
+ x="18.25"
+ y="1.5"
+ id="rect32"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="20.511999"
+ y="2.25"
+ id="text34"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <text
+ x="17.955999"
+ y="3.2"
+ id="text36"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">groupmap_idmap.tdb</text>
+ <line
+ x1="26.549999"
+ y1="2.45"
+ x2="18.35"
+ y2="2.45"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line38"
+ style="stroke:#000000;stroke-width:0.05" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap-uid2sid.svg b/docs-xml/Samba3-HOWTO/images/idmap-uid2sid.svg
new file mode 100644
index 0000000000..13aca9cf70
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap-uid2sid.svg
@@ -0,0 +1,365 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="21.431cm"
+ height="23.086cm"
+ viewBox="10.369 0.921 31.8 24.007"
+ id="svg2">
+ <defs
+ id="defs121" />
+ <line
+ x1="19.25"
+ y1="12.75"
+ x2="19.25"
+ y2="14.15"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line4"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="18.85,14.15 19.25,14.95 19.65,14.15 18.85,14.15 "
+ id="polygon6"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <line
+ x1="12.5"
+ y1="2.779"
+ x2="12.5"
+ y2="4.6500001"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line8"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="12.1,4.65 12.5,5.45 12.9,4.65 12.1,4.65 "
+ id="polygon10"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 11.333,0.971 L 13.667,0.971 C 13.989,0.971 14.25,1.376 14.25,1.875 C 14.25,2.374 13.989,2.779 13.667,2.779 L 11.333,2.779 C 11.011,2.779 10.75,2.374 10.75,1.875 C 10.75,1.376 11.011,0.971 11.333,0.971"
+ id="path12"
+ style="fill:#dcdcdc;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 11.333,0.971 L 13.667,0.971 C 13.989,0.971 14.25,1.376 14.25,1.875 C 14.25,2.374 13.989,2.779 13.667,2.779 L 11.333,2.779 C 11.011,2.779 10.75,2.374 10.75,1.875 C 10.75,1.376 11.011,0.971 11.333,0.971"
+ id="path14"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="11.765"
+ y="2.053"
+ id="text16"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">UID</text>
+ <line
+ x1="12.489"
+ y1="7.5"
+ x2="12.497"
+ y2="9.6499996"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line18"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="12.097,9.651 12.5,10.45 12.897,9.649 12.097,9.651 "
+ id="polygon20"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 14.833,22.15 L 17.167,22.15 C 17.489,22.15 17.75,22.555 17.75,23.054 C 17.75,23.553 17.489,23.957 17.167,23.957 L 14.833,23.957 C 14.511,23.957 14.25,23.553 14.25,23.054 C 14.25,22.555 14.511,22.15 14.833,22.15"
+ id="path22"
+ style="fill:#d5d5d5;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 14.833,22.15 L 17.167,22.15 C 17.489,22.15 17.75,22.555 17.75,23.054 C 17.75,23.553 17.489,23.957 17.167,23.957 L 14.833,23.957 C 14.511,23.957 14.25,23.553 14.25,23.054 C 14.25,22.555 14.511,22.15 14.833,22.15"
+ id="path24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="15.299"
+ y="23.231001"
+ id="text26"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">SID</text>
+ <polygon
+ points="12.5,10.5 14.5,12 12.5,13.5 10.5,12 12.5,10.5 "
+ id="polygon28"
+ style="fill:#b8f5fc;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="12.5,10.5 14.5,12 12.5,13.5 10.5,12 12.5,10.5 "
+ id="polygon30"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="11.023"
+ y="12.25"
+ id="text32"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="13.031"
+ y="14.5"
+ id="text34"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <text
+ x="14.854"
+ y="11.75"
+ id="text36"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="14.5"
+ y1="12"
+ x2="16.4"
+ y2="12"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line38"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="16.4,12.4 17.2,12 16.4,11.6 16.4,12.4 "
+ id="polygon40"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <line
+ x1="16"
+ y1="19.25"
+ x2="16"
+ y2="21.4"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line42"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="15.6,21.4 16,22.2 16.4,21.4 15.6,21.4 "
+ id="polygon44"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 24.083,15.65 L 26.417,15.65 C 26.739,15.65 27,16.055 27,16.554 C 27,17.053 26.739,17.457 26.417,17.457 L 24.083,17.457 C 23.761,17.457 23.5,17.053 23.5,16.554 C 23.5,16.055 23.761,15.65 24.083,15.65"
+ id="path46"
+ style="fill:#d9d9d9;stroke:none;stroke-width:0.1" />
+ <path
+ d="M 24.083,15.65 L 26.417,15.65 C 26.739,15.65 27,16.055 27,16.554 C 27,17.053 26.739,17.457 26.417,17.457 L 24.083,17.457 C 23.761,17.457 23.5,17.053 23.5,16.554 C 23.5,16.055 23.761,15.65 24.083,15.65"
+ id="path48"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="24.525999"
+ y="16.731001"
+ id="text50"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Fail</text>
+ <rect
+ width="4.1399999"
+ height="2.0999999"
+ x="10.419"
+ y="5.4000001"
+ id="rect52"
+ style="fill:#dcd7d7;stroke:none;stroke-width:0" />
+ <rect
+ width="4.1399999"
+ height="2.0999999"
+ x="10.419"
+ y="5.4000001"
+ id="rect54"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="10.969"
+ y="6.6279998"
+ id="text56"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">PassDB</text>
+ <line
+ x1="14.75"
+ y1="5.25"
+ x2="17"
+ y2="4"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line58"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="14.75"
+ y1="7.5"
+ x2="17"
+ y2="8.75"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line60"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="8"
+ height="5.25"
+ x="17.25"
+ y="3.75"
+ id="rect62"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="8"
+ height="5.25"
+ x="17.25"
+ y="3.75"
+ id="rect64"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="20.089001"
+ y="4.5"
+ id="text66"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">guest</text>
+ <text
+ x="18.85"
+ y="5.5"
+ id="text68"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">smbpasswd</text>
+ <text
+ x="19.709"
+ y="6.5"
+ id="text70"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">tdbsam</text>
+ <text
+ x="19.511999"
+ y="7.5"
+ id="text72"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <text
+ x="17.799999"
+ y="8.5"
+ id="text74"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam_compat</text>
+ <line
+ x1="17.25"
+ y1="4.75"
+ x2="25.25"
+ y2="4.75"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line76"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="17.25"
+ y1="5.75"
+ x2="25.25"
+ y2="5.75"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line78"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="17.25"
+ y1="6.75"
+ x2="25.25"
+ y2="6.75"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line80"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="17.25"
+ y1="7.75"
+ x2="25.25"
+ y2="7.75"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line82"
+ style="stroke:#000000;stroke-width:0.05" />
+ <polyline
+ fill="none"
+ stroke="#000000"
+ stroke-width="0.100"
+ points="12.500,13.500 12.500,19.000 19.250,19.000 19.250,18.000 "
+ id="polyline84"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="16.993999"
+ y="10.9"
+ id="rect86"
+ style="fill:#d7d7d7;stroke:none;stroke-width:0" />
+ <rect
+ width="4.4899998"
+ height="2.0999999"
+ x="16.993999"
+ y="10.9"
+ id="rect88"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="17.544001"
+ y="12.128"
+ id="text90"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Winbind</text>
+ <line
+ x1="21.5"
+ y1="12.5"
+ x2="23.5"
+ y2="13.25"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line92"
+ style="stroke:#000000;stroke-width:0.05" />
+ <line
+ x1="21.5"
+ y1="11.25"
+ x2="23.5"
+ y2="10.5"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line94"
+ style="stroke:#000000;stroke-width:0.05" />
+ <rect
+ width="7.6669998"
+ height="2.75"
+ x="23.75"
+ y="10.5"
+ id="rect96"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="7.6669998"
+ height="2.75"
+ x="23.75"
+ y="10.5"
+ id="rect98"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="23.433001"
+ y="11.507"
+ id="text100"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">winbindd_idmap.tdb</text>
+ <text
+ x="25.761999"
+ y="12.75"
+ id="text102"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">ldapsam</text>
+ <line
+ x1="31.417"
+ y1="11.875"
+ x2="23.75"
+ y2="11.875"
+ stroke="#000000"
+ stroke-width="0.050"
+ id="line104"
+ style="stroke:#000000;stroke-width:0.05" />
+ <polygon
+ points="19.25,15 21.25,16.5 19.25,18 17.25,16.5 19.25,15 "
+ id="polygon106"
+ style="fill:#bcf9ff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="19.25,15 21.25,16.5 19.25,18 17.25,16.5 19.25,15 "
+ id="polygon108"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="17.773001"
+ y="16.75"
+ id="text110"
+ style="font-size:1px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:luxi sans">Found?</text>
+ <text
+ x="19.781"
+ y="19"
+ id="text112"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">Yes</text>
+ <text
+ x="21.604"
+ y="16.25"
+ id="text114"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:luxi sans">No</text>
+ <line
+ x1="21.25"
+ y1="16.5"
+ x2="22.65"
+ y2="16.5"
+ stroke="#000000"
+ stroke-width="0.100"
+ id="line116"
+ style="stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="22.65,16.9 23.45,16.5 22.65,16.1 22.65,16.9 "
+ id="polygon118"
+ style="fill:#000000;stroke:none;stroke-width:0.1" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap.svg b/docs-xml/Samba3-HOWTO/images/idmap.svg
new file mode 100644
index 0000000000..db2d883551
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap.svg
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="8.1999998cm"
+ height="17.198cm"
+ viewBox="1.45 1.4 9.65 18.598"
+ id="svg2">
+ <defs
+ id="defs45" />
+ <rect
+ width="7.3000002"
+ height="2.5999999"
+ x="1.5"
+ y="1.7"
+ id="rect4"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="7.3000002"
+ height="2.5999999"
+ x="1.5"
+ y="1.7"
+ id="rect6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="5.9000001"
+ height="2.7"
+ x="2.3"
+ y="8.5"
+ id="rect8"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="5.9000001"
+ height="2.7"
+ x="2.3"
+ y="8.5"
+ id="rect10"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="2.7"
+ y="2.8"
+ id="text12"
+ style="font-size:0.80000001px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:sans">passdb backend</text>
+ <text
+ x="1.7"
+ y="3.7"
+ id="text14"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">contains samba users</text>
+ <text
+ x="4.5"
+ y="9.3999996"
+ id="text16"
+ style="font-size:0.80000001px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:sans">idmap</text>
+ <text
+ x="3.3"
+ y="10.2"
+ id="text18"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">maps unix to</text>
+ <text
+ x="3.3"
+ y="11"
+ id="text20"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">samba users</text>
+ <rect
+ width="7.6999998"
+ height="3"
+ x="1.9"
+ y="15.5"
+ id="rect22"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="7.6999998"
+ height="3"
+ x="1.9"
+ y="15.5"
+ id="rect24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.675,7.35 4.675,5.45 4.2,5.45 5.15,4.5 6.1,5.45 5.625,5.45 5.625,7.35 6.1,7.35 5.15,8.3 4.2,7.35 4.675,7.35 "
+ id="polygon26"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.675,7.35 4.675,5.45 4.2,5.45 5.15,4.5 6.1,5.45 5.625,5.45 5.625,7.35 6.1,7.35 5.15,8.3 4.2,7.35 4.675,7.35 "
+ id="polygon28"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.675,7.35 4.675,5.45 4.2,5.45 5.15,4.5 6.1,5.45 5.625,5.45 5.625,7.35 6.1,7.35 5.15,8.3 4.2,7.35 4.675,7.35 "
+ id="polygon30"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="4.763,14.175 4.763,12.325 4.3,12.325 5.225,11.4 6.15,12.325 5.688,12.325 5.688,14.175 6.15,14.175 5.225,15.1 4.3,14.175 4.763,14.175 "
+ id="polygon32"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="4.763,14.175 4.763,12.325 4.3,12.325 5.225,11.4 6.15,12.325 5.688,12.325 5.688,14.175 6.15,14.175 5.225,15.1 4.3,14.175 4.763,14.175 "
+ id="polygon34"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="4.763,14.175 4.763,12.325 4.3,12.325 5.225,11.4 6.15,12.325 5.688,12.325 5.688,14.175 6.15,14.175 5.225,15.1 4.3,14.175 4.763,14.175 "
+ id="polygon36"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="3.7"
+ y="16.299999"
+ id="text38"
+ style="font-size:0.80000001px;font-style:normal;font-weight:700;text-anchor:start;fill:#000000;font-family:sans">Unix users</text>
+ <text
+ x="2.4000001"
+ y="17.4"
+ id="text40"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">/etc/passwd</text>
+ <text
+ x="2.4000001"
+ y="18.200001"
+ id="text42"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">or other NSS backend</text>
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/idmap_winbind_no_loop.png b/docs-xml/Samba3-HOWTO/images/idmap_winbind_no_loop.png
new file mode 100644
index 0000000000..5393f6a192
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/idmap_winbind_no_loop.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/pdftoepsonusb.svg b/docs-xml/Samba3-HOWTO/images/pdftoepsonusb.svg
new file mode 100644
index 0000000000..d9434d7e26
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/pdftoepsonusb.svg
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="18.5cm"
+ height="4.9990001cm"
+ viewBox="5.85 2.808 24.35 7.807"
+ id="svg2">
+ <defs
+ id="defs59" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="5.9000001"
+ y="3"
+ id="rect4"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="5.9000001"
+ y="3"
+ id="rect6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="6.8039999"
+ y="3.8"
+ id="text8"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pdftops</text>
+ <rect
+ width="4.0999999"
+ height="1"
+ x="12.8"
+ y="3"
+ id="rect10"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="12.8"
+ y="3"
+ id="rect12"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="13.835"
+ y="3.8"
+ id="text14"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstops</text>
+ <rect
+ width="4.0999999"
+ height="1"
+ x="19.9"
+ y="3"
+ id="rect16"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.7609506"
+ height="0.99263805"
+ x="19.903681"
+ y="3.0036809"
+ id="rect18"
+ style="fill:none;stroke:#000000;stroke-width:0.10736195" />
+ <text
+ x="20.409"
+ y="3.8"
+ id="text20"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstoraster</text>
+ <polygon
+ points="10.5,3.225 11.5,3.225 11.5,2.9 12.5,3.55 11.5,4.2 11.5,3.875 10.5,3.875 10.5,3.225 "
+ id="polygon22"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="10.5,3.225 11.5,3.225 11.5,2.9 12.5,3.55 11.5,4.2 11.5,3.875 10.5,3.875 10.5,3.225 "
+ id="polygon24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="10.5,3.225 11.5,3.225 11.5,2.9 12.5,3.55 11.5,4.2 11.5,3.875 10.5,3.875 10.5,3.225 "
+ id="polygon26"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="17.4,3.225 18.4,3.225 18.4,2.9 19.4,3.55 18.4,4.2 18.4,3.875 17.4,3.875 17.4,3.225 "
+ id="polygon28"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="17.4,3.225 18.4,3.225 18.4,2.9 19.4,3.55 18.4,4.2 18.4,3.875 17.4,3.875 17.4,3.225 "
+ id="polygon30"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="17.4,3.225 18.4,3.225 18.4,2.9 19.4,3.55 18.4,4.2 18.4,3.875 17.4,3.875 17.4,3.225 "
+ id="polygon32"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="4.8000002"
+ height="1"
+ x="19.5"
+ y="6.3000002"
+ id="rect34"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="6.0224352"
+ height="0.9886266"
+ x="19.505686"
+ y="6.305687"
+ id="rect36"
+ style="fill:none;stroke:#000000;stroke-width:0.11137342" />
+ <text
+ x="19.865999"
+ y="7.0999999"
+ id="text38"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">rastertoepson</text>
+ <polygon
+ points="21.6,4.4 21.6,5.2 21.2,5.2 22,6 22.8,5.2 22.4,5.2 22.4,4.4 21.6,4.4 "
+ id="polygon40"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="21.6,4.4 21.6,5.2 21.2,5.2 22,6 22.8,5.2 22.4,5.2 22.4,4.4 21.6,4.4 "
+ id="polygon42"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="21.6,4.4 21.6,5.2 21.2,5.2 22,6 22.8,5.2 22.4,5.2 22.4,4.4 21.6,4.4 "
+ id="polygon44"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="12.5"
+ y="6.3000002"
+ id="rect46"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="12.5"
+ y="6.3000002"
+ id="rect48"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="13.979"
+ y="7.0999999"
+ id="text50"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">usb</text>
+ <polygon
+ points="18.886,6.422 18.043,6.422 18.043,6 17.2,6.843 18.043,7.686 18.043,7.265 18.886,7.265 18.886,6.422 "
+ id="polygon52"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="18.886,6.422 18.043,6.422 18.043,6 17.2,6.843 18.043,7.686 18.043,7.265 18.886,7.265 18.886,6.422 "
+ id="polygon54"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="18.886,6.422 18.043,6.422 18.043,6 17.2,6.843 18.043,7.686 18.043,7.265 18.886,7.265 18.886,6.422 "
+ id="polygon56"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/pdftosocket.svg b/docs-xml/Samba3-HOWTO/images/pdftosocket.svg
new file mode 100644
index 0000000000..1c9732c3d2
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/pdftosocket.svg
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="18.200001cm"
+ height="1.484cm"
+ viewBox="5.85 2.808 24.05 4.292"
+ id="svg2">
+ <defs
+ id="defs35" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="5.9000001"
+ y="3"
+ id="rect4"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="5.9000001"
+ y="3"
+ id="rect6"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="6.8039999"
+ y="3.8"
+ id="text8"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pdftops</text>
+ <rect
+ width="4.0999999"
+ height="1"
+ x="12.8"
+ y="3"
+ id="rect10"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="12.8"
+ y="3"
+ id="rect12"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="13.835"
+ y="3.8"
+ id="text14"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">pstops</text>
+ <rect
+ width="4.0999999"
+ height="1"
+ x="19.9"
+ y="3"
+ id="rect16"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="4.0999999"
+ height="1"
+ x="19.9"
+ y="3"
+ id="rect18"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <text
+ x="20.959"
+ y="3.8"
+ id="text20"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">socket</text>
+ <polygon
+ points="10.5,3.225 11.5,3.225 11.5,2.9 12.5,3.55 11.5,4.2 11.5,3.875 10.5,3.875 10.5,3.225 "
+ id="polygon22"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="10.5,3.225 11.5,3.225 11.5,2.9 12.5,3.55 11.5,4.2 11.5,3.875 10.5,3.875 10.5,3.225 "
+ id="polygon24"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="10.5,3.225 11.5,3.225 11.5,2.9 12.5,3.55 11.5,4.2 11.5,3.875 10.5,3.875 10.5,3.225 "
+ id="polygon26"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="17.4,3.225 18.4,3.225 18.4,2.9 19.4,3.55 18.4,4.2 18.4,3.875 17.4,3.875 17.4,3.225 "
+ id="polygon28"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="17.4,3.225 18.4,3.225 18.4,2.9 19.4,3.55 18.4,4.2 18.4,3.875 17.4,3.875 17.4,3.225 "
+ id="polygon30"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="17.4,3.225 18.4,3.225 18.4,2.9 19.4,3.55 18.4,4.2 18.4,3.875 17.4,3.875 17.4,3.225 "
+ id="polygon32"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/trusts1.svg b/docs-xml/Samba3-HOWTO/images/trusts1.svg
new file mode 100644
index 0000000000..9845d493cf
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/trusts1.svg
@@ -0,0 +1,792 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ version="1.0"
+ width="27.1cm"
+ height="8.493cm"
+ viewBox="6.95 1.958 34.05 10.45"
+ id="svg2">
+ <defs
+ id="defs273" />
+ <rect
+ width="1.367"
+ height="3.1900001"
+ x="8.8730001"
+ y="5"
+ id="rect4"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.367"
+ height="3.1900001"
+ x="8.8730001"
+ y="5"
+ id="rect6"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="9.0100002"
+ y="5.191"
+ id="rect8"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="9.0100002"
+ y="5.5560002"
+ id="rect10"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="9.0100002"
+ y="5.921"
+ id="rect12"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="9.0100002"
+ y="6.2849998"
+ id="rect14"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.68400002"
+ height="0.219"
+ x="9.0100002"
+ y="6.723"
+ id="rect16"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="10.036"
+ cy="6.7589998"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse18"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="10.036"
+ cy="6.7589998"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse20"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="10.036"
+ cy="6.9050002"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse22"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="10.036"
+ cy="6.9050002"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse24"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="9.7620001"
+ y="6.796"
+ id="rect26"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="9.7620001"
+ y="6.796"
+ id="rect28"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 9.101,7.233 L 9.101,8.031"
+ id="path30"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 9.329,7.233 L 9.329,8.031"
+ id="path32"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 9.557,7.233 L 9.557,8.031"
+ id="path34"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 9.785,7.233 L 9.785,8.031"
+ id="path36"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 10.013,7.233 L 10.013,8.031"
+ id="path38"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 10.241,7.233 L 10.241,8.031"
+ id="path40"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="8.6,8.464 8.873,7.917 8.873,8.19 10.241,8.19 10.241,7.917 10.605,8.464 8.6,8.464 "
+ id="polygon42"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="8.6,8.464 8.873,7.917 8.873,8.19 10.241,8.19 10.241,7.917 10.605,8.464 8.6,8.464 "
+ id="polygon44"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="12.25"
+ cy="6.6999998"
+ rx="5.25"
+ ry="3.5999999"
+ id="ellipse46"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.365"
+ height="3.1860001"
+ x="11.273"
+ y="5"
+ id="rect48"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.365"
+ height="3.1860001"
+ x="11.273"
+ y="5"
+ id="rect50"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="11.41"
+ y="5.191"
+ id="rect52"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="11.41"
+ y="5.5549998"
+ id="rect54"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="11.41"
+ y="5.9190001"
+ id="rect56"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="11.41"
+ y="6.2839999"
+ id="rect58"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.68300003"
+ height="0.21799999"
+ x="11.41"
+ y="6.7199998"
+ id="rect60"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="12.434"
+ cy="6.757"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse62"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="12.434"
+ cy="6.757"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse64"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="12.434"
+ cy="6.902"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse66"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="12.434"
+ cy="6.902"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse68"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="12.161"
+ y="6.7930002"
+ id="rect70"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="12.161"
+ y="6.7930002"
+ id="rect72"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 11.501,7.23 L 11.501,8.027"
+ id="path74"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 11.728,7.23 L 11.728,8.027"
+ id="path76"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 11.956,7.23 L 11.956,8.027"
+ id="path78"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 12.183,7.23 L 12.183,8.027"
+ id="path80"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 12.411,7.23 L 12.411,8.027"
+ id="path82"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 12.639,7.23 L 12.639,8.027"
+ id="path84"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="11,8.459 11.273,7.913 11.273,8.186 12.639,8.186 12.639,7.913 13.003,8.459 11,8.459 "
+ id="polygon86"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="11,8.459 11.273,7.913 11.273,8.186 12.639,8.186 12.639,7.913 13.003,8.459 11,8.459 "
+ id="polygon88"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.322"
+ height="3.086"
+ x="13.764"
+ y="5.0999999"
+ id="rect90"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.322"
+ height="3.086"
+ x="13.764"
+ y="5.0999999"
+ id="rect92"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="13.897"
+ y="5.2849998"
+ id="rect94"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="13.897"
+ y="5.638"
+ id="rect96"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="13.897"
+ y="5.9899998"
+ id="rect98"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="13.897"
+ y="6.3429999"
+ id="rect100"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.66100001"
+ height="0.212"
+ x="13.897"
+ y="6.7659998"
+ id="rect102"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="14.888"
+ cy="6.8010001"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse104"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="14.888"
+ cy="6.8010001"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse106"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="14.888"
+ cy="6.9419999"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse108"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="14.888"
+ cy="6.9419999"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse110"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.15899999"
+ height="0.141"
+ x="14.624"
+ y="6.8369999"
+ id="rect112"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.15899999"
+ height="0.141"
+ x="14.624"
+ y="6.8369999"
+ id="rect114"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 13.985,7.26 L 13.985,8.031"
+ id="path116"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 14.205,7.26 L 14.205,8.031"
+ id="path118"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 14.426,7.26 L 14.426,8.031"
+ id="path120"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 14.646,7.26 L 14.646,8.031"
+ id="path122"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 14.866,7.26 L 14.866,8.031"
+ id="path124"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 15.087,7.26 L 15.087,8.031"
+ id="path126"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="13.5,8.45 13.764,7.921 13.764,8.186 15.087,8.186 15.087,7.921 15.439,8.45 13.5,8.45 "
+ id="polygon128"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="13.5,8.45 13.764,7.921 13.764,8.186 15.087,8.186 15.087,7.921 15.439,8.45 13.5,8.45 "
+ id="polygon130"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="10.5"
+ y="2.5"
+ id="text132"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Domain A</text>
+ <text
+ x="27.299999"
+ y="2.8"
+ id="text134"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Domain B</text>
+ <polygon
+ points="18.5,6.5 20.6,6.5 20.6,6.2 22.7,6.8 20.6,7.4 20.6,7.1 18.5,7.1 18.5,6.5 "
+ id="polygon136"
+ style="fill:#ffffff;stroke:none;stroke-width:0.1" />
+ <polygon
+ points="18.5,6.5 20.6,6.5 20.6,6.2 22.7,6.8 20.6,7.4 20.6,7.1 18.5,7.1 18.5,6.5 "
+ id="polygon138"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <polygon
+ points="18.5,6.5 20.6,6.5 20.6,6.2 22.7,6.8 20.6,7.4 20.6,7.1 18.5,7.1 18.5,6.5 "
+ id="polygon140"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <text
+ x="19.299999"
+ y="5.9000001"
+ id="text142"
+ style="font-size:0.80000001px;font-style:normal;font-weight:400;text-anchor:start;fill:#000000;font-family:sans">Trusts</text>
+ <rect
+ width="1.367"
+ height="3.1900001"
+ x="25.372999"
+ y="5.0999999"
+ id="rect144"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.367"
+ height="3.1900001"
+ x="25.372999"
+ y="5.0999999"
+ id="rect146"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="25.51"
+ y="5.2909999"
+ id="rect148"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="25.51"
+ y="5.6560001"
+ id="rect150"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="25.51"
+ y="6.0209999"
+ id="rect152"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.094"
+ height="0.36500001"
+ x="25.51"
+ y="6.3850002"
+ id="rect154"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.68400002"
+ height="0.219"
+ x="25.51"
+ y="6.823"
+ id="rect156"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="26.535999"
+ cy="6.8590002"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse158"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="26.535999"
+ cy="6.8590002"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse160"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="26.535999"
+ cy="7.0050001"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse162"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="26.535999"
+ cy="7.0050001"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse164"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="26.261999"
+ y="6.8959999"
+ id="rect166"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="26.261999"
+ y="6.8959999"
+ id="rect168"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 25.601,7.333 L 25.601,8.131"
+ id="path170"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 25.829,7.333 L 25.829,8.131"
+ id="path172"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 26.057,7.333 L 26.057,8.131"
+ id="path174"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 26.285,7.333 L 26.285,8.131"
+ id="path176"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 26.513,7.333 L 26.513,8.131"
+ id="path178"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 26.741,7.333 L 26.741,8.131"
+ id="path180"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="25.1,8.564 25.373,8.017 25.373,8.29 26.741,8.29 26.741,8.017 27.105,8.564 25.1,8.564 "
+ id="polygon182"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="25.1,8.564 25.373,8.017 25.373,8.29 26.741,8.29 26.741,8.017 27.105,8.564 25.1,8.564 "
+ id="polygon184"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="28.75"
+ cy="6.8000002"
+ rx="5.25"
+ ry="3.5999999"
+ id="ellipse186"
+ style="fill:none;stroke:#000000;stroke-width:0.1" />
+ <rect
+ width="1.365"
+ height="3.1860001"
+ x="27.773001"
+ y="5.0999999"
+ id="rect188"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.365"
+ height="3.1860001"
+ x="27.773001"
+ y="5.0999999"
+ id="rect190"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="27.91"
+ y="5.2909999"
+ id="rect192"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="27.91"
+ y="5.6550002"
+ id="rect194"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="27.91"
+ y="6.0190001"
+ id="rect196"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.092"
+ height="0.36399999"
+ x="27.91"
+ y="6.3839998"
+ id="rect198"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.68300003"
+ height="0.21799999"
+ x="27.91"
+ y="6.8200002"
+ id="rect200"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="28.934"
+ cy="6.8569999"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse202"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="28.934"
+ cy="6.8569999"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse204"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="28.934"
+ cy="7.0019999"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse206"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="28.934"
+ cy="7.0019999"
+ rx="0.048"
+ ry="0.048"
+ id="ellipse208"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="28.660999"
+ y="6.8930001"
+ id="rect210"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.164"
+ height="0.146"
+ x="28.660999"
+ y="6.8930001"
+ id="rect212"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 28.001,7.33 L 28.001,8.127"
+ id="path214"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 28.228,7.33 L 28.228,8.127"
+ id="path216"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 28.456,7.33 L 28.456,8.127"
+ id="path218"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 28.683,7.33 L 28.683,8.127"
+ id="path220"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 28.911,7.33 L 28.911,8.127"
+ id="path222"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 29.139,7.33 L 29.139,8.127"
+ id="path224"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="27.5,8.559 27.773,8.013 27.773,8.286 29.139,8.286 29.139,8.013 29.503,8.559 27.5,8.559 "
+ id="polygon226"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="27.5,8.559 27.773,8.013 27.773,8.286 29.139,8.286 29.139,8.013 29.503,8.559 27.5,8.559 "
+ id="polygon228"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.322"
+ height="3.086"
+ x="30.264"
+ y="5.1999998"
+ id="rect230"
+ style="fill:#b3b3b3;stroke:none;stroke-width:0" />
+ <rect
+ width="1.322"
+ height="3.086"
+ x="30.264"
+ y="5.1999998"
+ id="rect232"
+ style="fill:none;stroke:#000000;stroke-width:0.08" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="30.396999"
+ y="5.3850002"
+ id="rect234"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="30.396999"
+ y="5.7379999"
+ id="rect236"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="30.396999"
+ y="6.0900002"
+ id="rect238"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="1.058"
+ height="0.35299999"
+ x="30.396999"
+ y="6.4429998"
+ id="rect240"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.66100001"
+ height="0.212"
+ x="30.396999"
+ y="6.8660002"
+ id="rect242"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="31.388"
+ cy="6.901"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse244"
+ style="fill:#00ff00;stroke:none" />
+ <ellipse
+ cx="31.388"
+ cy="6.901"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse246"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <ellipse
+ cx="31.388"
+ cy="7.0430002"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse248"
+ style="fill:#ffff00;stroke:none" />
+ <ellipse
+ cx="31.388"
+ cy="7.0430002"
+ rx="0.046"
+ ry="0.046"
+ id="ellipse250"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <rect
+ width="0.15899999"
+ height="0.141"
+ x="31.124001"
+ y="6.9369998"
+ id="rect252"
+ style="fill:#ffffff;stroke:none;stroke-width:0" />
+ <rect
+ width="0.15899999"
+ height="0.141"
+ x="31.124001"
+ y="6.9369998"
+ id="rect254"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 30.485,7.36 L 30.485,8.131"
+ id="path256"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 30.705,7.36 L 30.705,8.131"
+ id="path258"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 30.926,7.36 L 30.926,8.131"
+ id="path260"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 31.146,7.36 L 31.146,8.131"
+ id="path262"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 31.366,7.36 L 31.366,8.131"
+ id="path264"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <path
+ d="M 31.587,7.36 L 31.587,8.131"
+ id="path266"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+ <polygon
+ points="30,8.55 30.264,8.021 30.264,8.286 31.587,8.286 31.587,8.021 31.939,8.55 30,8.55 "
+ id="polygon268"
+ style="fill:#999999;stroke:none;stroke-width:0.01" />
+ <polygon
+ points="30,8.55 30.264,8.021 30.264,8.286 31.587,8.286 31.587,8.021 31.939,8.55 30,8.55 "
+ id="polygon270"
+ style="fill:none;stroke:#000000;stroke-width:0.01" />
+</svg>
diff --git a/docs-xml/Samba3-HOWTO/images/w2kp001.png b/docs-xml/Samba3-HOWTO/images/w2kp001.png
new file mode 100644
index 0000000000..43adf23463
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/w2kp001.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/w2kp002.png b/docs-xml/Samba3-HOWTO/images/w2kp002.png
new file mode 100644
index 0000000000..13bb029f53
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/w2kp002.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/w2kp003.png b/docs-xml/Samba3-HOWTO/images/w2kp003.png
new file mode 100644
index 0000000000..c7b779900e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/w2kp003.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/w2kp004.png b/docs-xml/Samba3-HOWTO/images/w2kp004.png
new file mode 100644
index 0000000000..d0e005a36e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/w2kp004.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/w2kp005.png b/docs-xml/Samba3-HOWTO/images/w2kp005.png
new file mode 100644
index 0000000000..a729b40cd7
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/w2kp005.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/w2kp006.png b/docs-xml/Samba3-HOWTO/images/w2kp006.png
new file mode 100644
index 0000000000..ea96db055a
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/w2kp006.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp001.png b/docs-xml/Samba3-HOWTO/images/wxpp001.png
new file mode 100644
index 0000000000..2e689a17e2
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp001.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp004.png b/docs-xml/Samba3-HOWTO/images/wxpp004.png
new file mode 100644
index 0000000000..656f67942e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp004.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp006.png b/docs-xml/Samba3-HOWTO/images/wxpp006.png
new file mode 100644
index 0000000000..a20b3ed583
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp006.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp007.png b/docs-xml/Samba3-HOWTO/images/wxpp007.png
new file mode 100644
index 0000000000..cf41352220
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp007.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp008.png b/docs-xml/Samba3-HOWTO/images/wxpp008.png
new file mode 100644
index 0000000000..9958c7c873
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp008.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp010.png b/docs-xml/Samba3-HOWTO/images/wxpp010.png
new file mode 100644
index 0000000000..068a0dfc73
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp010.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp011.png b/docs-xml/Samba3-HOWTO/images/wxpp011.png
new file mode 100644
index 0000000000..0cf88c04a6
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp011.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp012.png b/docs-xml/Samba3-HOWTO/images/wxpp012.png
new file mode 100644
index 0000000000..d89f3b5d31
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp012.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp013.png b/docs-xml/Samba3-HOWTO/images/wxpp013.png
new file mode 100644
index 0000000000..451240ee38
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp013.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/images/wxpp015.png b/docs-xml/Samba3-HOWTO/images/wxpp015.png
new file mode 100644
index 0000000000..12fe2f31b2
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/images/wxpp015.png
Binary files differ
diff --git a/docs-xml/Samba3-HOWTO/index.xml b/docs-xml/Samba3-HOWTO/index.xml
new file mode 100644
index 0000000000..1253b0352e
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/index.xml
@@ -0,0 +1,237 @@
+<?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.2.x 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="TOSHARG-inside-cover.xml"/>
+
+ <?latex \cleardoublepage ?>
+
+ <xi:include href="../Samba3-HOWTO-attributions.xml">
+ <xi:fallback/>
+ </xi:include>
+
+ <?latex \cleardoublepage ?>
+
+<!-- Contents -->
+ <toc/>
+
+ <?latex \cleardoublepage ?>
+
+ <?latex \listofexamples ?>
+
+ <?latex \cleardoublepage ?>
+
+ <lot/>
+
+ <xi:include href="TOSHARG-foreword-cargill.xml"/>
+
+ <?latex \cleardoublepage ?>
+
+ <xi:include href="TOSHARG-preface.xml"/>
+
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-IntroSMB.xml"/>
+
+ <?latex \cleardoublepage ?>
+
+<!-- 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>
+
+ <?latex \cleardoublepage ?>
+
+ <xi:include href="TOSHARG-Install.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-FastStart.xml"/>
+ <?latex \cleardoublepage ?>
+
+</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>
+
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-ServerType.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-PDC.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-BDC.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-DomainMember.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-StandAloneServer.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-WindowsClientConfig.xml"/>
+ <?latex \cleardoublepage ?>
+
+</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>
+
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-ChangeNotes.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-NetworkBrowsing.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Passdb.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Group-Mapping.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-TheNetCommand.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-IDMAP.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-RightsAndPriviliges.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-AccessControls.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-locking.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Securing.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-InterdomainTrusts.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-msdfs.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Printing.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-CUPS-printing.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-VFS.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Winbind.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-AdvancedNetworkAdmin.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-PolicyMgmt.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-ProfileMgmt.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-PAM.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Integrating-with-Windows.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Unicode.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Backup.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-HighAvailability.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-LargeFile.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-ConfigSmarts.xml"/>
+ <?latex \cleardoublepage ?>
+
+</part>
+
+<part id="migration">
+<title>Migration and Updating</title>
+
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-upgrading-to-3.0.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-NT4Migration.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-SWAT.xml"/>
+ <?latex \cleardoublepage ?>
+
+</part>
+
+<part id="troubleshooting">
+<title>Troubleshooting</title>
+
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Diagnosis.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Problems.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Bugs.xml"/>
+ <?latex \cleardoublepage ?>
+
+</part>
+
+<part id="Appendix">
+<title>Reference Section</title>
+
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Compiling.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Portability.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Other-Clients.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Speed.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-SecureLDAP.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-Support.xml"/>
+ <?latex \cleardoublepage ?>
+ <xi:include href="TOSHARG-DNS-DHCP-Configuration.xml"/>
+ <?latex \cleardoublepage ?>
+</part>
+
+<!-- Comment out the following line to include the manpages.
+ *Please* do not commit with the two lines below enabled! -->
+<!--
+ <?latex \cleardoublepage ?>
+ <xi:include href="manpages.xml"/>
+-->
+ <?latex \cleardoublepage ?>
+
+<xi:include href="gpl-3.0.xml"/>
+
+ <?latex \cleardoublepage ?>
+<xi:include href="TOSHARG-glossary.xml"/>
+
+ <?latex \cleardoublepage ?>
+<?latex \chaptermark{Subject index} ?>
+
+<index/>
+
+</book>
diff --git a/docs-xml/Samba3-HOWTO/manpages.xml b/docs-xml/Samba3-HOWTO/manpages.xml
new file mode 100644
index 0000000000..4de54bf4f5
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/manpages.xml
@@ -0,0 +1,73 @@
+<?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 xmlns:xi="http://www.w3.org/2003/XInclude">
+ <title>Manual pages</title>
+
+ <para>This chapter contains most of the manual pages from the official Samba distribution.
+ All manual pages have been written by members of
+ <ulink url="http://www.samba.org/samba/team.html">the Samba Team</ulink>.</para>
+
+ <xi:include href="../manpages-3/eventlogadm.8.xml"/>
+ <xi:include href="../manpages-3/findsmb.1.xml"/>
+ <xi:include href="../manpages-3/idmap_ad.8.xml"/>
+ <xi:include href="../manpages-3/idmap_ldap.8.xml"/>
+ <xi:include href="../manpages-3/idmap_nss.8.xml"/>
+ <xi:include href="../manpages-3/idmap_rid.8.xml"/>
+ <xi:include href="../manpages-3/idmap_tdb.8.xml"/>
+ <xi:include href="../manpages-3/libsmbclient.7.xml"/>
+ <xi:include href="../manpages-3/lmhosts.5.xml"/>
+ <xi:include href="../manpages-3/log2pcap.1.xml"/>
+ <xi:include href="../manpages-3/mount.cifs.8.xml"/>
+ <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/ntlm_auth.1.xml"/>
+ <xi:include href="../manpages-3/pam_winbind.7.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/smbcontrol.1.xml"/>
+ <xi:include href="../manpages-3/smbcquotas.1.xml"/>
+ <xi:include href="../manpages-3/smbd.8.xml"/>
+ <xi:include href="../manpages-3/smbget.1.xml"/>
+ <xi:include href="../manpages-3/smbgetrc.5.xml"/>
+ <xi:include href="../manpages-3/smbpasswd.5.xml"/>
+ <xi:include href="../manpages-3/smbpasswd.8.xml"/>
+ <xi:include href="../manpages-3/smbsh.1.xml"/>
+ <xi:include href="../manpages-3/smbstatus.1.xml"/>
+ <xi:include href="../manpages-3/smbtar.1.xml"/>
+ <xi:include href="../manpages-3/smbtree.1.xml"/>
+ <xi:include href="../manpages-3/smbumount.8.xml"/>
+ <xi:include href="../manpages-3/swat.8.xml"/>
+ <xi:include href="../manpages-3/tdbbackup.8.xml"/>
+ <xi:include href="../manpages-3/tdbdump.8.xml"/>
+ <xi:include href="../manpages-3/tdbtool.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"/>
+ <xi:include href="../manpages-3/umount.cifs.8.xml"/>
+ <xi:include href="../manpages-3/vfs_audit.8.xml"/>
+ <xi:include href="../manpages-3/vfs_cacheprime.8.xml"/>
+ <xi:include href="../manpages-3/vfs_cap.8.xml"/>
+ <xi:include href="../manpages-3/vfs_catia.8.xml"/>
+ <xi:include href="../manpages-3/vfs_commit.8.xml"/>
+ <xi:include href="../manpages-3/vfs_default_quota.8.xml"/>
+ <xi:include href="../manpages-3/vfs_extd_audit.8.xml"/>
+ <xi:include href="../manpages-3/vfs_fake_perms.8.xml"/>
+ <xi:include href="../manpages-3/vfs_full_audit.8.xml"/>
+ <xi:include href="../manpages-3/vfs_gpfs.8.xml"/>
+ <xi:include href="../manpages-3/vfs_netatalk.8.xml"/>
+ <xi:include href="../manpages-3/vfs_notify_fam.8.xml"/>
+ <xi:include href="../manpages-3/vfs_prealloc.8.xml"/>
+ <xi:include href="../manpages-3/vfs_readahead.8.xml"/>
+ <xi:include href="../manpages-3/vfs_readonly.8.xml"/>
+ <xi:include href="../manpages-3/vfs_recycle.8.xml"/>
+ <xi:include href="../manpages-3/vfs_shadow_copy.8.xml"/>
+ <xi:include href="../manpages-3/vfstest.1.xml"/>
+ <xi:include href="../manpages-3/wbinfo.1.xml"/>
+ <xi:include href="../manpages-3/winbindd.8.xml"/>
+
+</reference>