diff options
Diffstat (limited to 'docs/manpages')
28 files changed, 12122 insertions, 5345 deletions
diff --git a/docs/manpages/findsmb.1 b/docs/manpages/findsmb.1 new file mode 100644 index 00000000000..23a51a353de --- /dev/null +++ b/docs/manpages/findsmb.1 @@ -0,0 +1,90 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "FINDSMB" "1" "06 December 2001" "" "" +.SH NAME +findsmb \- list info about machines that respond to SMB name queries on a subnet +.SH SYNOPSIS +.sp +\fBfindsmb\fR [ \fBsubnet broadcast address\fR ] +.SH "DESCRIPTION" +.PP +This perl script is part of the Sambasuite. +.PP +\fBfindsmb\fR is a perl script that +prints out several pieces of information about machines +on a subnet that respond to SMB name query requests. +It uses \fB nmblookup(1)\fRto obtain this information. +.SH "OPTIONS" +.TP +\fBsubnet broadcast address\fR +Without this option, \fBfindsmb +\fRwill probe the subnet of the machine where +\fBfindsmb\fR is run. This value is passed +to \fBnmblookup\fR as part of the +-B option +.SH "EXAMPLES" +.PP +The output of \fBfindsmb\fR lists the following +information for all machines that respond to the initial +\fBnmblookup\fR for any name: IP address, NetBIOS name, +Workgroup name, operating system, and SMB server version. +.PP +There will be a '+' in front of the workgroup name for +machines that are local master browsers for that workgroup. There +will be an '*' in front of the workgroup name for +machines that are the domain master browser for that workgroup. +Machines that are running Windows, Windows 95 or Windows 98 will +not show any information about the operating system or server +version. +.PP +The command must be run on a system without \fBnmbd\fRrunning. +If \fBnmbd\fR is running on the system, you will +only get the IP address and the DNS name of the machine. To +get proper responses from Windows 95 and Windows 98 machines, +the command must be run as root. +.PP +For example running \fBfindsmb\fR on a machine +without \fBnmbd\fR running would yield output similar +to the following +.sp +.nf +IP ADDR NETBIOS NAME WORKGROUP/OS/VERSION +--------------------------------------------------------------------- +192.168.35.10 MINESET-TEST1 [DMVENGR] +192.168.35.55 LINUXBOX *[MYGROUP] [Unix] [Samba 2.0.6] +192.168.35.56 HERBNT2 [HERB-NT] +192.168.35.63 GANDALF [MVENGR] [Unix] [Samba 2.0.5a for IRIX] +192.168.35.65 SAUNA [WORKGROUP] [Unix] [Samba 1.9.18p10] +192.168.35.71 FROGSTAR [ENGR] [Unix] [Samba 2.0.0 for IRIX] +192.168.35.78 HERBDHCP1 +[HERB] +192.168.35.88 SCNT2 +[MVENGR] [Windows NT 4.0] [NT LAN Manager 4.0] +192.168.35.93 FROGSTAR-PC [MVENGR] [Windows 5.0] [Windows 2000 LAN Manager] +192.168.35.97 HERBNT1 *[HERB-NT] [Windows NT 4.0] [NT LAN Manager 4.0] + +.sp +.fi +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBnmbd(8)\fR, +\fBsmbclient(1) +\fR +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/lmhosts.5 b/docs/manpages/lmhosts.5 new file mode 100644 index 00000000000..eb55aa3104a --- /dev/null +++ b/docs/manpages/lmhosts.5 @@ -0,0 +1,92 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "LMHOSTS" "5" "06 December 2001" "" "" +.SH NAME +lmhosts \- The Samba NetBIOS hosts file +.SH SYNOPSIS +.PP +\fIlmhosts\fR is the SambaNetBIOS name to IP address mapping file. +.SH "DESCRIPTION" +.PP +This file is part of the Sambasuite. +.PP +\fIlmhosts\fR is the \fBSamba +\fRNetBIOS name to IP address mapping file. It +is very similar to the \fI/etc/hosts\fR file +format, except that the hostname component must correspond +to the NetBIOS naming format. +.SH "FILE FORMAT" +.PP +It is an ASCII file containing one line for NetBIOS name. +The two fields on each line are separated from each other by +white space. Any entry beginning with '#' is ignored. Each line +in the lmhosts file contains the following information : +.TP 0.2i +\(bu +IP Address - in dotted decimal format. +.TP 0.2i +\(bu +NetBIOS Name - This name format is a +maximum fifteen character host name, with an optional +trailing '#' character followed by the NetBIOS name type +as two hexadecimal digits. + +If the trailing '#' is omitted then the given IP +address will be returned for all names that match the given +name, whatever the NetBIOS name type in the lookup. +.PP +An example follows : +.PP +.PP +.sp +.nf +# +# Sample Samba lmhosts file. +# +192.9.200.1 TESTPC +192.9.200.20 NTSERVER#20 +192.9.200.21 SAMBASERVER + +.sp +.fi +.PP +.PP +Contains three IP to NetBIOS name mappings. The first +and third will be returned for any queries for the names "TESTPC" +and "SAMBASERVER" respectively, whatever the type component of +the NetBIOS name requested. +.PP +.PP +The second mapping will be returned only when the "0x20" name +type for a name "NTSERVER" is queried. Any other name type will not +be resolved. +.PP +.PP +The default location of the \fIlmhosts\fR file +is in the same directory as the +smb.conf(5)>file. +.PP +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbclient(1) +\fR +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/make_smbcodepage.1 b/docs/manpages/make_smbcodepage.1 new file mode 100644 index 00000000000..bb53aeb02dd --- /dev/null +++ b/docs/manpages/make_smbcodepage.1 @@ -0,0 +1,140 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "MAKE_SMBCODEPAGE" "1" "06 December 2001" "" "" +.SH NAME +make_smbcodepage \- construct a codepage file for Samba +.SH SYNOPSIS +.sp +\fBmake_smbcodepage\fR \fBc|d\fR \fBcodepage\fR \fBinputfile\fR \fBoutputfile\fR +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBmake_smbcodepage\fR compiles or de-compiles +codepage files for use with the internationalization features +of Samba 2.2 +.SH "OPTIONS" +.TP +\fBc|d\fR +This tells \fBmake_smbcodepage\fR +if it is compiling (\fIc\fR) a text format code +page file to binary, or (\fId\fR) de-compiling +a binary codepage file to text. +.TP +\fBcodepage\fR +This is the codepage we are processing (a +number, e.g. 850). +.TP +\fBinputfile\fR +This is the input file to process. In +the \fIc\fR case this will be a text +codepage definition file such as the ones found in the Samba +\fIsource/codepages\fR directory. In +the \fId\fR case this will be the +binary format codepage definition file normally found in +the \fIlib/codepages\fR directory in the +Samba install directory path. +.TP +\fBoutputfile\fR +This is the output file to produce. +.SH "SAMBA CODEPAGE FILES" +.PP +A text Samba codepage definition file is a description +that tells Samba how to map from upper to lower case for +characters greater than ascii 127 in the specified DOS code page. +Note that for certain DOS codepages (437 for example) mapping +from lower to upper case may be non-symmetrical. For example, in +code page 437 lower case a acute maps to a plain upper case A +when going from lower to upper case, but plain upper case A maps +to plain lower case a when lower casing a character. +.PP +A binary Samba codepage definition file is a binary +representation of the same information, including a value that +specifies what codepage this file is describing. +.PP +As Samba does not yet use UNICODE (current for Samba version 2.2) +you must specify the client code page that your DOS and Windows +clients are using if you wish to have case insensitivity done +correctly for your particular language. The default codepage Samba +uses is 850 (Western European). Text codepage definition sample files +are provided in the Samba distribution for codepages 437 (USA), 737 (Greek), +850 (Western European) 852 (MS-DOS Latin 2), 861 (Icelandic), 866 (Cyrillic), +932 (Kanji SJIS), 936 (Simplified Chinese), 949 (Hangul) and 950 (Traditional +Chinese). Users are encouraged to write text codepage definition files for +their own code pages and donate them to samba@samba.org. All codepage files +in the Samba \fIsource/codepages\fR directory are +compiled and installed when a \fB'make install'\fR +command is issued there. +.PP +The client codepage used by the \fBsmbd\fR server +is configured using the \fBclient code page\fR parameter +in the \fBsmb.conf\fR file. +.SH "FILES" +.PP +\fBcodepage_def.<codepage>\fR +.PP +These are the input (text) codepage files provided in the +Samba \fIsource/codepages\fR directory. +.PP +A text codepage definition file consists of multiple lines +containing four fields. These fields are: +.TP 0.2i +\(bu +\fBlower\fR: which is the +(hex) lower case character mapped on this line. +.TP 0.2i +\(bu +\fBupper\fR: which is the (hex) +upper case character that the lower case character will map to. +.TP 0.2i +\(bu +\fBmap upper to lower\fR which +is a boolean value (put either True or False here) which tells +Samba if it is to map the given upper case character to the +given lower case character when lower casing a filename. +.TP 0.2i +\(bu +\fBmap lower to upper\fR which +is a boolean value (put either True or False here) which tells +Samba if it is to map the given lower case character to the +given upper case character when upper casing a filename. +.PP +\fBcodepage.<codepage>\fR - These are the +output (binary) codepage files produced and placed in the Samba +destination \fIlib/codepage\fR directory. +.PP +.SH "INSTALLATION" +.PP +The location of the server and its support files is a +matter for individual system administrators. The following are +thus suggestions only. +.PP +It is recommended that the \fBmake_smbcodepage +\fRprogram be installed under the \fI/usr/local/samba +\fRhierarchy, in a directory readable by all, writeable +only by root. The program itself should be executable by all. The +program should NOT be setuid or setgid! +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbd(8)\fR, +smb.conf(5) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/make_unicodemap.1 b/docs/manpages/make_unicodemap.1 new file mode 100644 index 00000000000..93683c2708e --- /dev/null +++ b/docs/manpages/make_unicodemap.1 @@ -0,0 +1,99 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "MAKE_UNICODEMAP" "1" "06 December 2001" "" "" +.SH NAME +make_unicodemap \- construct a unicode map file for Samba +.SH SYNOPSIS +.sp +\fBmake_unicodemap\fR \fBcodepage\fR \fBinputfile\fR \fBoutputfile\fR +.SH "DESCRIPTION" +.PP +This tool is part of the Samba +suite. +.PP +\fBmake_unicodemap\fR compiles text unicode map +files into binary unicode map files for use with the +internationalization features of Samba 2.2. +.SH "OPTIONS" +.TP +\fBcodepage\fR +This is the codepage or UNIX character +set we are processing (a number, e.g. 850). +.TP +\fBinputfile\fR +This is the input file to process. This is a +text unicode map file such as the ones found in the Samba +\fIsource/codepages\fR directory. +.TP +\fBoutputfile\fR +This is the binary output file to produce. +.SH "SAMBA UNICODE MAP FILES" +.PP +A text Samba unicode map file is a description that tells Samba +how to map characters from a specified DOS code page or UNIX character +set to 16 bit unicode. +.PP +A binary Samba unicode map file is a binary representation +of the same information, including a value that specifies what +codepage or UNIX character set this file is describing. +.SH "FILES" +.PP +\fICP<codepage>.TXT\fR +.PP +These are the input (text) unicode map files provided +in the Samba \fIsource/codepages\fR +directory. +.PP +A text unicode map file consists of multiple lines +containing two fields. These fields are : +.TP 0.2i +\(bu +\fIcharacter\fR - which is +the (hex) character mapped on this line. +.TP 0.2i +\(bu +\fIunicode\fR - which +is the (hex) 16 bit unicode character that the character +will map to. +.PP +\fIunicode_map.<codepage>\fR - These are +the output (binary) unicode map files produced and placed in +the Samba destination \fIlib/codepage\fR +directory. +.PP +.SH "INSTALLATION" +.PP +The location of the server and its support files is a matter +for individual system administrators. The following are thus +suggestions only. +.PP +It is recommended that the \fBmake_unicodemap\fR +program be installed under the +\fI$prefix/samba\fR hierarchy, +in a directory readable by all, writeable only by root. The +program itself should be executable by all. The program +should NOT be setuid or setgid! +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbd(8)\fR, +smb.conf(5) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/nmbd.8 b/docs/manpages/nmbd.8 index e42f194cdee..e7786549a1e 100644 --- a/docs/manpages/nmbd.8 +++ b/docs/manpages/nmbd.8 @@ -1,491 +1,241 @@ -.TH NMBD 8 17/1/1995 nmbd nmbd +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "NMBD" "8" "06 December 2001" "" "" .SH NAME -nmbd \- provide netbios nameserver support to clients +nmbd \- NetBIOS name server to provide NetBIOS over IP naming services to clients .SH SYNOPSIS -.B nmbd -[ -.B -B -.I broadcast address -] [ -.B -I -.I IP address -] [ -.B -D -] [ -.B -C comment string -] [ -.B -G -.I group name -] [ -.B -H -.I netbios hosts file -] [ -.B -N -.I netmask -] [ -.B -d -.I debuglevel -] [ -.B -l -.I log basename -] [ -.B -n -.I netbios name -] [ -.B -p -.I port number -] [ -.B -s -.I config file name -] - -.SH DESCRIPTION +.sp +\fBnmbd\fR [ \fB-D\fR ] [ \fB-a\fR ] [ \fB-o\fR ] [ \fB-P\fR ] [ \fB-h\fR ] [ \fB-V\fR ] [ \fB-d <debug level>\fR ] [ \fB-H <lmhosts file>\fR ] [ \fB-l <log directory>\fR ] [ \fB-n <primary netbios name>\fR ] [ \fB-p <port number>\fR ] [ \fB-s <configuration file>\fR ] +.SH "DESCRIPTION" +.PP This program is part of the Samba suite. - -.B nmbd -is a server that understands and can reply to netbios -name service requests, like those produced by LanManager -clients. It also controls browsing. - -LanManager clients, when they start up, may wish to locate a LanManager server. -That is, they wish to know what IP number a specified host is using. - -This program simply listens for such requests, and if its own name is specified -it will respond with the IP number of the host it is running on. "Its own name" -is by default the name of the host it is running on, but this can be overriden -with the -.B -n -option (see "OPTIONS" below). Using the -.B -S -option (see "OPTIONS" below), it can also be instructed to respond with IP -information about other hosts, provided they are locatable via the -gethostbyname() call, or they are in a netbios hosts file. - -Nmbd can also be used as a WINS (Windows Internet Name Server) -server. It will do this automatically by default. What this basically -means is that it will respond to all name requests that it receives -that are not broadcasts, as long as it can resolve the name. -.SH OPTIONS -.B -B - -.RS 3 -On some systems, the server is unable to determine the broadcast address to -use for name registration requests. If your system has this difficulty, this -parameter may be used to specify an appropriate broadcast address. The -address should be given in standard "a.b.c.d" notation. - -Only use this parameter if you are sure that the server cannot properly -determine the proper broadcast address. - -The default broadcast address is determined by the server at run time. If it -encounters difficulty doing so, it makes a guess based on the local IP -number. -.RE -.B -I - -.RS 3 -On some systems, the server is unable to determine the correct IP -address to use. This allows you to override the default choice. -.RE - -.B -D - -.RS 3 -If specified, this parameter causes the server to operate as a daemon. That is, -it detaches itself and runs in the background, fielding requests on the -appropriate port. - -By default, the server will NOT operate as a daemon. -.RE - -.B -C comment string - -.RS 3 -This allows you to set the "comment string" that is shown next to the -machine name in browse listings. - -A %v will be replaced with the Samba version number. - -A %h will be replaced with the hostname. - -It defaults to "Samba %v". -.RE - -.B -G - -.RS 3 -This option allows you to specify a netbios group (also known as -lanmanager domain) that the server should be part of. You may include -several of these on the command line if you like. Alternatively you -can use the -H option to load a netbios hosts file containing domain names. - -At startup, unless the -R switch has been used, the server will -attempt to register all group names in the hosts file and on the -command line (from the -G option). - -The server will also respond to queries on this name. -.RE - -.B -H - -.RS 3 -It may be useful in some situations to be able to specify a list of -netbios names for which the server should send a reply if -queried. This option allows that. The syntax is similar to the -standard /etc/hosts file format, but has some extensions. - -The file contains three columns. Lines beginning with a # are ignored -as comments. The first column is an IP address, or a hostname. If it -is a hostname then it is interpreted as the IP address returned by -gethostbyname() when read. Any IP address of 0.0.0.0 will be -interpreted as the servers own IP address. - -The second column is a netbios name. This is the name that the server -will respond to. It must be less than 20 characters long. - -The third column is optional, and is intended for flags. Currently the -only flags supported are G, S and M. A G indicates that the name is a -group (also known as domain) name. - -At startup all groups known to the server (either from this file or -from the -G option) are registered on the network (unless the -R -option has been selected). - -A S or G means that the specified address is a broadcast address of a -network that you want people to be able to browse you from. Nmbd will -search for a master browser in that domain and will send host -announcements to that machine, informing it that the specifed somain -is available. - -A M means that this name is the default netbios name for this -machine. This has the same affect as specifying the -n option to nmbd. - -After startup the server waits for queries, and will answer queries to -any name known to it. This includes all names in the netbios hosts -file (if any), it's own name, and any names given with the -G option. - -The primary intention of the -H option is to allow a mapping from -netbios names to internet domain names, and to allow the specification -of groups that the server should be part of. - -.B Example: - - # This is a sample netbios hosts file - - # DO NOT USE THIS FILE AS-IS - # YOU MAY INCONVENIENCE THE OWNERS OF THESE IPs - # if you want to include a name with a space in it then - # use double quotes. - - # first put ourselves in the group LANGROUP - 0.0.0.0 LANGROUP G - - # next add a netbios alias for a faraway host - arvidsjaur.anu.edu.au ARVIDSJAUR - - # finally put in an IP for a hard to find host - 130.45.3.213 FREDDY - - # now we want another subnet to be able to browse - # us in the workgroup UNIXSERV - 192.0.2.255 UNIXSERV G - -.RE - -.B -M -.I workgroup name - -.RS 3 -If this parameter is given, the server will look for a master browser -for the specified workgroup name, report success or failure, then -exit. If successful, the IP address of the name located will be -reported. - -If you use the workgroup name "-" then nmbd will search for a master -browser for any workgroup by using the name __MSBROWSE__. - -This option is meant to be used interactively on the command line, not -as a daemon or in inetd. - -.RE -.B -N - -.RS 3 -On some systems, the server is unable to determine the netmask. If -your system has this difficulty, this parameter may be used to specify -an appropriate netmask. The mask should be given in standard -"a.b.c.d" notation. - -Only use this parameter if you are sure that the server cannot properly -determine the proper netmask. - -The default netmask is determined by the server at run time. If it -encounters difficulty doing so, it makes a guess based on the local IP -number. -.RE - -.B -d -.I debuglevel -.RS 3 - -debuglevel is an integer from 0 to 5. - -The default value if this parameter is not specified is zero. - -The higher this value, the more detail will be logged to the log files about -the activities of the server. At level 0, only critical errors and serious -warnings will be logged. Level 1 is a reasonable level for day to day running -- it generates a small amount of information about operations carried out. - -Levels above 1 will generate considerable amounts of log data, and should -only be used when investigating a problem. Levels above 3 are designed for -use only by developers and generate HUGE amounts of log data, most of which -is extremely cryptic. -.RE - -.B -l -.I log file - -.RS 3 -If specified, -.I logfile -specifies a base filename into which operational data from the running server -will be logged. - -The default base name is specified at compile time. - -The base name is used to generate actual log file names. For example, if the -name specified was "log", the following files would be used for log data: - -.RS 3 -log.nmb (containing debugging information) - -log.nmb.in (containing inbound transaction data) - -log.nmb.out (containing outbound transaction data) -.RE - -The log files generated are never removed by the server. -.RE -.RE - -.B -n -.I netbios name - -.RS 3 -This parameter tells the server what netbios name to respond with when -queried. The same name is also registered on startup unless the -R -parameter was specified. - -The default netbios name used if this parameter is not specified is the -name of the host on which the server is running. -.RE - -.B -p -.I port number -.RS 3 - -port number is a positive integer value. - -The default value if this parameter is not specified is 137. - -This number is the port number that will be used when making connections to -the server from client software. The standard (well-known) port number for the -server is 137, hence the default. If you wish to run the server as an ordinary -user rather than as root, most systems will require you to use a port number -greater than 1024 - ask your system administrator for help if you are in this -situation. - -Note that the name server uses UDP, not TCP! - -This parameter is not normally specified except in the above situation. -.RE -.SH FILES - -.B /etc/inetd.conf - -.RS 3 -If the server is to be run by the inetd meta-daemon, this file must contain -suitable startup information for the meta-daemon. See the section -"INSTALLATION" below. -.RE - -.B /etc/rc.d/rc.inet2 - -.RS 3 -(or whatever initialisation script your system uses) - -If running the server as a daemon at startup, this file will need to contain -an appropriate startup sequence for the server. See the section "Installation" +.PP +\fBnmbd\fR is a server that understands +and can reply to NetBIOS over IP name service requests, like +those produced by SMB/CIFS clients such as Windows 95/98/ME, +Windows NT, Windows 2000, and LanManager clients. It also +participates in the browsing protocols which make up the +Windows "Network Neighborhood" view. +.PP +SMB/CIFS clients, when they start up, may wish to +locate an SMB/CIFS server. That is, they wish to know what +IP number a specified host is using. +.PP +Amongst other services, \fBnmbd\fR will +listen for such requests, and if its own NetBIOS name is +specified it will respond with the IP number of the host it +is running on. Its "own NetBIOS name" is by +default the primary DNS name of the host it is running on, +but this can be overridden with the \fB-n\fR +option (see OPTIONS below). Thus \fBnmbd\fR will +reply to broadcast queries for its own name(s). Additional +names for \fBnmbd\fR to respond on can be set +via parameters in the \fI smb.conf(5)\fRconfiguration file. +.PP +\fBnmbd\fR can also be used as a WINS +(Windows Internet Name Server) server. What this basically means +is that it will act as a WINS database server, creating a +database from name registration requests that it receives and +replying to queries from clients for these names. +.PP +In addition, \fBnmbd\fR can act as a WINS +proxy, relaying broadcast queries from clients that do +not understand how to talk the WINS protocol to a WIN +server. +.SH "OPTIONS" +.TP +\fB-D\fR +If specified, this parameter causes +\fBnmbd\fR to operate as a daemon. That is, +it detaches itself and runs in the background, fielding +requests on the appropriate port. By default, \fBnmbd\fR +will operate as a daemon if launched from a command shell. +nmbd can also be operated from the \fBinetd\fR +meta-daemon, although this is not recommended. +.TP +\fB-a\fR +If this parameter is specified, each new +connection will append log messages to the log file. +This is the default. +.TP +\fB-o\fR +If this parameter is specified, the +log files will be overwritten when opened. By default, +\fBsmbd\fR will append entries to the log +files. +.TP +\fB-h\fR +Prints the help information (usage) +for \fBnmbd\fR. +.TP +\fB-H <filename>\fR +NetBIOS lmhosts file. The lmhosts +file is a list of NetBIOS names to IP addresses that +is loaded by the nmbd server and used via the name +resolution mechanism name resolve order +to resolve any NetBIOS name queries needed by the server. Note +that the contents of this file are \fBNOT\fR +used by \fBnmbd\fR to answer any name queries. +Adding a line to this file affects name NetBIOS resolution +from this host \fBONLY\fR. + +The default path to this file is compiled into +Samba as part of the build process. Common defaults +are \fI/usr/local/samba/lib/lmhosts\fR, +\fI/usr/samba/lib/lmhosts\fR or +\fI/etc/lmhosts\fR. See the \fIlmhosts(5)\fRman page for details on the +contents of this file. +.TP +\fB-V\fR +Prints the version number for +\fBnmbd\fR. +.TP +\fB-d <debug level>\fR +debuglevel is an integer +from 0 to 10. The default value if this parameter is +not specified is zero. + +The higher this value, the more detail will +be logged to the log files about the activities of the +server. At level 0, only critical errors and serious +warnings will be logged. Level 1 is a reasonable level for +day to day running - it generates a small amount of +information about operations carried out. + +Levels above 1 will generate considerable amounts +of log data, and should only be used when investigating +a problem. Levels above 3 are designed for use only by developers +and generate HUGE amounts of log data, most of which is extremely +cryptic. + +Note that specifying this parameter here will override +the log level +parameter in the \fI smb.conf\fRfile. +.TP +\fB-l <log directory>\fR +The -l parameter specifies a directory +into which the "log.nmbd" log file will be created +for operational data from the running +\fBnmbd\fR server. + +The default log directory is compiled into Samba +as part of the build process. Common defaults are \fI /usr/local/samba/var/log.nmb\fR, \fI /usr/samba/var/log.nmb\fR or +\fI/var/log/log.nmb\fR. +.TP +\fB-n <primary NetBIOS name>\fR +This option allows you to override +the NetBIOS name that Samba uses for itself. This is identical +to setting the NetBIOS nameparameter in the +\fIsmb.conf\fRfile. However, a command +line setting will take precedence over settings in +\fIsmb.conf\fR. +.TP +\fB-p <UDP port number>\fR +UDP port number is a positive integer value. +This option changes the default UDP port number (normally 137) +that \fBnmbd\fR responds to name queries on. Don't +use this option unless you are an expert, in which case you +won't need help! +.TP +\fB-s <configuration file>\fR +The default configuration file name +is set at build time, typically as \fI /usr/local/samba/lib/smb.conf\fR, but +this may be changed when Samba is autoconfigured. + +The file specified contains the configuration details +required by the server. See +\fIsmb.conf(5)\fRfor more information. +.SH "FILES" +.TP +\fB\fI/etc/inetd.conf\fB\fR +If the server is to be run by the +\fBinetd\fR meta-daemon, this file +must contain suitable startup information for the +meta-daemon. See the section INSTALLATION below. +.TP +\fB\fI/etc/rc\fB\fR +or whatever initialization script your +system uses). + +If running the server as a daemon at startup, +this file will need to contain an appropriate startup +sequence for the server. See the section INSTALLATION below. -.RE - -.B /etc/services - -.RS 3 -If running the server via the meta-daemon inetd, this file must contain a -mapping of service name (eg., netbios-ns) to service port (eg., 137) and -protocol type (eg., udp). See the section "INSTALLATION" below. -.RE -.RE - -.SH ENVIRONMENT VARIABLES -Not applicable. - -.SH INSTALLATION -The location of the server and its support files is a matter for individual -system administrators. The following are thus suggestions only. - -It is recommended that the server software be installed under the /usr/local -hierarchy, in a directory readable by all, writeable only by root. The server -program itself should be executable by all, as users may wish to run the -server themselves (in which case it will of course run with their privileges). -The server should NOT be setuid or setgid! - -The server log files should be put in a directory readable and writable only -by root, as the log files may contain sensitive information. - -The remaining notes will assume the following: - -.RS 3 -nmbd (the server program) installed in /usr/local/smb - -log files stored in /var/adm/smblogs -.RE - -The server may be run either as a daemon by users or at startup, or it may -be run from a meta-daemon such as inetd upon request. If run as a daemon, the -server will always be ready, so starting sessions will be faster. If run from -a meta-daemon some memory will be saved and utilities such as the tcpd -TCP-wrapper may be used for extra security. - -When you've decided, continue with either "Running the server as a daemon" or -"Running the server on request". -.SH RUNNING THE SERVER AS A DAEMON -To run the server as a daemon from the command line, simply put the "-D" option -on the command line. There is no need to place an ampersand at the end of the -command line - the "-D" option causes the server to detach itself from the -tty anyway. - -Any user can run the server as a daemon (execute permissions permitting, of -course). This is useful for testing purposes. - -To ensure that the server is run as a daemon whenever the machine is started, -you will need to modify the system startup files. Wherever appropriate (for -example, in /etc/rc.d/rc.inet2), insert the following line, substituting -values appropriate to your system: - -.RS 3 -/usr/local/smb/nmbd -D -l/var/adm/smblogs/log -.RE - -(The above should appear in your initialisation script as a single line. -Depending on your terminal characteristics, it may not appear that way in -this man page. If the above appears as more than one line, please treat any -newlines or indentation as a single space or TAB character.) - -If the options used at compile time are appropriate for your system, all -parameters except the desired debug level and "-D" may be omitted. See the -section on "Options" above. -.SH RUNNING THE SERVER ON REQUEST -If your system uses a meta-daemon such as inetd, you can arrange to have the -SMB name server started whenever a process attempts to connect to it. This -requires several changes to the startup files on the host machine. If you are -experimenting as an ordinary user rather than as root, you will need the -assistance of your system administrator to modify the system files. - -First, ensure that a port is configured in the file /etc/services. The -well-known port 137 should be used if possible, though any port may be used. - -Ensure that a line similar to the following is in /etc/services: - -.RS 3 -netbios-ns 137/udp -.RE - -Note for NIS/YP users: You may need to rebuild the NIS service maps rather -than alter your local /etc/services file. - -Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event -that you are using a meta-daemon other than inetd, you are on your own). Note -that the first item in this line matches the service name in /etc/services. -Substitute appropriate values for your system in this line (see -.B inetd(8)): - -.RS 3 -netbios-ns dgram udp wait root /usr/local/smb/nmbd -l/var/adm/smblogs/log -.RE - -(The above should appear in /etc/inetd.conf as a single line. Depending on -your terminal characteristics, it may not appear that way in this man page. -If the above appears as more than one line, please treat any newlines or -indentation as a single space or TAB character.) - -Note that there is no need to specify a port number here, even if you are -using a non-standard port number. -.SH TESTING THE INSTALLATION -If running the server as a daemon, execute it before proceeding. If -using a meta-daemon, either restart the system or kill and restart the -meta-daemon. Some versions of inetd will reread their configuration tables if -they receive a HUP signal. - -To test whether the name server is running, start up a client -.I on a different machine -and see whether the desired name is now present. Alternatively, run -the nameserver -.I on a different machine -specifying "-L netbiosname", where "netbiosname" is the name you have -configured the test server to respond with. The command should respond -with success, and the IP number of the machine using the specified netbios -name. You may need the -B parameter on some systems. See the README -file for more information on testing nmbd. - -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the server has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B inetd(8), -.B smbd(8), -.B smb.conf(5), -.B smbclient(1), -.B testparm(1), -.B testprns(1) - -.SH DIAGNOSTICS -[This section under construction] - -Most diagnostics issued by the server are logged in the specified log file. The -log file name is specified at compile time, but may be overridden on the -command line. - -The number and nature of diagnostics available depends on the debug level used -by the server. If you have problems, set the debug level to 3 and peruse the -log files. - -Most messages are reasonably self-explanatory. Unfortunately, at time of -creation of this man page the source code is still too fluid to warrant -describing each and every diagnostic. At this stage your best bet is still -to grep the source code and inspect the conditions that gave rise to the -diagnostics you are seeing. - -.SH BUGS -None known. -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -This man page written by Karl Auer (Karl.Auer@anu.edu.au) - -See -.B smb.conf(5) for a full list of contributors and details on how to -submit bug reports, comments etc. - - - - - +.TP +\fB\fI/etc/services\fB\fR +If running the server via the +meta-daemon \fBinetd\fR, this file +must contain a mapping of service name (e.g., netbios-ssn) +to service port (e.g., 139) and protocol type (e.g., tcp). +See the section INSTALLATION below. +.TP +\fB\fI/usr/local/samba/lib/smb.conf\fB\fR +This is the default location of the +\fIsmb.conf\fR +server configuration file. Other common places that systems +install this file are \fI/usr/samba/lib/smb.conf\fR +and \fI/etc/smb.conf\fR. + +When run as a WINS server (see the +wins support +parameter in the \fI smb.conf(5)\fRman page), \fBnmbd\fR +will store the WINS database in the file \fIwins.dat\fR +in the \fIvar/locks\fR directory configured under +wherever Samba was configured to install itself. + +If \fBnmbd\fR is acting as a \fB browse master\fR (see the local master +parameter in the \fI smb.conf(5)\fRman page), \fBnmbd\fR +will store the browsing database in the file \fIbrowse.dat +\fRin the \fIvar/locks\fR directory +configured under wherever Samba was configured to install itself. +.SH "SIGNALS" +.PP +To shut down an \fBnmbd\fR process it is recommended +that SIGKILL (-9) \fBNOT\fR be used, except as a last +resort, as this may leave the name database in an inconsistent state. +The correct way to terminate \fBnmbd\fR is to send it +a SIGTERM (-15) signal and wait for it to die on its own. +.PP +\fBnmbd\fR will accept SIGHUP, which will cause +it to dump out its namelists into the file \fInamelist.debug +\fRin the \fI/usr/local/samba/var/locks\fR +directory (or the \fIvar/locks\fR directory configured +under wherever Samba was configured to install itself). This will also +cause \fBnmbd\fR to dump out its server database in +the \fIlog.nmb\fR file. +.PP +The debug log level of nmbd may be raised or lowered using +\fBsmbcontrol(1)\fR +(SIGUSR[1|2] signals are no longer used in Samba 2.2). This is +to allow transient problems to be diagnosed, whilst still running +at a normally low log level. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBinetd(8)\fR, \fBsmbd(8)\fR, +\fIsmb.conf(5)\fR +, \fBsmbclient(1) +\fR, and the Internet RFC's +\fIrfc1001.txt\fR, \fIrfc1002.txt\fR. +In addition the CIFS (formerly SMB) specification is available +as a link from the Web page +http://samba.org/cifs/ <URL:http://samba.org/cifs/>. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/nmblookup.1 b/docs/manpages/nmblookup.1 new file mode 100644 index 00000000000..c607a4a72d5 --- /dev/null +++ b/docs/manpages/nmblookup.1 @@ -0,0 +1,154 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "NMBLOOKUP" "1" "06 December 2001" "" "" +.SH NAME +nmblookup \- NetBIOS over TCP/IP client used to lookup NetBIOS names +.SH SYNOPSIS +.sp +\fBnmblookup\fR [ \fB-M\fR ] [ \fB-R\fR ] [ \fB-S\fR ] [ \fB-r\fR ] [ \fB-A\fR ] [ \fB-h\fR ] [ \fB-B <broadcast address>\fR ] [ \fB-U <unicast address>\fR ] [ \fB-d <debug level>\fR ] [ \fB-s <smb config file>\fR ] [ \fB-i <NetBIOS scope>\fR ] [ \fB-T\fR ] \fBname\fR +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBnmblookup\fR is used to query NetBIOS names +and map them to IP addresses in a network using NetBIOS over TCP/IP +queries. The options allow the name queries to be directed at a +particular IP broadcast area or to a particular machine. All queries +are done over UDP. +.SH "OPTIONS" +.TP +\fB-M\fR +Searches for a master browser by looking +up the NetBIOS name \fIname\fR with a +type of 0x1d. If \fI name\fR is "-" then it does a lookup on the special name +__MSBROWSE__. +.TP +\fB-R\fR +Set the recursion desired bit in the packet +to do a recursive lookup. This is used when sending a name +query to a machine running a WINS server and the user wishes +to query the names in the WINS server. If this bit is unset +the normal (broadcast responding) NetBIOS processing code +on a machine is used instead. See rfc1001, rfc1002 for details. +.TP +\fB-S\fR +Once the name query has returned an IP +address then do a node status query as well. A node status +query returns the NetBIOS names registered by a host. +.TP +\fB-r\fR +Try and bind to UDP port 137 to send and receive UDP +datagrams. The reason for this option is a bug in Windows 95 +where it ignores the source port of the requesting packet +and only replies to UDP port 137. Unfortunately, on most UNIX +systems root privilege is needed to bind to this port, and +in addition, if the nmbd(8) +daemon is running on this machine it also binds to this port. +.TP +\fB-A\fR +Interpret \fIname\fR as +an IP Address and do a node status query on this address. +.TP +\fB-h\fR +Print a help (usage) message. +.TP +\fB-B <broadcast address>\fR +Send the query to the given broadcast address. Without +this option the default behavior of nmblookup is to send the +query to the broadcast address of the network interfaces as +either auto-detected or defined in the \fIinterfaces\fR +parameter of the \fIsmb.conf (5)\fR file. +.TP +\fB-U <unicast address>\fR +Do a unicast query to the specified address or +host \fIunicast address\fR. This option +(along with the \fI-R\fR option) is needed to +query a WINS server. +.TP +\fB-d <debuglevel>\fR +debuglevel is an integer from 0 to 10. + +The default value if this parameter is not specified +is zero. + +The higher this value, the more detail will be logged +about the activities of \fBnmblookup\fR. At level +0, only critical errors and serious warnings will be logged. + +Levels above 1 will generate considerable amounts of +log data, and should only be used when investigating a problem. +Levels above 3 are designed for use only by developers and +generate HUGE amounts of data, most of which is extremely cryptic. + +Note that specifying this parameter here will override +the \fI log level\fRparameter in the \fI smb.conf(5)\fR file. +.TP +\fB-s <smb.conf>\fR +This parameter specifies the pathname to +the Samba configuration file, smb.conf(5). This file controls all aspects of +the Samba setup on the machine. +.TP +\fB-i <scope>\fR +This specifies a NetBIOS scope that +\fBnmblookup\fR will use to communicate with when +generating NetBIOS names. For details on the use of NetBIOS +scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes are +\fBvery\fR rarely used, only set this parameter +if you are the system administrator in charge of all the +NetBIOS systems you communicate with. +.TP +\fB-T\fR +This causes any IP addresses found in the +lookup to be looked up via a reverse DNS lookup into a +DNS name, and printed out before each + +\fBIP address .... NetBIOS name\fR + +pair that is the normal output. +.TP +\fBname\fR +This is the NetBIOS name being queried. Depending +upon the previous options this may be a NetBIOS name or IP address. +If a NetBIOS name then the different name types may be specified +by appending '#<type>' to the name. This name may also be +\&'*', which will return all registered names within a broadcast +area. +.SH "EXAMPLES" +.PP +\fBnmblookup\fR can be used to query +a WINS server (in the same way \fBnslookup\fR is +used to query DNS servers). To query a WINS server, +\fBnmblookup\fR must be called like this: +.PP +\fBnmblookup -U server -R 'name'\fR +.PP +For example, running : +.PP +\fBnmblookup -U samba.org -R 'IRIX#1B'\fR +.PP +would query the WINS server samba.org for the domain +master browser (1B name type) for the IRIX workgroup. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBnmbd(8)\fR, +samba(7) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/rpcclient.1 b/docs/manpages/rpcclient.1 new file mode 100644 index 00000000000..a29dbe28440 --- /dev/null +++ b/docs/manpages/rpcclient.1 @@ -0,0 +1,329 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "RPCCLIENT" "1" "06 December 2001" "" "" +.SH NAME +rpcclient \- tool for executing client side MS-RPC functions +.SH SYNOPSIS +.sp +\fBrpcclient\fR \fBserver\fR [ \fB-A authfile\fR ] [ \fB-c <command string>\fR ] [ \fB-d debuglevel\fR ] [ \fB-h\fR ] [ \fB-l logfile\fR ] [ \fB-N\fR ] [ \fB-s <smb config file>\fR ] [ \fB-U username[%password]\fR ] [ \fB-W workgroup\fR ] [ \fB-N\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBrpcclient\fR is a utility initially developed +to test MS-RPC functionality in Samba itself. It has undergone +several stages of development and stability. Many system administrators +have now written scripts around it to manage Windows NT clients from +their UNIX workstation. +.SH "OPTIONS" +.TP +\fBserver\fR +NetBIOS name of Server to which to connect. +The server can be any SMB/CIFS server. The name is +resolved using the \fIname resolve order\fRline from +\fIsmb.conf(5)\fR. +.TP +\fB-A filename\fR +This option allows +you to specify a file from which to read the username and +password used in the connection. The format of the file is + +.sp +.nf + username = <value> + password = <value> + domain = <value> + +.sp +.fi + +Make certain that the permissions on the file restrict +access from unwanted users. +.TP +\fB-c 'command string'\fR +execute semicolon separated commands (listed +below)) +.TP +\fB-d debuglevel\fR +set the debuglevel. Debug level 0 is the lowest +and 100 being the highest. This should be set to 100 if you are +planning on submitting a bug report to the Samba team (see \fIBUGS.txt\fR). +.TP +\fB-h\fR +Print a summary of command line options. +.TP +\fB-l logbasename\fR +File name for log/debug files. The extension +\&'.client' will be appended. The log file is never removed +by the client. +.TP +\fB-N\fR +instruct \fBrpcclient\fR not to ask +for a password. By default, \fBrpcclient\fR will prompt +for a password. See also the \fI-U\fR option. +.TP +\fB-s smb.conf\fR +Specifies the location of the all important +\fIsmb.conf\fR file. +.TP +\fB-U username[%password]\fR +Sets the SMB username or username and password. + +If %password is not specified, the user will be prompted. The +client will first check the \fBUSER\fR environment variable, then the +\fBLOGNAME\fR variable and if either exists, the +string is uppercased. If these environmental variables are not +found, the username GUEST is used. + +A third option is to use a credentials file which +contains the plaintext of the username and password. This +option is mainly provided for scripts where the admin doesn't +desire to pass the credentials on the command line or via environment +variables. If this method is used, make certain that the permissions +on the file restrict access from unwanted users. See the +\fI-A\fR for more details. + +Be cautious about including passwords in scripts. Also, on +many systems the command line of a running process may be seen +via the \fBps\fR command. To be safe always allow +\fBrpcclient\fR to prompt for a password and type +it in directly. +.TP +\fB-W domain\fR +Set the SMB domain of the username. This +overrides the default domain which is the domain defined in +smb.conf. If the domain specified is the same as the server's NetBIOS name, +it causes the client to log on using the server's local SAM (as +opposed to the Domain SAM). +.SH "COMMANDS" +.PP +\fBLSARPC\fR +.TP 0.2i +\(bu +\fBlsaquery\fR +.TP 0.2i +\(bu +\fBlookupsids\fR - Resolve a list +of SIDs to usernames. +.TP 0.2i +\(bu +\fBlookupnames\fR - Resolve s list +of usernames to SIDs. +.TP 0.2i +\(bu +\fBenumtrusts\fR +.PP +.PP +.PP +\fBSAMR\fR +.PP +.TP 0.2i +\(bu +\fBqueryuser\fR +.TP 0.2i +\(bu +\fBquerygroup\fR +.TP 0.2i +\(bu +\fBqueryusergroups\fR +.TP 0.2i +\(bu +\fBquerygroupmem\fR +.TP 0.2i +\(bu +\fBqueryaliasmem\fR +.TP 0.2i +\(bu +\fBquerydispinfo\fR +.TP 0.2i +\(bu +\fBquerydominfo\fR +.TP 0.2i +\(bu +\fBenumdomgroups\fR +.PP +.PP +.PP +\fBSPOOLSS\fR +.PP +.TP 0.2i +\(bu +\fBadddriver <arch> <config>\fR +- Execute an AddPrinterDriver() RPC to install the printer driver +information on the server. Note that the driver files should +already exist in the directory returned by +\fBgetdriverdir\fR. Possible values for +\fIarch\fR are the same as those for +the \fBgetdriverdir\fR command. +The \fIconfig\fR parameter is defined as +follows: + +.sp +.nf + 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 + +.sp +.fi + +Any empty fields should be enter as the string "NULL". + +Samba does not need to support the concept of Print Monitors +since these only apply to local printers whose driver can make +use of a bi-directional link for communication. This field should +be "NULL". On a remote NT print server, the Print Monitor for a +driver must already be installed prior to adding the driver or +else the RPC will fail. +.TP 0.2i +\(bu +\fBaddprinter <printername> +<sharename> <drivername> <port>\fR +- Add a printer on the remote server. This printer +will be automatically shared. Be aware that the printer driver +must already be installed on the server (see \fBadddriver\fR) +and the \fIport\fRmust be a valid port name (see +\fBenumports\fR. +.TP 0.2i +\(bu +\fBdeldriver\fR - Delete the +specified printer driver for all architectures. This +does not delete the actual driver files from the server, +only the entry from the server's list of drivers. +.TP 0.2i +\(bu +\fBenumdata\fR - Enumerate all +printer setting data stored on the server. On Windows NT clients, +these values are stored in the registry, while Samba servers +store them in the printers TDB. This command corresponds +to the MS Platform SDK GetPrinterData() function (* This +command is currently unimplemented). +.TP 0.2i +\(bu +\fBenumjobs <printer>\fR +- List the jobs and status of a given printer. +This command corresponds to the MS Platform SDK EnumJobs() +function (* This command is currently unimplemented). +.TP 0.2i +\(bu +\fBenumports [level]\fR +- Executes an EnumPorts() call using the specified +info level. Currently only info levels 1 and 2 are supported. +.TP 0.2i +\(bu +\fBenumdrivers [level]\fR +- Execute an EnumPrinterDrivers() call. This lists the various installed +printer drivers for all architectures. Refer to the MS Platform SDK +documentation for more details of the various flags and calling +options. Currently supported info levels are 1, 2, and 3. +.TP 0.2i +\(bu +\fBenumprinters [level]\fR +- Execute an EnumPrinters() call. This lists the various installed +and share printers. Refer to the MS Platform SDK documentation for +more details of the various flags and calling options. Currently +supported info levels are 0, 1, and 2. +.TP 0.2i +\(bu +\fBgetdata <printername>\fR +- Retrieve the data for a given printer setting. See +the \fBenumdata\fR command for more information. +This command corresponds to the GetPrinterData() MS Platform +SDK function (* This command is currently unimplemented). +.TP 0.2i +\(bu +\fBgetdriver <printername>\fR +- Retrieve the printer driver information (such as driver file, +config file, dependent files, etc...) for +the given printer. This command corresponds to the GetPrinterDriver() +MS Platform SDK function. Currently info level 1, 2, and 3 are supported. +.TP 0.2i +\(bu +\fBgetdriverdir <arch>\fR +- Execute a GetPrinterDriverDirectory() +RPC to retreive the SMB share name and subdirectory for +storing printer driver files for a given architecture. Possible +values for \fIarch\fR are "Windows 4.0" +(for Windows 95/98), "Windows NT x86", "Windows NT PowerPC", "Windows +Alpha_AXP", and "Windows NT R4000". +.TP 0.2i +\(bu +\fBgetprinter <printername>\fR +- Retrieve the current printer information. This command +corresponds to the GetPrinter() MS Platform SDK function. +.TP 0.2i +\(bu +\fBopenprinter <printername>\fR +- Execute an OpenPrinterEx() and ClosePrinter() RPC +against a given printer. +.TP 0.2i +\(bu +\fBsetdriver <printername> <drivername>\fR +- Execute a SetPrinter() command to update the printer driver associated +with an installed printer. The printer driver must already be correctly +installed on the print server. + +See also the \fBenumprinters\fR and +\fBenumdrivers\fR commands for obtaining a list of +of installed printers and drivers. +.PP +\fBGENERAL OPTIONS\fR +.PP +.TP 0.2i +\(bu +\fBdebuglevel\fR - Set the current debug level +used to log information. +.TP 0.2i +\(bu +\fBhelp (?)\fR - Print a listing of all +known commands or extended help on a particular command. +.TP 0.2i +\(bu +\fBquit (exit)\fR - Exit \fBrpcclient +\fR\&. +.SH "BUGS" +.PP +\fBrpcclient\fR is designed as a developer testing tool +and may not be robust in certain areas (such as command line parsing). +It has been known to generate a core dump upon failures when invalid +parameters where passed to the interpreter. +.PP +From Luke Leighton's original rpcclient man page: +.PP +\fB"WARNING!\fR The MSRPC over SMB code has +been developed from examining Network traces. No documentation is +available from the original creators (Microsoft) on how MSRPC over +SMB works, or how the individual MSRPC services work. Microsoft's +implementation of these services has been demonstrated (and reported) +to be... a bit flaky in places. +.PP +The development of Samba's implementation is also a bit rough, +and as more of the services are understood, it can even result in +versions of \fBsmbd(8)\fR and \fBrpcclient(1)\fR +that are incompatible for some commands or services. Additionally, +the developers are sending reports to Microsoft, and problems found +or reported to Microsoft are fixed in Service Packs, which may +result in incompatibilities." +.SH "VERSION" +.PP +This man page is correct for version 2.2 of the Samba +suite. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original rpcclient man page was written by Matthew +Geddes, Luke Kenneth Casson Leighton, and rewritten by Gerald Carter. +The conversion to DocBook for Samba 2.2 was done by Gerald +Carter. diff --git a/docs/manpages/samba.7 b/docs/manpages/samba.7 index 0c81f736b6e..ff16ff7c915 100644 --- a/docs/manpages/samba.7 +++ b/docs/manpages/samba.7 @@ -1,190 +1,141 @@ -.TH SAMBA 7 29/3/95 Samba Samba +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SAMBA" "7" "06 December 2001" "" "" .SH NAME -Samba \- a LanManager like fileserver for Unix +SAMBA \- A Windows SMB/CIFS fileserver for UNIX .SH SYNOPSIS -.B Samba -.SH DESCRIPTION -The -.B Samba -software suite is a collection of programs that implements the SMB -protocol for unix systems. This protocol is sometimes also referred to -as the LanManager or Netbios protocol. - -.SH COMPONENTS - -The Samba suite is made up of several components. Each component is -described in a separate manual page. It is strongly recommended that -you read the documentation that comes with Samba and the manual pages -of those components that you use. If the manual pages aren't clear -enough then please send me a patch! - -The smbd(8) daemon provides the file and print services to SMB clents, -such as Windows for Workgroups, Windows NT or LanManager. The -configuration file for this daemon is described in smb.conf(5). - -The nmbd(8) daemon provides Netbios nameserving and browsing -support. It can also be run interactively to query other name service -daemons. - -The smbclient(1) program implements a simple ftp-like client. This is -useful for accessing SMB shares on other compatible servers (such as -WfWg), and can also be used to allow a unix box to print to a printer -attached to any SMB server (such as a PC running WfWg). - -The testparm(1) utility allows you to test your smb.conf(5) -configuration file. - -The smbstatus(1) utility allows you to tell who is currently using the -smbd(8) server. - -.SH AVAILABILITY - -The Samba software suite is licensed under the Gnu Public License. A -copy of that license should have come with the package. You are -encouraged to distribute copies of the Samba suite, but please keep it -intact. - -The latest version of the Samba suite can be obtained via anonymous -ftp from nimbus.anu.edu.au in the directory pub/tridge/samba/. It is -also available on several mirror sites worldwide. - -You may also find useful information about Samba on the newsgroup -comp.protocols.smb and the Samba mailing list. Details on how to join -the mailing list are given in the README file that comes with Samba. - -If you have access to a WWW viewer (such as Netscape or Mosaic) then -you will also find lots of useful information, including back issues -of the Samba mailing list, at http://lake.canberra.edu.au/pub/samba/ - -.SH AUTHOR - -The main author of the Samba suite is Andrew Tridgell. He may be -contacted via e-mail at samba-bugs@anu.edu.au. - -There have also been an enourmous number of contributors to Samba from -all over the world. A partial list of these contributors is included -in the CREDITS section below. The list is, however, badly out of -date. More up to date info may be obtained from the change-log that -comes with the Samba source code. - -.SH CONTRIBUTIONS - -If you wish to contribute to the Samba project, then I suggest you -join the Samba mailing list. - -If you have patches to submit or bugs to report then you may mail them -directly to samba-bugs@anu.edu.au. Note, however, that due to the -enourmous popularity of this package I may take some time to repond to -mail. I prefer patches in "diff -u" format. - -.SH CREDITS - -Contributors to the project are (in alphabetical order by email address): - -(NOTE: This list is very out of date) - - Adams, Graham - (gadams@ddrive.demon.co.uk) - Allison, Jeremy - (jeremy@netcom.com) - Andrus, Ross - (ross@augie.insci.com) - Auer, Karl - (Karl.Auer@anu.edu.au) - Bogstad, Bill - (bogstad@cs.jhu.edu) - Boreham, Bryan - (Bryan@alex.com) - Boreham, David - (davidb@ndl.co.uk) - Butler, Michael - (imb@asstdc.scgt.oz.au) - ??? - (charlie@edina.demon.co.uk) - Chua, Michael - (lpc@solomon.technet.sg) - Cochran, Marc - (mcochran@wellfleet.com) - Dey, Martin N - (mnd@netmgrs.co.uk) - Errath, Maximilian - (errath@balu.kfunigraz.ac.at) - Fisher, Lee - (leefi@microsoft.com) - Foderaro, Sean - (jkf@frisky.Franz.COM) - Greer, Brad - (brad@cac.washington.edu) - Griffith, Michael A - (grif@cs.ucr.edu) - Grosen, Mark - (MDGrosen@spectron.COM) - ???? - (gunjkoa@dep.sa.gov.au) - Haapanen, Tom - (tomh@metrics.com) - Hench, Mike - (hench@cae.uwm.edu) - Horstman, Mark A - (mh2620@sarek.sbc.com) - Hudson, Tim - (tim.hudson@gslmail.mincom.oz.au) - Hulthen, Erik Magnus - (magnus@axiom.se) - ??? - (imb@asstdc.scgt.oz.au) - Iversen, Per Steinar - (iversen@dsfys1.fi.uib.no) - Kaara, Pasi - (ppk@atk.tpo.fi) - Karman, Merik - (merik@blackadder.dsh.oz.au) - Kiff, Martin - (mgk@newton.npl.co.uk) - Kiick, Chris - (cjkiick@flinx.b11.ingr.com) - Kukulies, Christoph - (kuku@acds.physik.rwth-aachen.de) - ??? - (lance@fox.com) - Lendecke, Volker - (lendecke@namu01.gwdg.de) - ??? - (lonnie@itg.ti.com) - Mahoney, Paul Thomas - (ptm@xact1.xact.com) - Mauelshagen, Heinz - (mauelsha@ez.da.telekom.de) - Merrick, Barry G - (bgm@atml.co.uk) - Mol, Marcel - (marcel@fanout.et.tudeflt.nl) - ??? - (njw@cpsg.com.au) - ??? - (noses@oink.rhein.de) - Owens, John - (john@micros.com) - Pierson, Jacques - (pierson@ketje.enet.dec.com) - Powell, Mark - (mark@scot1.ucsalf.ac.uk) - Reiz, Steven - (sreiz@aie.nl) - Schlaeger, Joerg - (joergs@toppoint.de) - S{rkel{, Vesa - (vesku@rankki.kcl.fi) - Tridgell, Andrew - (samba-bugs@anu.edu.au) - Troyer, Dean - (troyer@saifr00.ateng.az.honeywell.com) - Wakelin, Ross - (rossw@march.co.uk) - Wessels, Stefan - (SWESSELS@dos-lan.cs.up.ac.za) - Young, Ian A - (iay@threel.co.uk) - van der Zwan, Paul - (paulzn@olivetti.nl) - +.sp +\fBSamba\fR +.SH "DESCRIPTION" +.PP +The Samba software suite is a collection of programs +that implements the Server Message Block (commonly abbreviated +as SMB) protocol for UNIX systems. This protocol is sometimes +also referred to as the Common Internet File System (CIFS), +LanManager or NetBIOS protocol. +.TP +\fBsmbd\fR +The \fBsmbd \fR +daemon provides the file and print services to +SMB clients, such as Windows 95/98, Windows NT, Windows +for Workgroups or LanManager. The configuration file +for this daemon is described in \fIsmb.conf\fR +.TP +\fBnmbd\fR +The \fBnmbd\fR +daemon provides NetBIOS nameserving and browsing +support. The configuration file for this daemon +is described in \fIsmb.conf\fR +.TP +\fBsmbclient\fR +The \fBsmbclient\fR +program implements a simple ftp-like client. This +is useful for accessing SMB shares on other compatible +servers (such as Windows NT), and can also be used +to allow a UNIX box to print to a printer attached to +any SMB server (such as a PC running Windows NT). +.TP +\fBtestparm\fR +The \fBtestparm\fR +utility is a simple syntax checker for Samba's +\fIsmb.conf\fRconfiguration file. +.TP +\fBtestprns\fR +The \fBtestprns\fR +utility supports testing printer names defined +in your \fIprintcap>\fR file used +by Samba. +.TP +\fBsmbstatus\fR +The \fBsmbstatus\fR +tool provides access to information about the +current connections to \fBsmbd\fR. +.TP +\fBnmblookup\fR +The \fBnmblookup\fR +tools allows NetBIOS name queries to be made +from a UNIX host. +.TP +\fBmake_smbcodepage\fR +The \fBmake_smbcodepage\fR +utility provides a means of creating SMB code page +definition files for your \fBsmbd\fR server. +.TP +\fBsmbpasswd\fR +The \fBsmbpasswd\fR +command is a tool for changing LanMan and Windows NT +password hashes on Samba and Windows NT servers. +.SH "COMPONENTS" +.PP +The Samba suite is made up of several components. Each +component is described in a separate manual page. It is strongly +recommended that you read the documentation that comes with Samba +and the manual pages of those components that you use. If the +manual pages aren't clear enough then please send a patch or +bug report to samba@samba.org <URL:mailto:samba@samba.org> +.SH "AVAILABILITY" +.PP +The Samba software suite is licensed under the +GNU Public License(GPL). A copy of that license should +have come with the package in the file COPYING. You are +encouraged to distribute copies of the Samba suite, but +please obey the terms of this license. +.PP +The latest version of the Samba suite can be +obtained via anonymous ftp from samba.org in the +directory pub/samba/. It is also available on several +mirror sites worldwide. +.PP +You may also find useful information about Samba +on the newsgroup comp.protocol.smb <URL:news:comp.protocols.smb> and the Samba mailing +list. Details on how to join the mailing list are given in +the README file that comes with Samba. +.PP +If you have access to a WWW viewer (such as Netscape +or Mosaic) then you will also find lots of useful information, +including back issues of the Samba mailing list, at +http://lists.samba.org <URL:http://lists.samba.org/>. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of the +Samba suite. +.SH "CONTRIBUTIONS" +.PP +If you wish to contribute to the Samba project, +then I suggest you join the Samba mailing list at +http://lists.samba.org <URL:http://lists.samba.org/>. +.PP +If you have patches to submit or bugs to report +then you may mail them directly to samba-patches@samba.org. +Note, however, that due to the enormous popularity of this +package the Samba Team may take some time to respond to mail. We +prefer patches in \fBdiff -u\fR format. +.SH "CONTRIBUTORS" +.PP +Contributors to the project are now too numerous +to mention here but all deserve the thanks of all Samba +users. To see a full list, look at ftp://samba.org/pub/samba/alpha/change-log <URL:ftp://samba.org/pub/samba/alpha/change-log> +for the pre-CVS changes and at ftp://samba.org/pub/samba/alpha/cvs.log <URL:ftp://samba.org/pub/samba/alpha/cvs.log> +for the contributors to Samba post-CVS. CVS is the Open Source +source code control system used by the Samba Team to develop +Samba. The project would have been unmanageable without it. +.PP +In addition, several commercial organizations now help +fund the Samba Team with money and equipment. For details see +the Samba Web pages at http://samba.org/samba/samba-thanks.html. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smb.conf.5 b/docs/manpages/smb.conf.5 index 933d71ff0c3..9d88615f3f8 100644 --- a/docs/manpages/smb.conf.5 +++ b/docs/manpages/smb.conf.5 @@ -1,2719 +1,7372 @@ -.TH SMB.CONF 5 11/10/94 smb.conf smb.conf +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMB.CONF" "5" "06 December 2001" "" "" .SH NAME -smb.conf \- configuration file for smbd -.SH SYNOPSIS -.B smb.conf -.SH DESCRIPTION -The -.B smb.conf -file is a configuration file for the Samba suite. - -.B smb.conf -contains runtime configuration information for the -.B smbd -program. The -.B smbd -program provides LanManager-like services to clients -using the SMB protocol. - -.SH FILE FORMAT -The file consists of sections and parameters. A section begins with the -name of the section in square brackets and continues until the next -section begins. Sections contain parameters of the form 'name = value'. - -The file is line-based - that is, each newline-terminated line represents -either a comment, a section name or a parameter. - +smb.conf \- The configuration file for the Samba suite +.SH "SYNOPSIS" +.PP +The \fIsmb.conf\fR file is a configuration +file for the Samba suite. \fIsmb.conf\fR contains +runtime configuration information for the Samba programs. The +\fIsmb.conf\fR file is designed to be configured and +administered by the \fBswat(8)\fR +program. The complete description of the file format and +possible parameters held within are here for reference purposes. +.SH "FILE FORMAT" +.PP +The file consists of sections and parameters. A section +begins with the name of the section in square brackets and continues +until the next section begins. Sections contain parameters of the +form +.PP +\fIname\fR = \fIvalue +\fR.PP +The file is line-based - that is, each newline-terminated +line represents either a comment, a section name or a parameter. +.PP Section and parameter names are not case sensitive. - -Only the first equals sign in a parameter is significant. Whitespace before -or after the first equals sign is discarded. Leading, trailing and internal -whitespace in section and parameter names is irrelevant. Leading and -trailing whitespace in a parameter value is discarded. Internal whitespace -within a parameter value is retained verbatim. - -Any line beginning with a semicolon is ignored, as are lines containing -only whitespace. - -Any line ending in a \\ is "continued" on the next line in the -customary unix fashion. - -The values following the equals sign in parameters are all either a string -(no quotes needed) or a boolean, which may be given as yes/no, 0/1 or -true/false. Case is not significant in boolean values, but is preserved -in string values. Some items such as create modes are numeric. -.SH SERVICE DESCRIPTIONS -Each section in the configuration file describes a service. The section name -is the service name and the parameters within the section define the service's -attributes. - -There are three special sections, [global], [homes] and [printers], which are -described under 'special sections'. The following notes apply to ordinary -service descriptions. - -A service consists of a directory to which access is being given plus a -description of the access rights which are granted to the user of the -service. Some housekeeping options are also specifiable. - -Services are either filespace services (used by the client as an extension of -their native file systems) or printable services (used by the client to access -print services on the host running the server). - -Services may be guest services, in which case no password is required to -access them. A specified guest account is used to define access privileges -in this case. - -Services other than guest services will require a password to access -them. The client provides the username. As many clients only provide -passwords and not usernames, you may specify a list of usernames to -check against the password using the "user=" option in the service -definition. - -Note that the access rights granted by the server are masked by the access -rights granted to the specified or guest user by the host system. The -server does not grant more access than the host system grants. - -The following sample section defines a file space service. The user has write -access to the path /home/bar. The service is accessed via the service name -"foo": - - [foo] +.PP +Only the first equals sign in a parameter is significant. +Whitespace before or after the first equals sign is discarded. +Leading, trailing and internal whitespace in section and parameter +names is irrelevant. Leading and trailing whitespace in a parameter +value is discarded. Internal whitespace within a parameter value +is retained verbatim. +.PP +Any line beginning with a semicolon (';') or a hash ('#') +character is ignored, as are lines containing only whitespace. +.PP +Any line ending in a '\\' is continued +on the next line in the customary UNIX fashion. +.PP +The values following the equals sign in parameters are all +either a string (no quotes needed) or a boolean, which may be given +as yes/no, 0/1 or true/false. Case is not significant in boolean +values, but is preserved in string values. Some items such as +create modes are numeric. +.SH "SECTION DESCRIPTIONS" +.PP +Each section in the configuration file (except for the +[global] section) describes a shared resource (known +as a "share"). The section name is the name of the +shared resource and the parameters within the section define +the shares attributes. +.PP +There are three special sections, [global], +[homes] and [printers], which are +described under \fBspecial sections\fR. The +following notes apply to ordinary section descriptions. +.PP +A share consists of a directory to which access is being +given plus a description of the access rights which are granted +to the user of the service. Some housekeeping options are +also specifiable. +.PP +Sections are either file share services (used by the +client as an extension of their native file systems) or +printable services (used by the client to access print services +on the host running the server). +.PP +Sections may be designated \fBguest\fR services, +in which case no password is required to access them. A specified +UNIX \fBguest account\fR is used to define access +privileges in this case. +.PP +Sections other than guest services will require a password +to access them. The client provides the username. As older clients +only provide passwords and not usernames, you may specify a list +of usernames to check against the password using the "user =" +option in the share definition. For modern clients such as +Windows 95/98/ME/NT/2000, this should not be necessary. +.PP +Note that the access rights granted by the server are +masked by the access rights granted to the specified or guest +UNIX user by the host system. The server does not grant more +access than the host system grants. +.PP +The following sample section defines a file space share. +The user has write access to the path \fI/home/bar\fR. +The share is accessed via the share name "foo": +.sp +.nf + [foo] path = /home/bar - writable = true - -The following sample section defines a printable service. The service is -readonly, but printable. That is, the only write access permitted is via -calls to open, write to and close a spool file. The 'guest ok' parameter -means access will be permitted as the default guest user (specified elsewhere): - - [aprinter] + writeable = true + + +.sp +.fi +.PP +The following sample section defines a printable share. +The share is readonly, but printable. That is, the only write +access permitted is via calls to open, write to and close a +spool file. The \fBguest ok\fR parameter means +access will be permitted as the default guest user (specified +elsewhere): +.sp +.nf + [aprinter] path = /usr/spool/public - read only = true + writeable = false printable = true - public = true - -.SH SPECIAL SECTIONS - -.SS The [global] section -.RS 3 -Parameters in this section apply to the server as a whole, or are defaults -for services which do not specifically define certain items. See the notes -under 'Parameters' for more information. + guest ok = true + + +.sp +.fi +.SH "SPECIAL SECTIONS" +.SS "THE GLOBAL SECTION" +.PP +parameters in this section apply to the server +as a whole, or are defaults for sections which do not +specifically define certain items. See the notes +under PARAMETERS for more information. +.SS "THE HOMES SECTION" +.PP +If a section called homes is included in the +configuration file, services connecting clients to their +home directories can be created on the fly by the server. +.PP +When the connection request is made, the existing +sections are scanned. If a match is found, it is used. If no +match is found, the requested section name is treated as a +user name and looked up in the local password file. If the +name exists and the correct password has been given, a share is +created by cloning the [homes] section. +.PP +Some modifications are then made to the newly +created share: +.TP 0.2i +\(bu +The share name is changed from homes to +the located username. +.TP 0.2i +\(bu +If no path was given, the path is set to +the user's home directory. +.PP +If you decide to use a \fBpath =\fR line +in your [homes] section then you may find it useful +to use the %S macro. For example : +.PP +.PP +\fBpath = /data/pchome/%S\fR +.PP +.PP +would be useful if you have different home directories +for your PCs than for UNIX access. +.PP +.PP +This is a fast and simple way to give a large number +of clients access to their home directories with a minimum +of fuss. +.PP +.PP +A similar process occurs if the requested section +name is "homes", except that the share name is not +changed to that of the requesting user. This method of using +the [homes] section works well if different users share +a client PC. +.PP +.PP +The [homes] section can specify all the parameters +a normal service section can specify, though some make more sense +than others. The following is a typical and suitable [homes] +section: +.PP +.sp +.nf + [homes] + writeable = yes + + +.sp +.fi +.PP +An important point is that if guest access is specified +in the [homes] section, all home directories will be +visible to all clients \fBwithout a password\fR. +In the very unlikely event that this is actually desirable, it +would be wise to also specify \fBread only +access\fR. +.PP +.PP +Note that the \fBbrowseable\fR flag for +auto home directories will be inherited from the global browseable +flag, not the [homes] browseable flag. This is useful as +it means setting \fBbrowseable = no\fR in +the [homes] section will hide the [homes] share but make +any auto home directories visible. +.PP +.SS "THE PRINTERS SECTION" +.PP +This section works like [homes], +but for printers. +.PP +If a [printers] section occurs in the +configuration file, users are able to connect to any printer +specified in the local host's printcap file. +.PP +When a connection request is made, the existing sections +are scanned. If a match is found, it is used. If no match is found, +but a [homes] section exists, it is used as described +above. Otherwise, the requested section name is treated as a +printer name and the appropriate printcap file is scanned to see +if the requested section name is a valid printer share name. If +a match is found, a new printer share is created by cloning +the [printers] section. +.PP +A few modifications are then made to the newly created +share: +.TP 0.2i +\(bu +The share name is set to the located printer +name +.TP 0.2i +\(bu +If no printer name was given, the printer name +is set to the located printer name +.TP 0.2i +\(bu +If the share does not permit guest access and +no username was given, the username is set to the located +printer name. +.PP +Note that the [printers] service MUST be +printable - if you specify otherwise, the server will refuse +to load the configuration file. +.PP +.PP +Typically the path specified would be that of a +world-writeable spool directory with the sticky bit set on +it. A typical [printers] entry would look like +this: +.PP +.sp +.nf + [printers] + path = /usr/spool/public + guest ok = yes + printable = yes + +.sp +.fi +.PP +All aliases given for a printer in the printcap file +are legitimate printer names as far as the server is concerned. +If your printing subsystem doesn't work like that, you will have +to set up a pseudo-printcap. This is a file consisting of one or +more lines like this: +.PP +.sp +.nf + alias|alias|alias|alias... + + +.sp +.fi +.PP +Each alias should be an acceptable printer name for +your printing subsystem. In the [global] section, specify +the new file as your printcap. The server will then only recognize +names found in your pseudo-printcap, which of course can contain +whatever aliases you like. The same technique could be used +simply to limit access to a subset of your local printers. +.PP +.PP +An alias, by the way, is defined as any component of the +first entry of a printcap record. Records are separated by newlines, +components (if there are more than one) are separated by vertical +bar symbols ('|'). +.PP +.PP +NOTE: On SYSV systems which use lpstat to determine what +printers are defined on the system you may be able to use +"printcap name = lpstat" to automatically obtain a list +of printers. See the "printcap name" option +for more details. +.PP +.SH "PARAMETERS" +.PP +parameters define the specific attributes of sections. +.PP +Some parameters are specific to the [global] section +(e.g., \fBsecurity\fR). Some parameters are usable +in all sections (e.g., \fBcreate mode\fR). All others +are permissible only in normal sections. For the purposes of the +following descriptions the [homes] and [printers] +sections will be considered normal. The letter \fBG\fR +in parentheses indicates that a parameter is specific to the +[global] section. The letter \fBS\fR +indicates that a parameter can be specified in a service specific +section. Note that all \fBS\fR parameters can also be specified in +the [global] section - in which case they will define +the default behavior for all services. +.PP +parameters are arranged here in alphabetical order - this may +not create best bedfellows, but at least you can find them! Where +there are synonyms, the preferred synonym is described, others refer +to the preferred synonym. +.SH "VARIABLE SUBSTITUTIONS" +.PP +Many of the strings that are settable in the config file +can take substitutions. For example the option "path = +/tmp/%u" would be interpreted as "path = +/tmp/john" if the user connected with the username john. +.PP +These substitutions are mostly noted in the descriptions below, +but there are some general substitutions which apply whenever they +might be relevant. These are: +.TP +\fB%S\fR +the name of the current service, if any. +.TP +\fB%P\fR +the root directory of the current service, +if any. +.TP +\fB%u\fR +user name of the current service, if any. +.TP +\fB%g\fR +primary group name of %u. +.TP +\fB%U\fR +session user name (the user name that the client +wanted, not necessarily the same as the one they got). +.TP +\fB%G\fR +primary group name of %U. +.TP +\fB%H\fR +the home directory of the user given +by %u. +.TP +\fB%v\fR +the Samba version. +.TP +\fB%h\fR +the Internet hostname that Samba is running +on. +.TP +\fB%m\fR +the NetBIOS name of the client machine +(very useful). +.TP +\fB%L\fR +the NetBIOS name of the server. This allows you +to change your config based on what the client calls you. Your +server can have a "dual personality". +.TP +\fB%M\fR +the Internet name of the client machine. +.TP +\fB%N\fR +the name of your NIS home directory server. +This is obtained from your NIS auto.map entry. If you have +not compiled Samba with the \fB--with-automount\fR +option then this value will be the same as %L. +.TP +\fB%p\fR +the path of the service's home directory, +obtained from your NIS auto.map entry. The NIS auto.map entry +is split up as "%N:%p". +.TP +\fB%R\fR +the selected protocol level after +protocol negotiation. It can be one of CORE, COREPLUS, +LANMAN1, LANMAN2 or NT1. +.TP +\fB%d\fR +The process id of the current server +process. +.TP +\fB%a\fR +the architecture of the remote +machine. Only some are recognized, and those may not be +100% reliable. It currently recognizes Samba, WfWg, Win95, +WinNT and Win2k. Anything else will be known as +"UNKNOWN". If it gets it wrong then sending a level +3 log to samba@samba.org + <URL:mailto:samba@samba.org> should allow it to be fixed. +.TP +\fB%I\fR +The IP address of the client machine. +.TP +\fB%T\fR +the current date and time. +.TP +\fB%$(\fIenvvar\fB)\fR +The value of the environment variable +\fIenvar\fR. +.PP +There are some quite creative things that can be done +with these substitutions and other smb.conf options. +.PP +.SH "NAME MANGLING" +.PP +Samba supports "name mangling" so that DOS and +Windows clients can use files that don't conform to the 8.3 format. +It can also be set to adjust the case of 8.3 format filenames. +.PP +There are several options that control the way mangling is +performed, and they are grouped here rather than listed separately. +For the defaults look at the output of the testparm program. +.PP +All of these options can be set separately for each service +(or globally, of course). +.PP +The options are: +.TP +\fBmangle case = yes/no\fR +controls if names that have characters that +aren't of the "default" case are mangled. For example, +if this is yes then a name like "Mail" would be mangled. +Default \fBno\fR. +.TP +\fBcase sensitive = yes/no\fR +controls whether filenames are case sensitive. If +they aren't then Samba must do a filename search and match on passed +names. Default \fBno\fR. +.TP +\fBdefault case = upper/lower\fR +controls what the default case is for new +filenames. Default \fBlower\fR. +.TP +\fBpreserve case = yes/no\fR +controls if new files are created with the +case that the client passes, or if they are forced to be the +"default" case. Default \fByes\fR. +.TP +\fBshort preserve case = yes/no\fR +controls if new files which conform to 8.3 syntax, +that is all in upper case and of suitable length, are created +upper case, or if they are forced to be the "default" +case. This option can be use with "preserve case = yes" +to permit long filenames to retain their case, while short names +are lowercased. Default \fByes\fR. +.PP +By default, Samba 2.2 has the same semantics as a Windows +NT server, in that it is case insensitive but case preserving. +.PP +.SH "NOTE ABOUT USERNAME/PASSWORD VALIDATION" +.PP +There are a number of ways in which a user can connect +to a service. The server uses the following steps in determining +if it will allow a connection to a specified service. If all the +steps fail, then the connection request is rejected. However, if one of the +steps succeeds, then the following steps are not checked. +.PP +If the service is marked "guest only = yes" then +steps 1 to 5 are skipped. +.IP 1. +If the client has passed a username/password +pair and that username/password pair is validated by the UNIX +system's password programs then the connection is made as that +username. Note that this includes the +\\\\server\\service%\fIusername\fR method of passing +a username. +.IP 2. +If the client has previously registered a username +with the system and now supplies a correct password for that +username then the connection is allowed. +.IP 3. +The client's NetBIOS name and any previously +used user names are checked against the supplied password, if +they match then the connection is allowed as the corresponding +user. +.IP 4. +If the client has previously validated a +username/password pair with the server and the client has passed +the validation token then that username is used. +.IP 5. +If a "user = " field is given in the +\fIsmb.conf\fR file for the service and the client +has supplied a password, and that password matches (according to +the UNIX system's password checking) with one of the usernames +from the "user =" field then the connection is made as +the username in the "user =" line. If one +of the username in the "user =" list begins with a +\&'@' then that name expands to a list of names in +the group of the same name. +.IP 6. +If the service is a guest service then a +connection is made as the username given in the "guest +account =" for the service, irrespective of the +supplied password. +.SH "COMPLETE LIST OF GLOBAL PARAMETERS" +.PP +Here is a list of all global parameters. See the section of +each parameter for details. Note that some are synonyms. +.TP 0.2i +\(bu +\fIabort shutdown script\fR +.TP 0.2i +\(bu +\fIadd printer command\fR +.TP 0.2i +\(bu +\fIadd share command\fR +.TP 0.2i +\(bu +\fIadd user script\fR +.TP 0.2i +\(bu +\fIadd machine script\fR +.TP 0.2i +\(bu +\fIallow trusted domains\fR +.TP 0.2i +\(bu +\fIannounce as\fR +.TP 0.2i +\(bu +\fIannounce version\fR +.TP 0.2i +\(bu +\fIauto services\fR +.TP 0.2i +\(bu +\fIbind interfaces only\fR +.TP 0.2i +\(bu +\fIbrowse list\fR +.TP 0.2i +\(bu +\fIchange notify timeout\fR +.TP 0.2i +\(bu +\fIchange share command\fR +.TP 0.2i +\(bu +\fIcharacter set\fR +.TP 0.2i +\(bu +\fIclient code page\fR +.TP 0.2i +\(bu +\fIcode page directory\fR +.TP 0.2i +\(bu +\fIcoding system\fR +.TP 0.2i +\(bu +\fIconfig file\fR +.TP 0.2i +\(bu +\fIdeadtime\fR +.TP 0.2i +\(bu +\fIdebug hires timestamp\fR +.TP 0.2i +\(bu +\fIdebug pid\fR +.TP 0.2i +\(bu +\fIdebug timestamp\fR +.TP 0.2i +\(bu +\fIdebug uid\fR +.TP 0.2i +\(bu +\fIdebuglevel\fR +.TP 0.2i +\(bu +\fIdefault\fR +.TP 0.2i +\(bu +\fIdefault service\fR +.TP 0.2i +\(bu +\fIdelete printer command\fR +.TP 0.2i +\(bu +\fIdelete share command\fR +.TP 0.2i +\(bu +\fIdelete user script\fR +.TP 0.2i +\(bu +\fIdfree command\fR +.TP 0.2i +\(bu +\fIdisable spoolss\fR +.TP 0.2i +\(bu +\fIdns proxy\fR +.TP 0.2i +\(bu +\fIdomain admin group\fR +.TP 0.2i +\(bu +\fIdomain guest group\fR +.TP 0.2i +\(bu +\fIdomain logons\fR +.TP 0.2i +\(bu +\fIdomain master\fR +.TP 0.2i +\(bu +\fIencrypt passwords\fR +.TP 0.2i +\(bu +\fIenhanced browsing\fR +.TP 0.2i +\(bu +\fIenumports command\fR +.TP 0.2i +\(bu +\fIgetwd cache\fR +.TP 0.2i +\(bu +\fIhide local users\fR +.TP 0.2i +\(bu +\fIhide unreadable\fR +.TP 0.2i +\(bu +\fIhomedir map\fR +.TP 0.2i +\(bu +\fIhost msdfs\fR +.TP 0.2i +\(bu +\fIhosts equiv\fR +.TP 0.2i +\(bu +\fIinterfaces\fR +.TP 0.2i +\(bu +\fIkeepalive\fR +.TP 0.2i +\(bu +\fIkernel oplocks\fR +.TP 0.2i +\(bu +\fIlanman auth\fR +.TP 0.2i +\(bu +\fIlarge readwrite\fR +.TP 0.2i +\(bu +\fIldap admin dn\fR +.TP 0.2i +\(bu +\fIldap filter\fR +.TP 0.2i +\(bu +\fIldap port\fR +.TP 0.2i +\(bu +\fIldap server\fR +.TP 0.2i +\(bu +\fIldap ssl\fR +.TP 0.2i +\(bu +\fIldap suffix\fR +.TP 0.2i +\(bu +\fIlm announce\fR +.TP 0.2i +\(bu +\fIlm interval\fR +.TP 0.2i +\(bu +\fIload printers\fR +.TP 0.2i +\(bu +\fIlocal master\fR +.TP 0.2i +\(bu +\fIlock dir\fR +.TP 0.2i +\(bu +\fIlock directory\fR +.TP 0.2i +\(bu +\fIlog file\fR +.TP 0.2i +\(bu +\fIlog level\fR +.TP 0.2i +\(bu +\fIlogon drive\fR +.TP 0.2i +\(bu +\fIlogon home\fR +.TP 0.2i +\(bu +\fIlogon path\fR +.TP 0.2i +\(bu +\fIlogon script\fR +.TP 0.2i +\(bu +\fIlpq cache time\fR +.TP 0.2i +\(bu +\fImachine password timeout\fR +.TP 0.2i +\(bu +\fImangled stack\fR +.TP 0.2i +\(bu +\fImap to guest\fR +.TP 0.2i +\(bu +\fImax disk size\fR +.TP 0.2i +\(bu +\fImax log size\fR +.TP 0.2i +\(bu +\fImax mux\fR +.TP 0.2i +\(bu +\fImax open files\fR +.TP 0.2i +\(bu +\fImax protocol\fR +.TP 0.2i +\(bu +\fImax smbd processes\fR +.TP 0.2i +\(bu +\fImax ttl\fR +.TP 0.2i +\(bu +\fImax wins ttl\fR +.TP 0.2i +\(bu +\fImax xmit\fR +.TP 0.2i +\(bu +\fImessage command\fR +.TP 0.2i +\(bu +\fImin passwd length\fR +.TP 0.2i +\(bu +\fImin password length\fR +.TP 0.2i +\(bu +\fImin protocol\fR +.TP 0.2i +\(bu +\fImin wins ttl\fR +.TP 0.2i +\(bu +\fIname resolve order\fR +.TP 0.2i +\(bu +\fInetbios aliases\fR +.TP 0.2i +\(bu +\fInetbios name\fR +.TP 0.2i +\(bu +\fInetbios scope\fR +.TP 0.2i +\(bu +\fInis homedir\fR +.TP 0.2i +\(bu +\fInt pipe support\fR +.TP 0.2i +\(bu +\fInt smb support\fR +.TP 0.2i +\(bu +\fInull passwords\fR +.TP 0.2i +\(bu +\fIobey pam restrictions\fR +.TP 0.2i +\(bu +\fIoplock break wait time\fR +.TP 0.2i +\(bu +\fIos level\fR +.TP 0.2i +\(bu +\fIos2 driver map\fR +.TP 0.2i +\(bu +\fIpam password change\fR +.TP 0.2i +\(bu +\fIpanic action\fR +.TP 0.2i +\(bu +\fIpasswd chat\fR +.TP 0.2i +\(bu +\fIpasswd chat debug\fR +.TP 0.2i +\(bu +\fIpasswd program\fR +.TP 0.2i +\(bu +\fIpassword level\fR +.TP 0.2i +\(bu +\fIpassword server\fR +.TP 0.2i +\(bu +\fIprefered master\fR +.TP 0.2i +\(bu +\fIpreferred master\fR +.TP 0.2i +\(bu +\fIpreload\fR +.TP 0.2i +\(bu +\fIprintcap\fR +.TP 0.2i +\(bu +\fIprintcap name\fR +.TP 0.2i +\(bu +\fIprinter driver file\fR +.TP 0.2i +\(bu +\fIprotocol\fR +.TP 0.2i +\(bu +\fIread bmpx\fR +.TP 0.2i +\(bu +\fIread raw\fR +.TP 0.2i +\(bu +\fIread size\fR +.TP 0.2i +\(bu +\fIremote announce\fR +.TP 0.2i +\(bu +\fIremote browse sync\fR +.TP 0.2i +\(bu +\fIrestrict anonymous\fR +.TP 0.2i +\(bu +\fIroot\fR +.TP 0.2i +\(bu +\fIroot dir\fR +.TP 0.2i +\(bu +\fIroot directory\fR +.TP 0.2i +\(bu +\fIsecurity\fR +.TP 0.2i +\(bu +\fIserver string\fR +.TP 0.2i +\(bu +\fIshow add printer wizard\fR +.TP 0.2i +\(bu +\fIshutdown script\fR +.TP 0.2i +\(bu +\fIsmb passwd file\fR +.TP 0.2i +\(bu +\fIsocket address\fR +.TP 0.2i +\(bu +\fIsocket options\fR +.TP 0.2i +\(bu +\fIsource environment\fR +.TP 0.2i +\(bu +\fIssl\fR +.TP 0.2i +\(bu +\fIssl CA certDir\fR +.TP 0.2i +\(bu +\fIssl CA certFile\fR +.TP 0.2i +\(bu +\fIssl ciphers\fR +.TP 0.2i +\(bu +\fIssl client cert\fR +.TP 0.2i +\(bu +\fIssl client key\fR +.TP 0.2i +\(bu +\fIssl compatibility\fR +.TP 0.2i +\(bu +\fIssl egd socket\fR +.TP 0.2i +\(bu +\fIssl entropy bytes\fR +.TP 0.2i +\(bu +\fIssl entropy file\fR +.TP 0.2i +\(bu +\fIssl hosts\fR +.TP 0.2i +\(bu +\fIssl hosts resign\fR +.TP 0.2i +\(bu +\fIssl require clientcert\fR +.TP 0.2i +\(bu +\fIssl require servercert\fR +.TP 0.2i +\(bu +\fIssl server cert\fR +.TP 0.2i +\(bu +\fIssl server key\fR +.TP 0.2i +\(bu +\fIssl version\fR +.TP 0.2i +\(bu +\fIstat cache\fR +.TP 0.2i +\(bu +\fIstat cache size\fR +.TP 0.2i +\(bu +\fIstrip dot\fR +.TP 0.2i +\(bu +\fIsyslog\fR +.TP 0.2i +\(bu +\fIsyslog only\fR +.TP 0.2i +\(bu +\fItemplate homedir\fR +.TP 0.2i +\(bu +\fItemplate shell\fR +.TP 0.2i +\(bu +\fItime offset\fR +.TP 0.2i +\(bu +\fItime server\fR +.TP 0.2i +\(bu +\fItimestamp logs\fR +.TP 0.2i +\(bu +\fItotal print jobs\fR +.TP 0.2i +\(bu +\fIunix password sync\fR +.TP 0.2i +\(bu +\fIupdate encrypted\fR +.TP 0.2i +\(bu +\fIuse mmap\fR +.TP 0.2i +\(bu +\fIuse rhosts\fR +.TP 0.2i +\(bu +\fIusername level\fR +.TP 0.2i +\(bu +\fIusername map\fR +.TP 0.2i +\(bu +\fIutmp\fR +.TP 0.2i +\(bu +\fIutmp directory\fR +.TP 0.2i +\(bu +\fIvalid chars\fR +.TP 0.2i +\(bu +\fIwinbind cache time\fR +.TP 0.2i +\(bu +\fIwinbind enum users\fR +.TP 0.2i +\(bu +\fIwinbind enum groups\fR +.TP 0.2i +\(bu +\fIwinbind gid\fR +.TP 0.2i +\(bu +\fIwinbind separator\fR +.TP 0.2i +\(bu +\fIwinbind uid\fR +.TP 0.2i +\(bu +\fIwins hook\fR +.TP 0.2i +\(bu +\fIwins proxy\fR +.TP 0.2i +\(bu +\fIwins server\fR +.TP 0.2i +\(bu +\fIwins support\fR +.TP 0.2i +\(bu +\fIworkgroup\fR +.TP 0.2i +\(bu +\fIwrite raw\fR +.SH "COMPLETE LIST OF SERVICE PARAMETERS" +.PP +Here is a list of all service parameters. See the section on +each parameter for details. Note that some are synonyms. +.TP 0.2i +\(bu +\fIadmin users\fR +.TP 0.2i +\(bu +\fIallow hosts\fR +.TP 0.2i +\(bu +\fIavailable\fR +.TP 0.2i +\(bu +\fIblocking locks\fR +.TP 0.2i +\(bu +\fIbrowsable\fR +.TP 0.2i +\(bu +\fIbrowseable\fR +.TP 0.2i +\(bu +\fIcase sensitive\fR +.TP 0.2i +\(bu +\fIcasesignames\fR +.TP 0.2i +\(bu +\fIcomment\fR +.TP 0.2i +\(bu +\fIcopy\fR +.TP 0.2i +\(bu +\fIcreate mask\fR +.TP 0.2i +\(bu +\fIcreate mode\fR +.TP 0.2i +\(bu +\fIdefault case\fR +.TP 0.2i +\(bu +\fIdelete readonly\fR +.TP 0.2i +\(bu +\fIdelete veto files\fR +.TP 0.2i +\(bu +\fIdeny hosts\fR +.TP 0.2i +\(bu +\fIdirectory\fR +.TP 0.2i +\(bu +\fIdirectory mask\fR +.TP 0.2i +\(bu +\fIdirectory mode\fR +.TP 0.2i +\(bu +\fIdirectory security mask\fR +.TP 0.2i +\(bu +\fIdont descend\fR +.TP 0.2i +\(bu +\fIdos filemode\fR +.TP 0.2i +\(bu +\fIdos filetime resolution\fR +.TP 0.2i +\(bu +\fIdos filetimes\fR +.TP 0.2i +\(bu +\fIexec\fR +.TP 0.2i +\(bu +\fIfake directory create times\fR +.TP 0.2i +\(bu +\fIfake oplocks\fR +.TP 0.2i +\(bu +\fIfollow symlinks\fR +.TP 0.2i +\(bu +\fIforce create mode\fR +.TP 0.2i +\(bu +\fIforce directory mode\fR +.TP 0.2i +\(bu +\fIforce directory security mode\fR +.TP 0.2i +\(bu +\fIforce group\fR +.TP 0.2i +\(bu +\fIforce security mode\fR +.TP 0.2i +\(bu +\fIforce user\fR +.TP 0.2i +\(bu +\fIfstype\fR +.TP 0.2i +\(bu +\fIgroup\fR +.TP 0.2i +\(bu +\fIguest account\fR +.TP 0.2i +\(bu +\fIguest ok\fR +.TP 0.2i +\(bu +\fIguest only\fR +.TP 0.2i +\(bu +\fIhide dot files\fR +.TP 0.2i +\(bu +\fIhide files\fR +.TP 0.2i +\(bu +\fIhosts allow\fR +.TP 0.2i +\(bu +\fIhosts deny\fR +.TP 0.2i +\(bu +\fIinclude\fR +.TP 0.2i +\(bu +\fIinherit permissions\fR +.TP 0.2i +\(bu +\fIinvalid users\fR +.TP 0.2i +\(bu +\fIlevel2 oplocks\fR +.TP 0.2i +\(bu +\fIlocking\fR +.TP 0.2i +\(bu +\fIlppause command\fR +.TP 0.2i +\(bu +\fIlpq command\fR +.TP 0.2i +\(bu +\fIlpresume command\fR +.TP 0.2i +\(bu +\fIlprm command\fR +.TP 0.2i +\(bu +\fImagic output\fR +.TP 0.2i +\(bu +\fImagic script\fR +.TP 0.2i +\(bu +\fImangle case\fR +.TP 0.2i +\(bu +\fImangled map\fR +.TP 0.2i +\(bu +\fImangled names\fR +.TP 0.2i +\(bu +\fImangling char\fR +.TP 0.2i +\(bu +\fImap archive\fR +.TP 0.2i +\(bu +\fImap hidden\fR +.TP 0.2i +\(bu +\fImap system\fR +.TP 0.2i +\(bu +\fImax connections\fR +.TP 0.2i +\(bu +\fImax print jobs\fR +.TP 0.2i +\(bu +\fImin print space\fR +.TP 0.2i +\(bu +\fImsdfs root\fR +.TP 0.2i +\(bu +\fInt acl support\fR +.TP 0.2i +\(bu +\fIonly guest\fR +.TP 0.2i +\(bu +\fIonly user\fR +.TP 0.2i +\(bu +\fIoplock contention limit\fR +.TP 0.2i +\(bu +\fIoplocks\fR +.TP 0.2i +\(bu +\fIpath\fR +.TP 0.2i +\(bu +\fIposix locking\fR +.TP 0.2i +\(bu +\fIpostexec\fR +.TP 0.2i +\(bu +\fIpostscript\fR +.TP 0.2i +\(bu +\fIpreexec\fR +.TP 0.2i +\(bu +\fIpreexec close\fR +.TP 0.2i +\(bu +\fIpreserve case\fR +.TP 0.2i +\(bu +\fIprint command\fR +.TP 0.2i +\(bu +\fIprint ok\fR +.TP 0.2i +\(bu +\fIprintable\fR +.TP 0.2i +\(bu +\fIprinter\fR +.TP 0.2i +\(bu +\fIprinter admin\fR +.TP 0.2i +\(bu +\fIprinter driver\fR +.TP 0.2i +\(bu +\fIprinter driver location\fR +.TP 0.2i +\(bu +\fIprinter name\fR +.TP 0.2i +\(bu +\fIprinting\fR +.TP 0.2i +\(bu +\fIpublic\fR +.TP 0.2i +\(bu +\fIqueuepause command\fR +.TP 0.2i +\(bu +\fIqueueresume command\fR +.TP 0.2i +\(bu +\fIread list\fR +.TP 0.2i +\(bu +\fIread only\fR +.TP 0.2i +\(bu +\fIroot postexec\fR +.TP 0.2i +\(bu +\fIroot preexec\fR +.TP 0.2i +\(bu +\fIroot preexec close\fR +.TP 0.2i +\(bu +\fIsecurity mask\fR +.TP 0.2i +\(bu +\fIset directory\fR +.TP 0.2i +\(bu +\fIshort preserve case\fR +.TP 0.2i +\(bu +\fIstatus\fR +.TP 0.2i +\(bu +\fIstrict allocate\fR +.TP 0.2i +\(bu +\fIstrict locking\fR +.TP 0.2i +\(bu +\fIstrict sync\fR +.TP 0.2i +\(bu +\fIsync always\fR +.TP 0.2i +\(bu +\fIuse client driver\fR +.TP 0.2i +\(bu +\fIuser\fR +.TP 0.2i +\(bu +\fIusername\fR +.TP 0.2i +\(bu +\fIusers\fR +.TP 0.2i +\(bu +\fIvalid users\fR +.TP 0.2i +\(bu +\fIveto files\fR +.TP 0.2i +\(bu +\fIveto oplock files\fR +.TP 0.2i +\(bu +\fIvfs object\fR +.TP 0.2i +\(bu +\fIvfs options\fR +.TP 0.2i +\(bu +\fIvolume\fR +.TP 0.2i +\(bu +\fIwide links\fR +.TP 0.2i +\(bu +\fIwritable\fR +.TP 0.2i +\(bu +\fIwrite cache size\fR +.TP 0.2i +\(bu +\fIwrite list\fR +.TP 0.2i +\(bu +\fIwrite ok\fR +.TP 0.2i +\(bu +\fIwriteable\fR +.SH "EXPLANATION OF EACH PARAMETER" +.TP +\fBabort shutdown script (G)\fR +\fBThis parameter only exists in the HEAD cvs branch\fR +This a full path name to a script called by +\fBsmbd(8)\fRthat +should stop a shutdown procedure issued by the \fIshutdown script\fR. + +This command will be run as user. + +Default: \fBNone\fR. + +Example: \fBabort shutdown script = /sbin/shutdown -c\fR +.TP +\fBadd printer command (G)\fR +With the introduction of MS-RPC based printing +support for Windows NT/2000 clients in Samba 2.2, The MS Add +Printer Wizard (APW) icon is now also available in the +"Printers..." folder displayed a share listing. The APW +allows for printers to be add remotely to a Samba or Windows +NT/2000 print server. + +For a Samba host this means that the printer must be +physically added to the underlying printing system. The \fIadd +printer command\fR defines a script to be run which +will perform the necessary operations for adding the printer +to the print system and to add the appropriate service definition +to the \fIsmb.conf\fR file in order that it can be +shared by \fBsmbd(8)\fR +. + +The \fIadd printer command\fR is +automatically invoked with the following parameter (in +order: +.RS +.TP 0.2i +\(bu +\fIprinter name\fR +.TP 0.2i +\(bu +\fIshare name\fR +.TP 0.2i +\(bu +\fIport name\fR +.TP 0.2i +\(bu +\fIdriver name\fR +.TP 0.2i +\(bu +\fIlocation\fR +.TP 0.2i +\(bu +\fIWindows 9x driver location\fR .RE - -.SS The [homes] section -.RS 3 -If a section called 'homes' is included in the configuration file, services -connecting clients to their home directories can be created on the fly by the -server. - -When the connection request is made, the existing services are scanned. If a -match is found, it is used. If no match is found, the requested service name is -treated as a user name and looked up in the local passwords file. If the -name exists and the correct password has been given, a service is created -by cloning the [homes] section. - -Some modifications are then made to the newly created section: - -.RS 3 -The service name is changed from 'homes' to the located username - -If no path was given, the path is set to the user's home directory. +.PP +All parameters are filled in from the PRINTER_INFO_2 structure sent +by the Windows NT/2000 client with one exception. The "Windows 9x +driver location" parameter is included for backwards compatibility +only. The remaining fields in the structure are generated from answers +to the APW questions. +.PP +.PP +Once the \fIadd printer command\fR has +been executed, \fBsmbd\fR will reparse the \fI smb.conf\fR to determine if the share defined by the APW +exists. If the sharename is still invalid, then \fBsmbd +\fRwill return an ACCESS_DENIED error to the client. +.PP +.PP +See also \fI delete printer command\fR, \fIprinting\fR, +\fIshow add +printer wizard\fR +.PP +.PP +Default: \fBnone\fR +.PP +.PP +Example: \fBaddprinter command = /usr/bin/addprinter +\fR.PP +.TP +\fBadd share command (G)\fR +Samba 2.2.0 introduced the ability to dynamically +add and delete shares via the Windows NT 4.0 Server Manager. The +\fIadd share command\fR is used to define an +external program or script which will add a new service definition +to \fIsmb.conf\fR. In order to successfully +execute the \fIadd share command\fR, \fBsmbd\fR +requires that the administrator be connected using a root account (i.e. +uid == 0). + +When executed, \fBsmbd\fR will automatically invoke the +\fIadd share command\fR with four parameters. +.RS +.TP 0.2i +\(bu +\fIconfigFile\fR - the location +of the global \fIsmb.conf\fR file. +.TP 0.2i +\(bu +\fIshareName\fR - the name of the new +share. +.TP 0.2i +\(bu +\fIpathName\fR - path to an **existing** +directory on disk. +.TP 0.2i +\(bu +\fIcomment\fR - comment string to associate +with the new share. .RE - -If you decide to use a path= line in your [homes] section then you may -find it useful to use the %S macro. For example path=/data/pchome/%S -would be useful if you have different home directories for your PCs -than for unix access. - -This is a fast and simple way to give a large number of clients access to -their home directories with a minimum of fuss. - -A similar process occurs if the requested service name is "homes", except that -the service name is not changed to that of the requesting user. This method -of using the [homes] section works well if different users share a client PC. - -The [homes] section can specify all the parameters a normal service section -can specify, though some make more sense than others. The following is a -typical and suitable [homes] section: - - [homes] - writable = yes - -An important point: - -.RS 3 -If guest access is specified in the [homes] section, all home directories will -be accessible to all clients -.B without a password. -In the very unlikely event -that this is actually desirable, it would be wise to also specify read only -access. +.PP +This parameter is only used for add file shares. To add printer shares, +see the \fIadd printer +command\fR. +.PP +.PP +See also \fIchange share +command\fR, \fIdelete share +command\fR. +.PP +.PP +Default: \fBnone\fR +.PP +.PP +Example: \fBadd share command = /usr/local/bin/addshare\fR +.PP +.TP +\fBadd machine script (G)\fR +This is the full pathname to a script that will +be run by smbd(8)when a machine is added +to it's domain using the administrator username and password method. + +This option is only required when using sam back-ends tied to the +Unix uid method of RID calculation such as smbpasswd. This option is only +available in Samba 3.0. + +Default: \fBadd machine script = <empty string> +\fR +Example: \fBadd machine script = /usr/sbin/adduser -n -g machines -c Machine -d /dev/null -s /bin/false %u +\fR.TP +\fBadd user script (G)\fR +This is the full pathname to a script that will +be run \fBAS ROOT\fR by smbd(8) +under special circumstances described below. + +Normally, a Samba server requires that UNIX users are +created for all users accessing files on this server. For sites +that use Windows NT account databases as their primary user database +creating these users and keeping the user list in sync with the +Windows NT PDC is an onerous task. This option allows smbdto create the required UNIX users +\fBON DEMAND\fR when a user accesses the Samba server. + +In order to use this option, smbd +must be set to \fIsecurity = server\fR or \fI security = domain\fR and \fIadd user script\fR +must be set to a full pathname for a script that will create a UNIX +user given one argument of \fI%u\fR, which expands into +the UNIX user name to create. + +When the Windows user attempts to access the Samba server, +at login (session setup in the SMB protocol) time, smbdcontacts the \fIpassword server\fR and +attempts to authenticate the given user with the given password. If the +authentication succeeds then \fBsmbd\fR +attempts to find a UNIX user in the UNIX password database to map the +Windows user into. If this lookup fails, and \fIadd user script +\fRis set then \fBsmbd\fR will +call the specified script \fBAS ROOT\fR, expanding +any \fI%u\fR argument to be the user name to create. + +If this script successfully creates the user then \fBsmbd +\fRwill continue on as though the UNIX user +already existed. In this way, UNIX users are dynamically created to +match existing Windows NT accounts. + +See also \fI security\fR, \fIpassword server\fR, +\fIdelete user +script\fR. + +Default: \fBadd user script = <empty string> +\fR +Example: \fBadd user script = /usr/local/samba/bin/add_user +%u\fR +.TP +\fBadmin users (S)\fR +This is a list of users who will be granted +administrative privileges on the share. This means that they +will do all file operations as the super-user (root). + +You should use this option very carefully, as any user in +this list will be able to do anything they like on the share, +irrespective of file permissions. + +Default: \fBno admin users\fR + +Example: \fBadmin users = jason\fR +.TP +\fBallow hosts (S)\fR +Synonym for \fIhosts allow\fR. +.TP +\fBallow trusted domains (G)\fR +This option only takes effect when the \fIsecurity\fR option is set to +server or domain. +If it is set to no, then attempts to connect to a resource from +a domain or workgroup other than the one which smbdis running +in will fail, even if that domain is trusted by the remote server +doing the authentication. + +This is useful if you only want your Samba server to +serve resources to users in the domain it is a member of. As +an example, suppose that there are two domains DOMA and DOMB. DOMB +is trusted by DOMA, which contains the Samba server. Under normal +circumstances, a user with an account in DOMB can then access the +resources of a UNIX account with the same account name on the +Samba server even if they do not have an account in DOMA. This +can make implementing a security boundary difficult. + +Default: \fBallow trusted domains = yes\fR +.TP +\fBannounce as (G)\fR +This specifies what type of server +\fBnmbd\fR +will announce itself as, to a network neighborhood browse +list. By default this is set to Windows NT. The valid options +are : "NT Server" (which can also be written as "NT"), +"NT Workstation", "Win95" or "WfW" meaning Windows NT Server, +Windows NT Workstation, Windows 95 and Windows for Workgroups +respectively. Do not change this parameter unless you have a +specific need to stop Samba appearing as an NT server as this +may prevent Samba servers from participating as browser servers +correctly. + +Default: \fBannounce as = NT Server\fR + +Example: \fBannounce as = Win95\fR +.TP +\fBannounce version (G)\fR +This specifies the major and minor version numbers +that nmbd will use when announcing itself as a server. The default +is 4.2. Do not change this parameter unless you have a specific +need to set a Samba server to be a downlevel server. + +Default: \fBannounce version = 4.5\fR + +Example: \fBannounce version = 2.0\fR +.TP +\fBauto services (G)\fR +This is a synonym for the \fIpreload\fR. +.TP +\fBavailable (S)\fR +This parameter lets you "turn off" a service. If +\fIavailable = no\fR, then \fBALL\fR +attempts to connect to the service will fail. Such failures are +logged. + +Default: \fBavailable = yes\fR +.TP +\fBbind interfaces only (G)\fR +This global parameter allows the Samba admin +to limit what interfaces on a machine will serve SMB requests. If +affects file service smbd(8)and +name service nmbd(8)in slightly +different ways. + +For name service it causes \fBnmbd\fR to bind +to ports 137 and 138 on the interfaces listed in the interfaces parameter. \fBnmbd +\fRalso binds to the "all addresses" interface (0.0.0.0) +on ports 137 and 138 for the purposes of reading broadcast messages. +If this option is not set then \fBnmbd\fR will service +name requests on all of these sockets. If \fIbind interfaces +only\fR is set then \fBnmbd\fR will check the +source address of any packets coming in on the broadcast sockets +and discard any that don't match the broadcast addresses of the +interfaces in the \fIinterfaces\fR parameter list. +As unicast packets are received on the other sockets it allows +\fBnmbd\fR to refuse to serve names to machines that +send packets that arrive through any interfaces not listed in the +\fIinterfaces\fR list. IP Source address spoofing +does defeat this simple check, however so it must not be used +seriously as a security feature for \fBnmbd\fR. + +For file service it causes smbd(8) +to bind only to the interface list given in the interfaces parameter. This restricts the networks that +\fBsmbd\fR will serve to packets coming in those +interfaces. Note that you should not use this parameter for machines +that are serving PPP or other intermittent or non-broadcast network +interfaces as it will not cope with non-permanent interfaces. + +If \fIbind interfaces only\fR is set then +unless the network address \fB127.0.0.1\fR is added +to the \fIinterfaces\fR parameter list \fBsmbpasswd(8)\fR +and \fBswat(8)\fRmay +not work as expected due to the reasons covered below. + +To change a users SMB password, the \fBsmbpasswd\fR +by default connects to the \fBlocalhost - 127.0.0.1\fR +address as an SMB client to issue the password change request. If +\fIbind interfaces only\fR is set then unless the +network address \fB127.0.0.1\fR is added to the +\fIinterfaces\fR parameter list then \fB smbpasswd\fR will fail to connect in it's default mode. +\fBsmbpasswd\fR can be forced to use the primary IP interface +of the local host by using its \fI-r remote machine\fR +parameter, with \fIremote machine\fR set +to the IP name of the primary interface of the local host. + +The \fBswat\fR status page tries to connect with +\fBsmbd\fR and \fBnmbd\fR at the address +\fB127.0.0.1\fR to determine if they are running. +Not adding \fB127.0.0.1\fR will cause \fB smbd\fR and \fBnmbd\fR to always show +"not running" even if they really are. This can prevent \fB swat\fR from starting/stopping/restarting \fBsmbd\fR +and \fBnmbd\fR. + +Default: \fBbind interfaces only = no\fR +.TP +\fBblocking locks (S)\fR +This parameter controls the behavior of smbd(8)when given a request by a client +to obtain a byte range lock on a region of an open file, and the +request has a time limit associated with it. + +If this parameter is set and the lock range requested +cannot be immediately satisfied, Samba 2.2 will internally +queue the lock request, and periodically attempt to obtain +the lock until the timeout period expires. + +If this parameter is set to false, then +Samba 2.2 will behave as previous versions of Samba would and +will fail the lock request immediately if the lock range +cannot be obtained. + +Default: \fBblocking locks = yes\fR +.TP +\fBbrowsable (S)\fR +See the \fI browseable\fR. +.TP +\fBbrowse list (G)\fR +This controls whether \fBsmbd(8)\fRwill serve a browse list to +a client doing a \fBNetServerEnum\fR call. Normally +set to true. You should never need to change +this. + +Default: \fBbrowse list = yes\fR +.TP +\fBbrowseable (S)\fR +This controls whether this share is seen in +the list of available shares in a net view and in the browse list. + +Default: \fBbrowseable = yes\fR +.TP +\fBcase sensitive (S)\fR +See the discussion in the section NAME MANGLING. + +Default: \fBcase sensitive = no\fR +.TP +\fBcasesignames (S)\fR +Synonym for case +sensitive. +.TP +\fBchange notify timeout (G)\fR +This SMB allows a client to tell a server to +"watch" a particular directory for any changes and only reply to +the SMB request when a change has occurred. Such constant scanning of +a directory is expensive under UNIX, hence an \fBsmbd(8)\fRdaemon only performs such a scan +on each requested directory once every \fIchange notify +timeout\fR seconds. + +Default: \fBchange notify timeout = 60\fR + +Example: \fBchange notify timeout = 300\fR + +Would change the scan time to every 5 minutes. +.TP +\fBchange share command (G)\fR +Samba 2.2.0 introduced the ability to dynamically +add and delete shares via the Windows NT 4.0 Server Manager. The +\fIchange share command\fR is used to define an +external program or script which will modify an existing service definition +in \fIsmb.conf\fR. In order to successfully +execute the \fIchange share command\fR, \fBsmbd\fR +requires that the administrator be connected using a root account (i.e. +uid == 0). + +When executed, \fBsmbd\fR will automatically invoke the +\fIchange share command\fR with four parameters. +.RS +.TP 0.2i +\(bu +\fIconfigFile\fR - the location +of the global \fIsmb.conf\fR file. +.TP 0.2i +\(bu +\fIshareName\fR - the name of the new +share. +.TP 0.2i +\(bu +\fIpathName\fR - path to an **existing** +directory on disk. +.TP 0.2i +\(bu +\fIcomment\fR - comment string to associate +with the new share. .RE +.PP +This parameter is only used modify existing file shares definitions. To modify +printer shares, use the "Printers..." folder as seen when browsing the Samba host. +.PP +.PP +See also \fIadd share +command\fR, \fIdelete +share command\fR. +.PP +.PP +Default: \fBnone\fR +.PP +.PP +Example: \fBchange share command = /usr/local/bin/addshare\fR +.PP +.TP +\fBcharacter set (G)\fR +This allows smbdto map incoming filenames +from a DOS Code page (see the client +code page parameter) to several built in UNIX character sets. +The built in code page translations are: +.RS +.TP 0.2i +\(bu +ISO8859-1 : Western European +UNIX character set. The parameter \fIclient code page\fR +\fBMUST\fR be set to code page 850 if the +\fIcharacter set\fR parameter is set to +ISO8859-1 in order for the conversion to the +UNIX character set to be done correctly. +.TP 0.2i +\(bu +ISO8859-2 : Eastern European +UNIX character set. The parameter \fIclient code page +\fR\fBMUST\fR be set to code page 852 if +the \fI character set\fR parameter is set +to ISO8859-2 in order for the conversion +to the UNIX character set to be done correctly. +.TP 0.2i +\(bu +ISO8859-5 : Russian Cyrillic +UNIX character set. The parameter \fIclient code page +\fR\fBMUST\fR be set to code page +866 if the \fIcharacter set \fR parameter is +set to ISO8859-5 in order for the conversion +to the UNIX character set to be done correctly. +.TP 0.2i +\(bu +ISO8859-7 : Greek UNIX +character set. The parameter \fIclient code page +\fR\fBMUST\fR be set to code page +737 if the \fIcharacter set\fR parameter is +set to ISO8859-7 in order for the conversion +to the UNIX character set to be done correctly. +.TP 0.2i +\(bu +KOI8-R : Alternate mapping +for Russian Cyrillic UNIX character set. The parameter +\fIclient code page\fR \fBMUST\fR +be set to code page 866 if the \fIcharacter set\fR +parameter is set to KOI8-R in order for the +conversion to the UNIX character set to be done correctly. .RE - -Note that the browseable flag for auto home directories will be -inherited from the global browseable flag, not the [homes] browseable -flag. This is useful as it means setting browseable=no in the [homes] -section will hide the [homes] service but make any auto home -directories visible. - -.SS The [printers] section -.RS 3 -This section works like [homes], but for printers. - -If a [printers] section occurs in the configuration file, users are able -to connect to any printer specified in the local host's printcap file. - -When a connection request is made, the existing services are scanned. If a -match is found, it is used. If no match is found, but a [homes] section -exists, it is used as described above. Otherwise, the requested service name is -treated as a printer name and the appropriate printcap file is scanned to -see if the requested service name is a valid printer name. If a match is -found, a new service is created by cloning the [printers] section. - -A few modifications are then made to the newly created section: - -.RS 3 -The service name is set to the located printer name - -If no printer name was given, the printer name is set to the located printer -name - -If the service does not permit guest access and no username was given, the -username is set to the located printer name. +.PP +\fBBUG\fR. These MSDOS code page to UNIX character +set mappings should be dynamic, like the loading of MS DOS code pages, +not static. +.PP +.PP +Normally this parameter is not set, meaning no filename +translation is done. +.PP +.PP +Default: \fBcharacter set = <empty string>\fR +.PP +.PP +Example: \fBcharacter set = ISO8859-1\fR +.PP +.TP +\fBclient code page (G)\fR +This parameter specifies the DOS code page +that the clients accessing Samba are using. To determine what code +page a Windows or DOS client is using, open a DOS command prompt +and type the command \fBchcp\fR. This will output +the code page. The default for USA MS-DOS, Windows 95, and +Windows NT releases is code page 437. The default for western +European releases of the above operating systems is code page 850. + +This parameter tells smbd(8) +which of the \fIcodepage.XXX +\fRfiles to dynamically load on startup. These files, +described more fully in the manual page \fBmake_smbcodepage(1)\fR, tell \fB smbd\fR how to map lower to upper case characters to provide +the case insensitivity of filenames that Windows clients expect. + +Samba currently ships with the following code page files : +.RS +.TP 0.2i +\(bu +Code Page 437 - MS-DOS Latin US +.TP 0.2i +\(bu +Code Page 737 - Windows '95 Greek +.TP 0.2i +\(bu +Code Page 850 - MS-DOS Latin 1 +.TP 0.2i +\(bu +Code Page 852 - MS-DOS Latin 2 +.TP 0.2i +\(bu +Code Page 861 - MS-DOS Icelandic +.TP 0.2i +\(bu +Code Page 866 - MS-DOS Cyrillic +.TP 0.2i +\(bu +Code Page 932 - MS-DOS Japanese SJIS +.TP 0.2i +\(bu +Code Page 936 - MS-DOS Simplified Chinese +.TP 0.2i +\(bu +Code Page 949 - MS-DOS Korean Hangul +.TP 0.2i +\(bu +Code Page 950 - MS-DOS Traditional Chinese .RE +.PP +Thus this parameter may have any of the values 437, 737, 850, 852, +861, 932, 936, 949, or 950. If you don't find the codepage you need, +read the comments in one of the other codepage files and the +\fBmake_smbcodepage(1)\fR man page and write one. Please +remember to donate it back to the Samba user community. +.PP +.PP +This parameter co-operates with the \fIvalid +chars\fR parameter in determining what characters are +valid in filenames and how capitalization is done. If you set both +this parameter and the \fIvalid chars\fR parameter +the \fIclient code page\fR parameter +\fBMUST\fR be set before the \fIvalid +chars\fR parameter in the \fIsmb.conf\fR +file. The \fIvalid chars\fR string will then +augment the character settings in the \fIclient code page\fR +parameter. +.PP +.PP +If not set, \fIclient code page\fR defaults +to 850. +.PP +.PP +See also : \fIvalid +chars\fR, \fIcode page directory\fR +.PP +.PP +Default: \fBclient code page = 850\fR +.PP +.PP +Example: \fBclient code page = 936\fR +.PP +.TP +\fBcode page directory (G)\fR +Define the location of the various client code page +files. -Note that the [printers] service MUST be printable - if you specify otherwise, -the server will refuse to load the configuration file. - -Typically the path specified would be that of a world-writable spool directory -with the sticky bit set on it. A typical [printers] entry would look like this: - - [printers] - path = /usr/spool/public - writable = no - public = yes - printable = yes - -All aliases given for a printer in the printcap file are legitimate printer -names as far as the server is concerned. If your printing subsystem doesn't -work like that, you will have to set up a pseudo-printcap. This is a file -consisting of one or more lines like this: - - alias|alias|alias|alias... - -Each alias should be an acceptable printer name for your printing -subsystem. In the [global] section, specify the new file as your printcap. -The server will then only recognise names found in your pseudo-printcap, -which of course can contain whatever aliases you like. The same technique -could be used simply to limit access to a subset of your local printers. - -An alias, by the way, is defined as any component of the first entry of a -printcap record. Records are separated by newlines, components (if there are -more than one) are separated by vertical bar symbols ("|"). -.SH PARAMETERS -Parameters define the specific attributes of services. - -Some parameters are specific to the [global] section (eg., security). -Some parameters are usable in all sections (eg., create mode). All others are -permissible only in normal sections. For the purposes of the following -descriptions the [homes] and [printers] sections will be considered normal. -The letter 'G' in parentheses indicates that a parameter is specific to the -[global] section. The letter 'S' indicates that a parameter can be -specified in a secvice specific section. Note that all S parameters -can also be specified in the [global] section - in which case they -will define the default behaviour for all services. - -Parameters are arranged here in alphabetical order - this may not create -best bedfellows, but at least you can find them! Where there are synonyms, -the preferred synonym is described, others refer to the preferred synonym. - -.SS VARIABLE SUBSTITUTIONS - -Many of the strings that are settable in the config file can take -substitutions. For example the option "path = /tmp/%u" would be -interpreted as "path = /tmp/john" if the user connected with the -username john. - -These substitutions are mostly noted in the descriptions below, but -there are some general substitions which apply whenever they might be -relevant. These are: - -%S = the name of the current service, if any - -%P = the root directory of the current service, if any - -%u = user name of the current service, if any - -%g = primary group name of %u - -%U = session user name (the user name that the client wanted, not -necessarily the same as the one they got) - -%G = primary group name of %U - -%H = the home directory of the user given by %u - -%v = the Samba version - -%h = the hostname that Samba is running on - -%m = the netbios name of the client machine (very useful) - -%L = the netbios name of the server. This allows you to change your -config based on what the client calls you. Your server can have a "dual -personality". - -%M = the internet name of the client machine - -%d = The process id of the current server process - -%a = the architecture of the remote machine. Only some are recognised, -and those may not be 100% reliable. It currently recognises Samba, -WfWg, WinNT and Win95. Anything else will be known as "UNKNOWN". If it -gets it wrong then sending me a level 3 log should allow me to fix it. - -%I = The IP address of the client machine - -%T = the current date and time - -There are some quite creative things that can be done with these -substitutions and other smb.conf options. - -.SS NAME MANGLING - -Samba supports "name mangling" so that Dos and Windows clients can use -files that don't conform to the 8.3 format. It can also be set to adjust -the case of 8.3 format filenames. - -There are several options that control the way mangling is performed, -and they are grouped here rather than listed separately. For the -defaults look at the output of the testparm program. - -All of these options can be set separately for each service (or -globally, of course). - -The options are: - -"mangle case = yes/no" controls if names that have characters that -aren't of the "default" case are mangled. For example, if this is yes -then a name like "Mail" would be mangled. Default no. - -"case sensitive = yes/no" controls whether filenames are case -sensitive. If they aren't then Samba must do a filename search and -match on passed names. Default no. - -"default case = upper/lower" controls what the default case is for new -filenames. Default lower. - -"preserve case = yes/no" controls if new files are created with the -case that the client passes, or if they are forced to be the "default" -case. Default no. - -"short preserve case = yes/no" controls if new files which conform to 8.3 -syntax, that is all in upper case and of suitable length, are created -upper case, or if they are forced to be the "default" case. This option can -be use with "preserve case = yes" to permit long filenames to retain their -case, while short names are lowered. Default no. - -.SS COMPLETE LIST OF GLOBAL PARAMETER - -Here is a list of all global parameters. See the section of each -parameter for details. Note that some are synonyms. - -auto services - -config file - -deadtime - -debuglevel - -default - -default service - -dfree command - -encrypt passwords - -getwd cache - -hosts equiv - -include - -keepalive - -lock dir - -load printers - -lock directory - -log file - -log level - -lpq cache time - -mangled stack - -max log size - -max packet - -max xmit - -message command - -null passwords - -os level - -packet size - -passwd chat - -passwd program - -password level - -password server - -preferred master - -preload - -printing - -printcap name - -protocol - -read bmpx - -read prediction - -read raw - -read size - -root - -root dir - -root directory - -security - -server string - -smbrun - -socket options - -status - -strip dot - -time offset - -username map - -use rhosts - -valid chars - -workgroup - -write raw - -.SS COMPLETE LIST OF SERVICE PARAMETER - -Here is a list of all service parameters. See the section of each -parameter for details. Note that some are synonyms. - -admin users - -allow hosts - -alternate permissions - -available - -browseable - -case sensitive - -case sig names - -copy - -create mask - -create mode - -comment - -default case - -deny hosts - -directory - -dont descend - -exec - -force group - -force user - -guest account - -guest ok - -guest only - -hide dot files - -hosts allow - -hosts deny - -invalid users - -locking - -lppause command - -lpq command - -lpresume command - -lprm command - -magic output - -magic script - -mangle case - -mangled names - -mangling char - -map archive - -map hidden - -map system - -max connections - -min print space - -only guest - -only user - -path - -postexec - -postscript - -preserve case - -print command - -print ok - -printable - -printer - -printer name - -public - -read only - -read list - -revalidate - -root postexec - -root preexec - -set directory - -share modes - -short preserve case - -strict locking - -sync always - -user - -username - -users - -valid users - -volume - -wide links - -writable - -write ok - -writeable - -write list - -.SS EXPLANATION OF EACH PARAMETER -.RS 3 - -.SS admin users (G) - -This is a list of users who will be granted administrative privilages -on the share. This means that they will do all file operations as the -super-user (root). - -You should use this option very carefully, as any user in this list -will be able to do anything they like on the share, irrespective of -file permissions. - -.B Default: - no admin users - -.B Example: - admin users = jason - -.SS auto services (G) -This is a list of services that you want to be automatically added to -the browse lists. This is most useful for homes and printers services -that would otherwise not be visible. - -Note that if you just want all printers in your printcap file loaded -then the "load printers" option is easier. - -.B Default: - no auto services - -.B Example: - auto services = fred lp colorlp - - -.SS allow hosts (S) -A synonym for this parameter is 'hosts allow'. - -This parameter is a comma delimited set of hosts which are permitted to access -a services. If specified in the [global] section, matching hosts will be -allowed access to any service that does not specifically exclude them from -access. Specific services my have their own list, which override those -specified in the [global] section. - -You can specify the hosts by name or IP number. For example, you could -restrict access to only the hosts on a Class C subnet with something like -"allow hosts = 150.203.5.". The full syntax of the list is described in -the man page -.B hosts_access(5). - -You can also specify hosts by network/netmask pairs and by netgroup -names if your system supports netgroups. The EXCEPT keyword can also -be used to limit a wildcard list. The following examples may provide -some help: - -Example 1: allow all IPs in 150.203.*.* except one - - hosts allow = 150.203. EXCEPT 150.203.6.66 - -Example 2: allow hosts that match the given network/netmask - - hosts allow = 150.203.15.0/255.255.255.0 - -Example 3: allow a couple of hosts - - hosts allow = lapland, arvidsjaur - -Example 4: allow only hosts in netgroup "foonet" or localhost, but -deny access from one particular host - - hosts allow = @foonet, localhost - hosts deny = pirate - -Note that access still requires suitable user-level passwords. - -See testparm(1) for a way of testing your host access to see if it -does what you expect. - -.B Default: - none (ie., all hosts permitted access) - -.B Example: - allow hosts = 150.203.5. myhost.mynet.edu.au - -.SS alternate permissions (S) - -This option affects the way the "read only" DOS attribute is produced -for unix files. If this is false then the read only bit is set for -files on writeable shares which the user cannot write to. - -If this is true then it is set for files whos user write bit is not set. - -The latter behaviour of useful for when users copy files from each -others directories, and use a file manager that preserves -permissions. Without this option they may get annoyed as all copied -files will have the "read only" bit set. - -.B Default: - alternate permissions = no - -.B Example: - alternate permissions = yes - -.SS available (S) -This parameter lets you 'turn off' a service. If 'available = no', then -ALL attempts to connect to the service will fail. Such failures are logged. - -.B Default: - available = yes - -.B Example: - available = no -.SS browseable (S) -This controls whether this share is seen in the list of available -shares in a net view and in the browse list. - -.B Default: - browseable = Yes - -.B Example: - browseable = No - -.SS case sig names (G) -See "case sensitive" - -.SS comment (S) -This is a text field that is seen when a client does a net view to -list what shares are available. It will also be used when browsing is -fully supported. - -.B Default: - No comment string - -.B Example: - comment = Fred's Files - -.SS config file (G) - -This allows you to override the config file to use, instead of the -default (usually smb.conf). There is a chicken and egg problem here as -this option is set in the config file! - -For this reason, if the name of the config file has changed when the -parameters are loaded then it will reload them from the new config -file. - -This option takes the usual substitutions, which can be very useful. - -If thew config file doesn't exist then it won't be loaded (allowing -you to special case the config files of just a few clients). - -.B Example: - config file = /usr/local/samba/smb.conf.%m - -.SS copy (S) -This parameter allows you to 'clone' service entries. The specified -service is simply duplicated under the current service's name. Any -parameters specified in the current section will override those in the -section being copied. - -This feature lets you set up a 'template' service and create similar -services easily. Note that the service being copied must occur earlier -in the configuration file than the service doing the copying. - -.B Default: - none - -.B Example: - copy = otherservice -.SS create mask (S) -A synonym for this parameter is 'create mode'. - -This parameter is the octal modes which are used when converting DOS modes -to Unix modes. - -Note that Samba will or this value with 0700 as you must have at least -user read, write and execute for Samba to work properly. - -.B Default: - create mask = 0755 - -.B Example: - create mask = 0775 -.SS create mode (S) -See -.B create mask. -.SS dead time (G) -The value of the parameter (a decimal integer) represents the number of -minutes of inactivity before a connection is considered dead, and it -is disconnected. The deadtime only takes effect if the number of open files -is zero. - -This is useful to stop a server's resources being exhausted by a large -number of inactive connections. - -Most clients have an auto-reconnect feature when a connection is broken so -in most cases this parameter should be transparent to users. - -Using this parameter with a timeout of a few minutes is recommended -for most systems. - -A deadtime of zero indicates that no auto-disconnection should be performed. - -.B Default: - dead time = 0 - -.B Example: - dead time = 15 -.SS debug level (G) -The value of the parameter (an integer) allows the debug level -(logging level) to be specified in the smb.conf file. This is to give -greater flexibility in the configuration of the system. - -The default will be the debug level specified on the command line. - -.B Example: - debug level = 3 -.SS default (G) -See -.B default service. -.SS default case (S) - -See the section on "NAME MANGLING" Also note the addition of "short -preserve case" - -.SS default service (G) -A synonym for this parameter is 'default'. - -This parameter specifies the name of a service which will be connected to -if the service actually requested cannot be found. Note that the square -brackets are NOT given in the parameter value (see example below). - -There is no default value for this parameter. If this parameter is not given, -attempting to connect to a nonexistent service results in an error. - -Typically the default service would be a public, read-only service. - -Also not that s of 1.9.14 the apparent service name will be changed to -equal that of the requested service, this is very useful as it allows -you to use macros like %S to make a wildcard service. - -Note also that any _ characters in the name of the service used in the -default service will get mapped to a /. This allows for interesting -things. - - -.B Example: - default service = pub +See also \fIclient +code page\fR + +Default: \fBcode page directory = ${prefix}/lib/codepages +\fR +Example: \fBcode page directory = /usr/share/samba/codepages +\fR.TP +\fBcoding system (G)\fR +This parameter is used to determine how incoming +Shift-JIS Japanese characters are mapped from the incoming \fIclient code page\fR +used by the client, into file names in the UNIX filesystem. +Only useful if \fIclient code page\fR is set to +932 (Japanese Shift-JIS). The options are : +.RS +.TP 0.2i +\(bu +SJIS - Shift-JIS. Does no +conversion of the incoming filename. +.TP 0.2i +\(bu +JIS8, J8BB, J8BH, J8@B, +J8@J, J8@H - Convert from incoming Shift-JIS to eight +bit JIS code with different shift-in, shift out codes. +.TP 0.2i +\(bu +JIS7, J7BB, J7BH, J7@B, J7@J, +J7@H - Convert from incoming Shift-JIS to seven bit +JIS code with different shift-in, shift out codes. +.TP 0.2i +\(bu +JUNET, JUBB, JUBH, JU@B, JU@J, JU@H +- Convert from incoming Shift-JIS to JUNET code with different shift-in, +shift out codes. +.TP 0.2i +\(bu +EUC - Convert an incoming +Shift-JIS character to EUC code. +.TP 0.2i +\(bu +HEX - Convert an incoming +Shift-JIS character to a 3 byte hex representation, i.e. +:AB. +.TP 0.2i +\(bu +CAP - Convert an incoming +Shift-JIS character to the 3 byte hex representation used by +the Columbia AppleTalk Program (CAP), i.e. :AB. +This is used for compatibility between Samba and CAP. +.RE +.PP +Default: \fBcoding system = <empty value>\fR +.PP +.TP +\fBcomment (S)\fR +This is a text field that is seen next to a share +when a client does a queries the server, either via the network +neighborhood or via \fBnet view\fR to list what shares +are available. + +If you want to set the string that is displayed next to the +machine name then see the \fI server string\fR parameter. + +Default: \fBNo comment string\fR + +Example: \fBcomment = Fred's Files\fR +.TP +\fBconfig file (G)\fR +This allows you to override the config file +to use, instead of the default (usually \fIsmb.conf\fR). +There is a chicken and egg problem here as this option is set +in the config file! + +For this reason, if the name of the config file has changed +when the parameters are loaded then it will reload them from +the new config file. + +This option takes the usual substitutions, which can +be very useful. + +If the config file doesn't exist then it won't be loaded +(allowing you to special case the config files of just a few +clients). + +Example: \fBconfig file = /usr/local/samba/lib/smb.conf.%m +\fR.TP +\fBcopy (S)\fR +This parameter allows you to "clone" service +entries. The specified service is simply duplicated under the +current service's name. Any parameters specified in the current +section will override those in the section being copied. + +This feature lets you set up a 'template' service and +create similar services easily. Note that the service being +copied must occur earlier in the configuration file than the +service doing the copying. + +Default: \fBno value\fR + +Example: \fBcopy = otherservice\fR +.TP +\fBcreate mask (S)\fR +A synonym for this parameter is +\fIcreate mode\fR +\&. + +When a file is created, the necessary permissions are +calculated according to the mapping from DOS modes to UNIX +permissions, and the resulting UNIX mode is then bit-wise 'AND'ed +with this parameter. This parameter may be thought of as a bit-wise +MASK for the UNIX modes of a file. Any bit \fBnot\fR +set here will be removed from the modes set on a file when it is +created. + +The default value of this parameter removes the +\&'group' and 'other' write and execute bits from the UNIX modes. + +Following this Samba will bit-wise 'OR' the UNIX mode created +from this parameter with the value of the \fIforce create mode\fR +parameter which is set to 000 by default. + +This parameter does not affect directory modes. See the +parameter \fIdirectory mode +\fRfor details. + +See also the \fIforce +create mode\fR parameter for forcing particular mode +bits to be set on created files. See also the \fIdirectory mode\fR parameter for masking +mode bits on created directories. See also the \fIinherit permissions\fR parameter. + +Note that this parameter does not apply to permissions +set by Windows NT/2000 ACL editors. If the administrator wishes to enforce +a mask on access control lists also, they need to set the \fIsecurity mask\fR. + +Default: \fBcreate mask = 0744\fR + +Example: \fBcreate mask = 0775\fR +.TP +\fBcreate mode (S)\fR +This is a synonym for \fI create mask\fR. +.TP +\fBdeadtime (G)\fR +The value of the parameter (a decimal integer) +represents the number of minutes of inactivity before a connection +is considered dead, and it is disconnected. The deadtime only takes +effect if the number of open files is zero. + +This is useful to stop a server's resources being +exhausted by a large number of inactive connections. + +Most clients have an auto-reconnect feature when a +connection is broken so in most cases this parameter should be +transparent to users. + +Using this parameter with a timeout of a few minutes +is recommended for most systems. + +A deadtime of zero indicates that no auto-disconnection +should be performed. + +Default: \fBdeadtime = 0\fR + +Example: \fBdeadtime = 15\fR +.TP +\fBdebug hires timestamp (G)\fR +Sometimes the timestamps in the log messages +are needed with a resolution of higher that seconds, this +boolean parameter adds microsecond resolution to the timestamp +message header when turned on. + +Note that the parameter \fI debug timestamp\fR must be on for this to have an +effect. + +Default: \fBdebug hires timestamp = no\fR +.TP +\fBdebug pid (G)\fR +When using only one log file for more then one +forked smbd-process there may be hard to follow which process +outputs which message. This boolean parameter is adds the process-id +to the timestamp message headers in the logfile when turned on. + +Note that the parameter \fI debug timestamp\fR must be on for this to have an +effect. + +Default: \fBdebug pid = no\fR +.TP +\fBdebug timestamp (G)\fR +Samba 2.2 debug log messages are timestamped +by default. If you are running at a high \fIdebug level\fR these timestamps +can be distracting. This boolean parameter allows timestamping +to be turned off. + +Default: \fBdebug timestamp = yes\fR +.TP +\fBdebug uid (G)\fR +Samba is sometimes run as root and sometime +run as the connected user, this boolean parameter inserts the +current euid, egid, uid and gid to the timestamp message headers +in the log file if turned on. + +Note that the parameter \fI debug timestamp\fR must be on for this to have an +effect. + +Default: \fBdebug uid = no\fR +.TP +\fBdebuglevel (G)\fR +Synonym for \fI log level\fR. +.TP +\fBdefault (G)\fR +A synonym for \fI default service\fR. +.TP +\fBdefault case (S)\fR +See the section on NAME MANGLING. Also note the \fIshort preserve case\fR parameter. + +Default: \fBdefault case = lower\fR +.TP +\fBdefault service (G)\fR +This parameter specifies the name of a service +which will be connected to if the service actually requested cannot +be found. Note that the square brackets are \fBNOT\fR +given in the parameter value (see example below). + +There is no default value for this parameter. If this +parameter is not given, attempting to connect to a nonexistent +service results in an error. + +Typically the default service would be a \fIguest ok\fR, \fIread-only\fR service. + +Also note that the apparent service name will be changed +to equal that of the requested service, this is very useful as it +allows you to use macros like \fI%S\fR to make +a wildcard service. + +Note also that any "_" characters in the name of the service +used in the default service will get mapped to a "/". This allows for +interesting things. + +Example: + +.sp +.nf +[global] + default service = pub - [pub] - path = /%S - - -.SS deny hosts (S) -A synonym for this parameter is 'hosts deny'. - -The opposite of 'allow hosts' - hosts listed here are NOT permitted -access to services unless the specific services have their own lists to -override this one. Where the lists conflict, the 'allow' list takes precedence. - -.B Default: - none (ie., no hosts specifically excluded) - -.B Example: - deny hosts = 150.203.4. badhost.mynet.edu.au -.SS dfree command (G) -The dfree command setting should only be used on systems where a -problem occurs with the internal disk space calculations. This has -been known to happen with Ultrix, but may occur with other operating -systems. The symptom that was seen was an error of "Abort Retry -Ignore" at the end of each directory listing. +[pub] + path = /%S + +.sp +.fi +.TP +\fBdelete printer command (G)\fR +With the introduction of MS-RPC based printer +support for Windows NT/2000 clients in Samba 2.2, it is now +possible to delete printer at run time by issuing the +DeletePrinter() RPC call. + +For a Samba host this means that the printer must be +physically deleted from underlying printing system. The \fI deleteprinter command\fR defines a script to be run which +will perform the necessary operations for removing the printer +from the print system and from \fIsmb.conf\fR. + +The \fIdelete printer command\fR is +automatically called with only one parameter: \fI "printer name"\fR. + +Once the \fIdelete printer command\fR has +been executed, \fBsmbd\fR will reparse the \fI smb.conf\fR to associated printer no longer exists. +If the sharename is still valid, then \fBsmbd +\fRwill return an ACCESS_DENIED error to the client. + +See also \fI add printer command\fR, \fIprinting\fR, +\fIshow add +printer wizard\fR + +Default: \fBnone\fR + +Example: \fBdeleteprinter command = /usr/bin/removeprinter +\fR.TP +\fBdelete readonly (S)\fR +This parameter allows readonly files to be deleted. +This is not normal DOS semantics, but is allowed by UNIX. + +This option may be useful for running applications such +as rcs, where UNIX file ownership prevents changing file +permissions, and DOS semantics prevent deletion of a read only file. + +Default: \fBdelete readonly = no\fR +.TP +\fBdelete share command (G)\fR +Samba 2.2.0 introduced the ability to dynamically +add and delete shares via the Windows NT 4.0 Server Manager. The +\fIdelete share command\fR is used to define an +external program or script which will remove an existing service +definition from \fIsmb.conf\fR. In order to successfully +execute the \fIdelete share command\fR, \fBsmbd\fR +requires that the administrator be connected using a root account (i.e. +uid == 0). + +When executed, \fBsmbd\fR will automatically invoke the +\fIdelete share command\fR with two parameters. +.RS +.TP 0.2i +\(bu +\fIconfigFile\fR - the location +of the global \fIsmb.conf\fR file. +.TP 0.2i +\(bu +\fIshareName\fR - the name of +the existing service. +.RE +.PP +This parameter is only used to remove file shares. To delete printer shares, +see the \fIdelete printer +command\fR. +.PP +.PP +See also \fIadd share +command\fR, \fIchange +share command\fR. +.PP +.PP +Default: \fBnone\fR +.PP +.PP +Example: \fBdelete share command = /usr/local/bin/delshare\fR +.PP +.TP +\fBdelete user script (G)\fR +This is the full pathname to a script that will +be run \fBAS ROOT\fR by \fBsmbd(8)\fRunder special circumstances +described below. + +Normally, a Samba server requires that UNIX users are +created for all users accessing files on this server. For sites +that use Windows NT account databases as their primary user database +creating these users and keeping the user list in sync with the +Windows NT PDC is an onerous task. This option allows \fB smbd\fR to delete the required UNIX users \fBON +DEMAND\fR when a user accesses the Samba server and the +Windows NT user no longer exists. + +In order to use this option, \fBsmbd\fR must be +set to \fIsecurity = domain\fR and \fIdelete +user script\fR must be set to a full pathname for a script +that will delete a UNIX user given one argument of \fI%u +\fR, which expands into the UNIX user name to delete. +\fBNOTE\fR that this is different to the \fIadd user script\fR +which will work with the \fIsecurity = server\fR option +as well as \fIsecurity = domain\fR. The reason for this +is only when Samba is a domain member does it get the information +on an attempted user logon that a user no longer exists. In the +\fIsecurity = server\fR mode a missing user +is treated the same as an invalid password logon attempt. Deleting +the user in this circumstance would not be a good idea. + +When the Windows user attempts to access the Samba server, +at \fBlogin\fR (session setup in the SMB protocol) +time, \fBsmbd\fR contacts the \fIpassword server\fR and attempts to authenticate +the given user with the given password. If the authentication fails +with the specific Domain error code meaning that the user no longer +exists then \fBsmbd\fR attempts to find a UNIX user in +the UNIX password database that matches the Windows user account. If +this lookup succeeds, and \fIdelete user script\fR is +set then \fBsmbd\fR will all the specified script +\fBAS ROOT\fR, expanding any \fI%u\fR +argument to be the user name to delete. + +This script should delete the given UNIX username. In this way, +UNIX users are dynamically deleted to match existing Windows NT +accounts. + +See also security = domain, +\fIpassword server\fR +, \fIadd user script\fR +\&. + +Default: \fBdelete user script = <empty string> +\fR +Example: \fBdelete user script = /usr/local/samba/bin/del_user +%u\fR +.TP +\fBdelete veto files (S)\fR +This option is used when Samba is attempting to +delete a directory that contains one or more vetoed directories +(see the \fIveto files\fR +option). If this option is set to false (the default) then if a vetoed +directory contains any non-vetoed files or directories then the +directory delete will fail. This is usually what you want. + +If this option is set to true, then Samba +will attempt to recursively delete any files and directories within +the vetoed directory. This can be useful for integration with file +serving systems such as NetAtalk which create meta-files within +directories you might normally veto DOS/Windows users from seeing +(e.g. \fI.AppleDouble\fR) + +Setting \fBdelete veto files = yes\fR allows these +directories to be transparently deleted when the parent directory +is deleted (so long as the user has permissions to do so). + +See also the \fIveto +files\fR parameter. + +Default: \fBdelete veto files = no\fR +.TP +\fBdeny hosts (S)\fR +Synonym for \fIhosts +deny\fR. +.TP +\fBdfree command (G)\fR +The \fIdfree command\fR setting should +only be used on systems where a problem occurs with the internal +disk space calculations. This has been known to happen with Ultrix, +but may occur with other operating systems. The symptom that was +seen was an error of "Abort Retry Ignore" at the end of each +directory listing. This setting allows the replacement of the internal routines to calculate the total disk space and amount available with an external routine. The example below gives a possible script that might fulfill -this function. - -The external program will be passed a single parameter indicating a -directory in the filesystem being queried. This will typically consist -of the string "./". The script should return two integers in ascii. The -first should be the total disk space in blocks, and the second should -be the number of available blocks. An optional third return value -can give the block size in bytes. The default blocksize is 1024 bytes. - -Note: Your script should NOT be setuid or setgid and should be owned by -(and writable only by) root! - -.B Default: - By default internal routines for determining the disk capacity -and remaining space will be used. - -.B Example: - dfree command = /usr/local/smb/dfree - - Where the script dfree (which must be made executable) could be - - #!/bin/sh - df $1 | tail -1 | awk '{print $2" "$4}' - - or perhaps (on Sys V) - - #!/bin/sh - /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' - - - Note that you may have to replace the command names with full -path names on some systems. -.SS directory (S) -See -.B path. -.SS dont descend (S) -There are certain directories on some systems (eg., the /proc tree under -Linux) that are either not of interest to clients or are infinitely deep -(recursive). This parameter allows you to specify a comma-delimited list -of directories that the server should always show as empty. - -Note that Samba can be very fussy about the exact format of the "dont -descend" entries. For example you ma need "./proc" instead of just -"/proc". Experimentation is the best policy :-) - -.B Default: - none (ie., all directories are OK to descend) - -.B Example: - dont descend = /proc,/dev - -.SS encrypt passwords (G) - -This boolean controls whether encrypted passwords will be negotiated -with the cient. Note that this option has no effect if you haven't -compiled in the necessary des libraries and encryption code. It -defaults to no. - -.SS exec (S) - -This is an alias for preexec - - -.SS force group (S) -This specifies a group name that all connections to this service -should be made as. This may be useful for sharing files. - -.B Default: - no forced group - -.B Example: - force group = agroup - -.SS force user (S) -This specifies a user name that all connections to this service -should be made as. This may be useful for sharing files. You should -also use it carefully as using it incorrectly can cause security -problems. - -This user name only gets used once a connection is established. Thus -clients still need to connect as a valid user and supply a valid -password. Once connected, all file operations will be performed as the -"forced user", not matter what username the client connected as. - -.B Default: - no forced user - -.B Example: - force user = auser +this function. + +The external program will be passed a single parameter indicating +a directory in the filesystem being queried. This will typically consist +of the string \fI./\fR. The script should return two +integers in ASCII. The first should be the total disk space in blocks, +and the second should be the number of available blocks. An optional +third return value can give the block size in bytes. The default +blocksize is 1024 bytes. + +Note: Your script should \fBNOT\fR be setuid or +setgid and should be owned by (and writeable only by) root! + +Default: \fBBy default internal routines for +determining the disk capacity and remaining space will be used. +\fR +Example: \fBdfree command = /usr/local/samba/bin/dfree +\fR +Where the script dfree (which must be made executable) could be: + +.sp +.nf + + #!/bin/sh + df $1 | tail -1 | awk '{print $2" "$4}' + +.sp +.fi + +or perhaps (on Sys V based systems): + +.sp +.nf + + #!/bin/sh + /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' + +.sp +.fi + +Note that you may have to replace the command names +with full path names on some systems. +.TP +\fBdirectory (S)\fR +Synonym for \fIpath +\fR\&. +.TP +\fBdirectory mask (S)\fR +This parameter is the octal modes which are +used when converting DOS modes to UNIX modes when creating UNIX +directories. + +When a directory is created, the necessary permissions are +calculated according to the mapping from DOS modes to UNIX permissions, +and the resulting UNIX mode is then bit-wise 'AND'ed with this +parameter. This parameter may be thought of as a bit-wise MASK for +the UNIX modes of a directory. Any bit \fBnot\fR set +here will be removed from the modes set on a directory when it is +created. + +The default value of this parameter removes the 'group' +and 'other' write bits from the UNIX mode, allowing only the +user who owns the directory to modify it. + +Following this Samba will bit-wise 'OR' the UNIX mode +created from this parameter with the value of the \fIforce directory mode +\fRparameter. This parameter is set to 000 by +default (i.e. no extra mode bits are added). + +Note that this parameter does not apply to permissions +set by Windows NT/2000 ACL editors. If the administrator wishes to enforce +a mask on access control lists also, they need to set the \fIdirectory security mask\fR. + +See the \fIforce +directory mode\fR parameter to cause particular mode +bits to always be set on created directories. + +See also the \fIcreate mode +\fRparameter for masking mode bits on created files, +and the \fIdirectory +security mask\fR parameter. + +Also refer to the \fI inherit permissions\fR parameter. + +Default: \fBdirectory mask = 0755\fR + +Example: \fBdirectory mask = 0775\fR +.TP +\fBdirectory mode (S)\fR +Synonym for \fI directory mask\fR +.TP +\fBdirectory security mask (S)\fR +This parameter controls what UNIX permission bits +can be modified when a Windows NT client is manipulating the UNIX +permission on a directory using the native NT security dialog +box. + +This parameter is applied as a mask (AND'ed with) to +the changed permission bits, thus preventing any bits not in +this mask from being modified. Essentially, zero bits in this +mask may be treated as a set of bits the user is not allowed +to change. + +If not set explicitly this parameter is set to 0777 +meaning a user is allowed to modify all the user/group/world +permissions on a directory. + +\fBNote\fR that users who can access the +Samba server through other means can easily bypass this restriction, +so it is primarily useful for standalone "appliance" systems. +Administrators of most normal systems will probably want to leave +it as the default of 0777. + +See also the \fI force directory security mode\fR, \fIsecurity mask\fR, +\fIforce security mode +\fRparameters. + +Default: \fBdirectory security mask = 0777\fR + +Example: \fBdirectory security mask = 0700\fR +.TP +\fBdisable spoolss (G)\fR +Enabling this parameter will disables Samba's support +for the SPOOLSS set of MS-RPC's and will yield identical behavior +as Samba 2.0.x. Windows NT/2000 clients will downgrade to using +Lanman style printing commands. Windows 9x/ME will be uneffected by +the parameter. However, this will also disable the ability to upload +printer drivers to a Samba server via the Windows NT Add Printer +Wizard or by using the NT printer properties dialog window. It will +also disable the capability of Windows NT/2000 clients to download +print drivers from the Samba host upon demand. +\fBBe very careful about enabling this parameter.\fR + +See also use client driver + +Default : \fBdisable spoolss = no\fR +.TP +\fBdns proxy (G)\fR +Specifies that nmbd(8) +when acting as a WINS server and finding that a NetBIOS name has not +been registered, should treat the NetBIOS name word-for-word as a DNS +name and do a lookup with the DNS server for that name on behalf of +the name-querying client. + +Note that the maximum length for a NetBIOS name is 15 +characters, so the DNS name (or DNS alias) can likewise only be +15 characters, maximum. + +\fBnmbd\fR spawns a second copy of itself to do the +DNS name lookup requests, as doing a name lookup is a blocking +action. + +See also the parameter \fI wins support\fR. + +Default: \fBdns proxy = yes\fR +.TP +\fBdomain admin group (G)\fR +This parameter is intended as a temporary solution +to enable users to be a member of the "Domain Admins" group when +a Samba host is acting as a PDC. A complete solution will be provided +by a system for mapping Windows NT/2000 groups onto UNIX groups. +Please note that this parameter has a somewhat confusing name. It +accepts a list of usernames and of group names in standard +\fIsmb.conf\fR notation. + +See also \fIdomain +guest group\fR, \fIdomain +logons\fR + +Default: \fBno domain administrators\fR + +Example: \fBdomain admin group = root @wheel\fR +.TP +\fBdomain guest group (G)\fR +This parameter is intended as a temporary solution +to enable users to be a member of the "Domain Guests" group when +a Samba host is acting as a PDC. A complete solution will be provided +by a system for mapping Windows NT/2000 groups onto UNIX groups. +Please note that this parameter has a somewhat confusing name. It +accepts a list of usernames and of group names in standard +\fIsmb.conf\fR notation. + +See also \fIdomain +admin group\fR, \fIdomain +logons\fR + +Default: \fBno domain guests\fR + +Example: \fBdomain guest group = nobody @guest\fR +.TP +\fBdomain logons (G)\fR +If set to true, the Samba server will serve +Windows 95/98 Domain logons for the \fIworkgroup\fR it is in. Samba 2.2 also +has limited capability to act as a domain controller for Windows +NT 4 Domains. For more details on setting up this feature see +the Samba-PDC-HOWTO included in the \fIhtmldocs/\fR +directory shipped with the source code. + +Default: \fBdomain logons = no\fR +.TP +\fBdomain master (G)\fR +Tell \fB nmbd(8)\fRto enable WAN-wide browse list +collation. Setting this option causes \fBnmbd\fR to +claim a special domain specific NetBIOS name that identifies +it as a domain master browser for its given \fIworkgroup\fR. Local master browsers +in the same \fIworkgroup\fR on broadcast-isolated +subnets will give this \fBnmbd\fR their local browse lists, +and then ask \fBsmbd(8)\fR +for a complete copy of the browse list for the whole wide area +network. Browser clients will then contact their local master browser, +and will receive the domain-wide browse list, instead of just the list +for their broadcast-isolated subnet. + +Note that Windows NT Primary Domain Controllers expect to be +able to claim this \fIworkgroup\fR specific special +NetBIOS name that identifies them as domain master browsers for +that \fIworkgroup\fR by default (i.e. there is no +way to prevent a Windows NT PDC from attempting to do this). This +means that if this parameter is set and \fBnmbd\fR claims +the special name for a \fIworkgroup\fR before a Windows +NT PDC is able to do so then cross subnet browsing will behave +strangely and may fail. + +If \fBdomain logons = yes\fR +, then the default behavior is to enable the \fIdomain +master\fR parameter. If \fIdomain logons\fR is +not enabled (the default setting), then neither will \fIdomain +master\fR be enabled by default. + +Default: \fBdomain master = auto\fR +.TP +\fBdont descend (S)\fR +There are certain directories on some systems +(e.g., the \fI/proc\fR tree under Linux) that are either not +of interest to clients or are infinitely deep (recursive). This +parameter allows you to specify a comma-delimited list of directories +that the server should always show as empty. + +Note that Samba can be very fussy about the exact format +of the "dont descend" entries. For example you may need \fI ./proc\fR instead of just \fI/proc\fR. +Experimentation is the best policy :-) + +Default: \fBnone (i.e., all directories are OK +to descend)\fR + +Example: \fBdont descend = /proc,/dev\fR +.TP +\fBdos filemode (S)\fR +The default behavior in Samba is to provide +UNIX-like behavior where only the owner of a file/directory is +able to change the permissions on it. However, this behavior +is often confusing to DOS/Windows users. Enabling this parameter +allows a user who has write access to the file (by whatever +means) to modify the permissions on it. Note that a user +belonging to the group owning the file will not be allowed to +change permissions if the group is only granted read access. +Ownership of the file/directory is not changed, only the permissions +are modified. + +Default: \fBdos filemode = no\fR +.TP +\fBdos filetime resolution (S)\fR +Under the DOS and Windows FAT filesystem, the finest +granularity on time resolution is two seconds. Setting this parameter +for a share causes Samba to round the reported time down to the +nearest two second boundary when a query call that requires one second +resolution is made to \fBsmbd(8)\fR +. + +This option is mainly used as a compatibility option for Visual +C++ when used against Samba shares. If oplocks are enabled on a +share, Visual C++ uses two different time reading calls to check if a +file has changed since it was last read. One of these calls uses a +one-second granularity, the other uses a two second granularity. As +the two second call rounds any odd second down, then if the file has a +timestamp of an odd number of seconds then the two timestamps will not +match and Visual C++ will keep reporting the file has changed. Setting +this option causes the two timestamps to match, and Visual C++ is +happy. + +Default: \fBdos filetime resolution = no\fR +.TP +\fBdos filetimes (S)\fR +Under DOS and Windows, if a user can write to a +file they can change the timestamp on it. Under POSIX semantics, +only the owner of the file or root may change the timestamp. By +default, Samba runs with POSIX semantics and refuses to change the +timestamp on a file if the user \fBsmbd\fR is acting +on behalf of is not the file owner. Setting this option to true allows DOS semantics and smbdwill change the file +timestamp as DOS requires. + +Default: \fBdos filetimes = no\fR +.TP +\fBencrypt passwords (G)\fR +This boolean controls whether encrypted passwords +will be negotiated with the client. Note that Windows NT 4.0 SP3 and +above and also Windows 98 will by default expect encrypted passwords +unless a registry entry is changed. To use encrypted passwords in +Samba see the file ENCRYPTION.txt in the Samba documentation +directory \fIdocs/\fR shipped with the source code. + +In order for encrypted passwords to work correctly +\fBsmbd(8)\fRmust either +have access to a local \fIsmbpasswd(5) +\fRprogram for information on how to set up +and maintain this file), or set the security = [server|domain] parameter which +causes \fBsmbd\fR to authenticate against another +server. -.SS guest account (S) -This is a username which will be used for access to services which are -specified as 'guest ok' (see below). Whatever privileges this user has -will be available to any client connecting to the guest -service. Typically this user will exist in the password file, but will -not have a valid login. If a username is specified in a given service, +Default: \fBencrypt passwords = no\fR +.TP +\fBenhanced browsing (G)\fR +This option enables a couple of enhancements to +cross-subnet browse propagation that have been added in Samba +but which are not standard in Microsoft implementations. + +The first enhancement to browse propagation consists of a regular +wildcard query to a Samba WINS server for all Domain Master Browsers, +followed by a browse synchronization with each of the returned +DMBs. The second enhancement consists of a regular randomised browse +synchronization with all currently known DMBs. + +You may wish to disable this option if you have a problem with empty +workgroups not disappearing from browse lists. Due to the restrictions +of the browse protocols these enhancements can cause a empty workgroup +to stay around forever which can be annoying. + +In general you should leave this option enabled as it makes +cross-subnet browse propagation much more reliable. + +Default: \fBenhanced browsing = yes\fR +.TP +\fBenumports command (G)\fR +The concept of a "port" is fairly foreign +to UNIX hosts. Under Windows NT/2000 print servers, a port +is associated with a port monitor and generally takes the form of +a local port (i.e. LPT1:, COM1:, FILE:) or a remote port +(i.e. LPD Port Monitor, etc...). By default, Samba has only one +port defined--"Samba Printer Port". Under +Windows NT/2000, all printers must have a valid port name. +If you wish to have a list of ports displayed (\fBsmbd +\fRdoes not use a port name for anything) other than +the default "Samba Printer Port", you +can define \fIenumports command\fR to point to +a program which should generate a list of ports, one per line, +to standard output. This listing will then be used in response +to the level 1 and 2 EnumPorts() RPC. + +Default: \fBno enumports command\fR + +Example: \fBenumports command = /usr/bin/listports +\fR.TP +\fBexec (S)\fR +This is a synonym for \fIpreexec\fR. +.TP +\fBfake directory create times (S)\fR +NTFS and Windows VFAT file systems keep a create +time for all files and directories. This is not the same as the +ctime - status change time - that Unix keeps, so Samba by default +reports the earliest of the various times Unix does keep. Setting +this parameter for a share causes Samba to always report midnight +1-1-1980 as the create time for directories. + +This option is mainly used as a compatibility option for +Visual C++ when used against Samba shares. Visual C++ generated +makefiles have the object directory as a dependency for each object +file, and a make rule to create the directory. Also, when NMAKE +compares timestamps it uses the creation time when examining a +directory. Thus the object directory will be created if it does not +exist, but once it does exist it will always have an earlier +timestamp than the object files it contains. + +However, Unix time semantics mean that the create time +reported by Samba will be updated whenever a file is created or +or deleted in the directory. NMAKE finds all object files in +the object directory. The timestamp of the last one built is then +compared to the timestamp of the object directory. If the +directory's timestamp if newer, then all object files +will be rebuilt. Enabling this option +ensures directories always predate their contents and an NMAKE build +will proceed as expected. + +Default: \fBfake directory create times = no\fR +.TP +\fBfake oplocks (S)\fR +Oplocks are the way that SMB clients get permission +from a server to locally cache file operations. If a server grants +an oplock (opportunistic lock) then the client is free to assume +that it is the only one accessing the file and it will aggressively +cache file data. With some oplock types the client may even cache +file open/close operations. This can give enormous performance benefits. + +When you set \fBfake oplocks = yes\fR, \fBsmbd(8)\fRwill +always grant oplock requests no matter how many clients are using +the file. + +It is generally much better to use the real \fIoplocks\fR support rather +than this parameter. + +If you enable this option on all read-only shares or +shares that you know will only be accessed from one client at a +time such as physically read-only media like CDROMs, you will see +a big performance improvement on many operations. If you enable +this option on shares where multiple clients may be accessing the +files read-write at the same time you can get data corruption. Use +this option carefully! + +Default: \fBfake oplocks = no\fR +.TP +\fBfollow symlinks (S)\fR +This parameter allows the Samba administrator +to stop \fBsmbd(8)\fR +from following symbolic links in a particular share. Setting this +parameter to no prevents any file or directory +that is a symbolic link from being followed (the user will get an +error). This option is very useful to stop users from adding a +symbolic link to \fI/etc/passwd\fR in their home +directory for instance. However it will slow filename lookups +down slightly. + +This option is enabled (i.e. \fBsmbd\fR will +follow symbolic links) by default. + +Default: \fBfollow symlinks = yes\fR +.TP +\fBforce create mode (S)\fR +This parameter specifies a set of UNIX mode bit +permissions that will \fBalways\fR be set on a +file created by Samba. This is done by bitwise 'OR'ing these bits onto +the mode bits of a file that is being created or having its +permissions changed. The default for this parameter is (in octal) +000. The modes in this parameter are bitwise 'OR'ed onto the file +mode after the mask set in the \fIcreate mask\fR +parameter is applied. + +See also the parameter \fIcreate +mask\fR for details on masking mode bits on files. + +See also the \fIinherit +permissions\fR parameter. + +Default: \fBforce create mode = 000\fR + +Example: \fBforce create mode = 0755\fR + +would force all created files to have read and execute +permissions set for 'group' and 'other' as well as the +read/write/execute bits set for the 'user'. +.TP +\fBforce directory mode (S)\fR +This parameter specifies a set of UNIX mode bit +permissions that will \fBalways\fR be set on a directory +created by Samba. This is done by bitwise 'OR'ing these bits onto the +mode bits of a directory that is being created. The default for this +parameter is (in octal) 0000 which will not add any extra permission +bits to a created directory. This operation is done after the mode +mask in the parameter \fIdirectory mask\fR is +applied. + +See also the parameter \fI directory mask\fR for details on masking mode bits +on created directories. + +See also the \fI inherit permissions\fR parameter. + +Default: \fBforce directory mode = 000\fR + +Example: \fBforce directory mode = 0755\fR + +would force all created directories to have read and execute +permissions set for 'group' and 'other' as well as the +read/write/execute bits set for the 'user'. +.TP +\fBforce directory security mode (S)\fR +This parameter controls what UNIX permission bits +can be modified when a Windows NT client is manipulating the UNIX +permission on a directory using the native NT security dialog box. + +This parameter is applied as a mask (OR'ed with) to the +changed permission bits, thus forcing any bits in this mask that +the user may have modified to be on. Essentially, one bits in this +mask may be treated as a set of bits that, when modifying security +on a directory, the user has always set to be 'on'. + +If not set explicitly this parameter is 000, which +allows a user to modify all the user/group/world permissions on a +directory without restrictions. + +\fBNote\fR that users who can access the +Samba server through other means can easily bypass this restriction, +so it is primarily useful for standalone "appliance" systems. +Administrators of most normal systems will probably want to leave +it set as 0000. + +See also the \fI directory security mask\fR, \fIsecurity mask\fR, +\fIforce security mode +\fRparameters. + +Default: \fBforce directory security mode = 0\fR + +Example: \fBforce directory security mode = 700\fR +.TP +\fBforce group (S)\fR +This specifies a UNIX group name that will be +assigned as the default primary group for all users connecting +to this service. This is useful for sharing files by ensuring +that all access to files on service will use the named group for +their permissions checking. Thus, by assigning permissions for this +group to the files and directories within this service the Samba +administrator can restrict or allow sharing of these files. + +In Samba 2.0.5 and above this parameter has extended +functionality in the following way. If the group name listed here +has a '+' character prepended to it then the current user accessing +the share only has the primary group default assigned to this group +if they are already assigned as a member of that group. This allows +an administrator to decide that only users who are already in a +particular group will create files with group ownership set to that +group. This gives a finer granularity of ownership assignment. For +example, the setting \fIforce group = +sys\fR means +that only users who are already in group sys will have their default +primary group assigned to sys when accessing this Samba share. All +other users will retain their ordinary primary group. + +If the \fIforce user +\fRparameter is also set the group specified in +\fIforce group\fR will override the primary group +set in \fIforce user\fR. + +See also \fIforce +user\fR. + +Default: \fBno forced group\fR + +Example: \fBforce group = agroup\fR +.TP +\fBforce security mode (S)\fR +This parameter controls what UNIX permission +bits can be modified when a Windows NT client is manipulating +the UNIX permission on a file using the native NT security dialog +box. + +This parameter is applied as a mask (OR'ed with) to the +changed permission bits, thus forcing any bits in this mask that +the user may have modified to be on. Essentially, one bits in this +mask may be treated as a set of bits that, when modifying security +on a file, the user has always set to be 'on'. + +If not set explicitly this parameter is set to 0, +and allows a user to modify all the user/group/world permissions on a file, +with no restrictions. + +\fBNote\fR that users who can access +the Samba server through other means can easily bypass this restriction, +so it is primarily useful for standalone "appliance" systems. +Administrators of most normal systems will probably want to leave +this set to 0000. + +See also the \fI force directory security mode\fR, +\fIdirectory security +mask\fR, \fI security mask\fR parameters. + +Default: \fBforce security mode = 0\fR + +Example: \fBforce security mode = 700\fR +.TP +\fBforce user (S)\fR +This specifies a UNIX user name that will be +assigned as the default user for all users connecting to this service. +This is useful for sharing files. You should also use it carefully +as using it incorrectly can cause security problems. + +This user name only gets used once a connection is established. +Thus clients still need to connect as a valid user and supply a +valid password. Once connected, all file operations will be performed +as the "forced user", no matter what username the client connected +as. This can be very useful. + +In Samba 2.0.5 and above this parameter also causes the +primary group of the forced user to be used as the primary group +for all file activity. Prior to 2.0.5 the primary group was left +as the primary group of the connecting user (this was a bug). + +See also \fIforce group +\fR +Default: \fBno forced user\fR + +Example: \fBforce user = auser\fR +.TP +\fBfstype (S)\fR +This parameter allows the administrator to +configure the string that specifies the type of filesystem a share +is using that is reported by \fBsmbd(8) +\fRwhen a client queries the filesystem type +for a share. The default type is NTFS for +compatibility with Windows NT but this can be changed to other +strings such as Samba or FAT +if required. + +Default: \fBfstype = NTFS\fR + +Example: \fBfstype = Samba\fR +.TP +\fBgetwd cache (G)\fR +This is a tuning option. When this is enabled a +caching algorithm will be used to reduce the time taken for getwd() +calls. This can have a significant impact on performance, especially +when the \fIwide links\fR +parameter is set to false. + +Default: \fBgetwd cache = yes\fR +.TP +\fBgroup (S)\fR +Synonym for \fIforce +group\fR. +.TP +\fBguest account (S)\fR +This is a username which will be used for access +to services which are specified as \fI guest ok\fR (see below). Whatever privileges this +user has will be available to any client connecting to the guest service. +Typically this user will exist in the password file, but will not +have a valid login. The user account "ftp" is often a good choice +for this parameter. If a username is specified in a given service, the specified username overrides this one. -One some systems the account "nobody" may not be able to print. Use -another account in this case. You should test this by trying to log in -as your guest user (perhaps by using the "su -" command) and trying to -print using lpr. - -Note that as of version 1.9 of Samba this option may be set -differently for each service. - -.B Default: - specified at compile time - -.B Example: - guest account = nobody -.SS getwd cache (G) -This is a tuning option. When this is enabled a cacheing algorithm will -be used to reduce the time taken for getwd() calls. This can have a -significant impact on performance, especially when widelinks is False. - -.B Default: - getwd cache = No - -.B Example: - getwd cache = Yes -.SS guest ok (S) -See -.B public. -.SS guest only (S) -If this parameter is 'yes' for a service, then only guest connections to the -service are permitted. This parameter will have no affect if "guest ok" or -"public" is not set for the service. - -See the section below on user/password validation for more information about -this option. - -.B Default: - guest only = no - -.B Example: - guest only = yes -.SS hide dot files (S) -This is a boolean parameter that controls whether files starting with -a dot appear as hidden files. - -.B Default: - hide dot files = yes - -.B Example: - hide dot files = no -.SS hosts allow (S) -See -.B allow hosts. -.SS hosts deny (S) -See -.B deny hosts. - -.SS group (S) -This is an alias for "force group" and is only kept for compatability -with old versions of Samba. It may be removed in future versions. - -.SS hosts equiv (G) -If this global parameter is a non-null string, it specifies the name of -a file to read for the names of hosts and users who will be allowed access -without specifying a password. - -This is not be confused with -.B allow hosts -which is about hosts access to services and is more useful for guest services. -.B hosts equiv -may be useful for NT clients which will not supply passwords to samba. - -NOTE: The use of hosts.equiv can be a major security hole. This is -because you are trusting the PC to supply the correct username. It is -very easy to get a PC to supply a false username. I recommend that the -hosts.equiv option be only used if you really know what you are doing, -or perhaps on a home network where you trust your wife and kids :-) - -.B Default - No host equivalences - -.B Example - hosts equiv = /etc/hosts.equiv - -.SS invalid users (S) -This is a list of users that should not be allowed to login to this -service. This is really a "paranoid" check to absolutely ensure an -improper setting does not breach your security. - -A name starting with @ is interpreted as a unix group. - -The current servicename is substituted for %S. This is useful in the -[homes] section. - -See also "valid users" - -.B Default - No invalid users - -.B Example - invalid users = root fred admin @wheel - -.SS include (G) - -This allows you to inlcude one config file inside another. the file is -included literally, as though typed in place. - -It takes the standard substitutions, except %u, %P and %S - -.SS keep alive (G) -The value of the parameter (an integer) represents the number of seconds -between 'keepalive' packets. If this parameter is zero, no keepalive packets -will be sent. Keepalive packets, if sent, allow the server to tell whether a -client is still present and responding. - -Keepalives should, in general, not be needed if the socket being used -has the SO_KEEPALIVE attribute set on it (see "socket -options"). Basically you should only use this option if you strike -difficulties. - -.B Default: - keep alive = 0 - -.B Example: - keep alive = 60 -.SS load printers (G) -A boolean variable that controls whether all printers in the printcap -will be loaded for browsing by default. - -.B Default: - load printers = no - -.B Example: - load printers = yes - -.SS lock directory (G) -This options specifies the directory where lock files will be placed. -The lock files are used to implement the "max connections" option. - -.B Default: - lock directory = /tmp/samba - -.B Example: - lock directory = /usr/local/samba/locks -.SS locking (S) -This controls whether or not locking will be performed by the server in -response to lock requests from the client. - -If "locking = no", all lock and unlock requests will appear to succeed and -all lock queries will indicate that the queried lock is clear. - -If "locking = yes", real locking will be performed by the server. - -This option may be particularly useful for read-only filesystems which -do not need locking (such as cdrom drives). - -Be careful about disabling locking either globally or in a specific -service, as lack of locking may result in data corruption. - -.B Default: - locking = yes - -.B Example: - locking = no - -.SS log file (G) - -This options allows you to override the name of the Samba log file -(also known as the debug file). +One some systems the default guest account "nobody" may not +be able to print. Use another account in this case. You should test +this by trying to log in as your guest user (perhaps by using the +\fBsu -\fR command) and trying to print using the +system print command such as \fBlpr(1)\fR or \fB lp(1)\fR. + +Default: \fBspecified at compile time, usually +"nobody"\fR + +Example: \fBguest account = ftp\fR +.TP +\fBguest ok (S)\fR +If this parameter is yes for +a service, then no password is required to connect to the service. +Privileges will be those of the \fI guest account\fR. + +See the section below on \fI security\fR for more information about this option. + +Default: \fBguest ok = no\fR +.TP +\fBguest only (S)\fR +If this parameter is yes for +a service, then only guest connections to the service are permitted. +This parameter will have no effect if \fIguest ok\fR is not set for the service. + +See the section below on \fI security\fR for more information about this option. + +Default: \fBguest only = no\fR +.TP +\fBhide dot files (S)\fR +This is a boolean parameter that controls whether +files starting with a dot appear as hidden files. + +Default: \fBhide dot files = yes\fR +.TP +\fBhide files(S)\fR +This is a list of files or directories that are not +visible but are accessible. The DOS 'hidden' attribute is applied +to any files or directories that match. + +Each entry in the list must be separated by a '/', +which allows spaces to be included in the entry. '*' +and '?' can be used to specify multiple files or directories +as in DOS wildcards. + +Each entry must be a Unix path, not a DOS path and must +not include the Unix directory separator '/'. + +Note that the case sensitivity option is applicable +in hiding files. + +Setting this parameter will affect the performance of Samba, +as it will be forced to check all files and directories for a match +as they are scanned. + +See also \fIhide +dot files\fR, \fI veto files\fR and \fIcase sensitive\fR. + +Default: \fBno file are hidden\fR + +Example: \fBhide files = +/.*/DesktopFolderDB/TrashFor%m/resource.frk/\fR + +The above example is based on files that the Macintosh +SMB client (DAVE) available from +Thursby <URL:http://www.thursby.com> creates for internal use, and also still hides +all files beginning with a dot. +.TP +\fBhide local users(G)\fR +This parameter toggles the hiding of local UNIX +users (root, wheel, floppy, etc) from remote clients. + +Default: \fBhide local users = no\fR +.TP +\fBhide unreadable (S)\fR +This parameter prevents clients from seeing the +existance of files that cannot be read. Defaults to off. + +Default: \fBhide unreadable = no\fR +.TP +\fBhomedir map (G)\fR +If\fInis homedir +\fRis true, and \fBsmbd(8)\fRis also acting +as a Win95/98 \fIlogon server\fR then this parameter +specifies the NIS (or YP) map from which the server for the user's +home directory should be extracted. At present, only the Sun +auto.home map format is understood. The form of the map is: + +\fBusername server:/some/file/system\fR + +and the program will extract the servername from before +the first ':'. There should probably be a better parsing system +that copes with different map formats and also Amd (another +automounter) maps. + +\fBNOTE :\fRA working NIS client is required on +the system for this option to work. + +See also \fInis homedir\fR +, \fIdomain logons\fR +\&. + +Default: \fBhomedir map = <empty string>\fR + +Example: \fBhomedir map = amd.homedir\fR +.TP +\fBhost msdfs (G)\fR +This boolean parameter is only available +if Samba has been configured and compiled with the \fB --with-msdfs\fR option. If set to yes, +Samba will act as a Dfs server, and allow Dfs-aware clients +to browse Dfs trees hosted on the server. + +See also the \fI msdfs root\fR share level parameter. For +more information on setting up a Dfs tree on Samba, +refer to msdfs_setup.html. + +Default: \fBhost msdfs = no\fR +.TP +\fBhosts allow (S)\fR +A synonym for this parameter is \fIallow +hosts\fR. + +This parameter is a comma, space, or tab delimited +set of hosts which are permitted to access a service. + +If specified in the [global] section then it will +apply to all services, regardless of whether the individual +service has a different setting. + +You can specify the hosts by name or IP number. For +example, you could restrict access to only the hosts on a +Class C subnet with something like \fBallow hosts = 150.203.5. +\fR\&. The full syntax of the list is described in the man +page \fIhosts_access(5)\fR. Note that this man +page may not be present on your system, so a brief description will +be given here also. + +Note that the localhost address 127.0.0.1 will always +be allowed access unless specifically denied by a \fIhosts deny\fR option. + +You can also specify hosts by network/netmask pairs and +by netgroup names if your system supports netgroups. The +\fBEXCEPT\fR keyword can also be used to limit a +wildcard list. The following examples may provide some help: + +Example 1: allow all IPs in 150.203.*.*; except one + +\fBhosts allow = 150.203. EXCEPT 150.203.6.66\fR -This option takes the standard substitutions, allowing you to have -separate log files for each user or machine. - -.B Example: - log file = /usr/local/samba/log.%m - -.SS log level (G) -see "debug level" - -.SS lppause command (S) -This parameter specifies the command to be executed on the server host in -order to stop printing or spooling a specific print job. - -This command should be a program or script which takes a printer name and -job number to pause the print job. Currently I don't know of any print -spooler system that can do this with a simple option, except for the PPR -system from Trinity College (ppr\-dist.trincoll.edu/pub/ppr). One way -of implementing this is by using job priorities, where jobs having a too -low priority wont be sent to the printer. See also the lppause command. - -If a %p is given then the printername is put in it's place. A %j is -replaced with the job number (an integer). -On HPUX (see printing=hpux), if the -p%p option is added to the lpq -command, the job will show up with the correct status, i.e. if the job -priority is lower than the set fence priority it will have the PAUSED -status, whereas if the priority is equal or higher it will have the -SPOOLED or PRINTING status. - -Note that it is good practice to include the absolute path in the lppause -command as the PATH may not be available to the server. - -.B Default: - Currently no default value is given to this string - -.B Example for HPUX: - lppause command = /usr/bin/lpalt %p-%j -p0 - -.SS lpq cache time (G) - -This controls how long lpq info will be cached for to prevent the lpq -command being called too often. A separate cache is kept for each -variation of the lpq command used by the system, so if you use -different lpq commands for different users then they won't share cache -information. - -The cache files are stored in /tmp/lpq.xxxx where xxxx is a hash -of the lpq command in use. - -The default is 10 seconds, meaning that the cached results of a -previous identical lpq command will be used if the cached data is less -than 10 seconds old. A large value may be advisable if your lpq -command is very slow. - -A value of 0 will disable cacheing completely. - -.B Default: - lpq cache time = 10 - -.B Example: - lpq cache time = 30 - -.SS lpq command (S) -This parameter specifies the command to be executed on the server host in -order to obtain "lpq"-style printer status information. - -This command should be a program or script which takes a printer name -as its only parameter and outputs printer status information. - -Currently four styles of printer status information are supported; -BSD, SYSV, AIX and HPUX. This covers most unix systems. You control -which type is expected using the "printing =" option. - -Some clients (notably Windows for Workgroups) may not correctly send the -connection number for the printer they are requesting status information -about. To get around this, the server reports on the first printer service -connected to by the client. This only happens if the connection number sent -is invalid. - -If a %p is given then the printername is put in it's place. Otherwise -it is placed at the end of the command. - -Note that it is good practice to include the absolute path in the lpq -command as the PATH may not be available to the server. - -.B Default: - depends on the setting of "printing =" - -.B Example: - lpq command = /usr/bin/lpq %p - -.SS lpresume command (S) -This parameter specifies the command to be executed on the server host in -order to restart or continue printing or spooling a specific print job. - -This command should be a program or script which takes a printer name and -job number to resume the print job. See also the lppause command. - -If a %p is given then the printername is put in it's place. A %j is -replaced with the job number (an integer). - -Note that it is good practice to include the absolute path in the lpresume -command as the PATH may not be available to the server. - -.B Default: - Currently no default value is given to this string - -.B Example for HPUX: - lpresume command = /usr/bin/lpalt %p-%j -p2 - -.SS lprm command (S) -This parameter specifies the command to be executed on the server host in -order to delete a print job. - -This command should be a program or script which takes a printer name -and job number, and deletes the print job. - -Currently four styles of printer control are supported; BSD, SYSV, AIX -and HPUX. This covers most unix systems. You control which type is -expected using the "printing =" option. - -If a %p is given then the printername is put in it's place. A %j is -replaced with the job number (an integer). - -Note that it is good practice to include the absolute path in the lprm -command as the PATH may not be available to the server. - -.B Default: - depends on the setting of "printing =" - -.B Example 1: - lprm command = /usr/bin/lprm -P%p %j - -.B Example 2: - lprm command = /usr/bin/cancel %p-%j - -.SS magic output (S) -This parameter specifies the name of a file which will contain output -created by a magic script (see -.I magic script -below). - -Warning: If two clients use the same magic script in the same directory the -output file content is undefined. -.B Default: - magic output = <magic script name>.out - -.B Example: - magic output = myfile.txt -.SS magic script (S) -This parameter specifies the name of a file which, if opened, will be -executed by the server when the file is closed. This allows a Unix script -to be sent to the Samba host and executed on behalf of the connected user. - -Scripts executed in this way will be deleted upon completion, permissions -permitting. - -If the script generates output, output will be sent to the file specified by -the -.I magic output -parameter (see above). - -Note that some shells are unable to interpret scripts containing -carriage-return-linefeed instead of linefeed as the end-of-line -marker. Magic scripts must be executable "as is" on the host, which -for some hosts and some shells will require filtering at the DOS end. - -Magic scripts are EXPERIMENTAL and should NOT be relied upon. -.B Default: - None. Magic scripts disabled. - -.B Example: - magic script = user.csh -.SS mangled map (S) -This is for those who want to directly map UNIX file names which are -not representable on DOS. The mangling of names is not always what is -needed. In particular you may have documents with file extensiosn -that differ between dos and unix. For example, under unix it is common -to use .html for HTML files, whereas under dos .htm is more commonly -used. - -So to map 'html' to 'htm' you put: - - mangled map = (*.html *.htm) +Example 2: allow hosts that match the given network/netmask -One very useful case is to remove the annoying ;1 off the ends of -filenames on some CDROMS (only visible under some unixes). To do this -use a map of (*;1 *) +\fBhosts allow = 150.203.15.0/255.255.255.0\fR -.B default: - no mangled map +Example 3: allow a couple of hosts -.B Example: - mangled map = (*;1 *) +\fBhosts allow = lapland, arvidsjaur\fR -.SS mangle case (S) +Example 4: allow only hosts in NIS netgroup "foonet", but +deny access from one particular host -See the section on "NAME MANGLING" +\fBhosts allow = @foonet\fR -.SS mangled names (S) -This controls whether non-DOS names under Unix should be mapped to -DOS-compatible names ("mangled") and made visible, or whether non-DOS names -should simply be ignored. +\fBhosts deny = pirate\fR -See the section on "NAME MANGLING" for details on how to control the -mangling process. +Note that access still requires suitable user-level passwords. -If mangling is used then the mangling algorithm is as follows: +See \fBtestparm(1)\fR +for a way of testing your host access to see if it does +what you expect. + +Default: \fBnone (i.e., all hosts permitted access) +\fR +Example: \fBallow hosts = 150.203.5. myhost.mynet.edu.au +\fR.TP +\fBhosts deny (S)\fR +The opposite of \fIhosts allow\fR +- hosts listed here are \fBNOT\fR permitted access to +services unless the specific services have their own lists to override +this one. Where the lists conflict, the \fIallow\fR +list takes precedence. + +Default: \fBnone (i.e., no hosts specifically excluded) +\fR +Example: \fBhosts deny = 150.203.4. badhost.mynet.edu.au +\fR.TP +\fBhosts equiv (G)\fR +If this global parameter is a non-null string, +it specifies the name of a file to read for the names of hosts +and users who will be allowed access without specifying a password. + +This is not be confused with \fIhosts allow\fR which is about hosts +access to services and is more useful for guest services. \fI hosts equiv\fR may be useful for NT clients which will +not supply passwords to Samba. + +\fBNOTE :\fR The use of \fIhosts equiv +\fRcan be a major security hole. This is because you are +trusting the PC to supply the correct username. It is very easy to +get a PC to supply a false username. I recommend that the +\fIhosts equiv\fR option be only used if you really +know what you are doing, or perhaps on a home network where you trust +your spouse and kids. And only if you \fBreally\fR trust +them :-). + +Default: \fBno host equivalences\fR + +Example: \fBhosts equiv = /etc/hosts.equiv\fR +.TP +\fBinclude (G)\fR +This allows you to include one config file +inside another. The file is included literally, as though typed +in place. + +It takes the standard substitutions, except \fI%u +\fR, \fI%P\fR and \fI%S\fR. + +Default: \fBno file included\fR + +Example: \fBinclude = /usr/local/samba/lib/admin_smb.conf +\fR.TP +\fBinherit permissions (S)\fR +The permissions on new files and directories +are normally governed by \fI create mask\fR, \fIdirectory mask\fR, \fIforce create mode\fR +and \fIforce +directory mode\fR but the boolean inherit +permissions parameter overrides this. + +New directories inherit the mode of the parent directory, +including bits such as setgid. + +New files inherit their read/write bits from the parent +directory. Their execute bits continue to be determined by +\fImap archive\fR +, \fImap hidden\fR +and \fImap system\fR +as usual. + +Note that the setuid bit is \fBnever\fR set via +inheritance (the code explicitly prohibits this). + +This can be particularly useful on large systems with +many users, perhaps several thousand, to allow a single [homes] +share to be used flexibly by each user. + +See also \fIcreate mask +\fR, \fI directory mask\fR, \fIforce create mode\fR and \fIforce directory mode\fR +\&. + +Default: \fBinherit permissions = no\fR +.TP +\fBinterfaces (G)\fR +This option allows you to override the default +network interfaces list that Samba will use for browsing, name +registration and other NBT traffic. By default Samba will query +the kernel for the list of all active interfaces and use any +interfaces except 127.0.0.1 that are broadcast capable. + +The option takes a list of interface strings. Each string +can be in any of the following forms: .RS -- the first (up to) five alphanumeric characters before the rightmost dot of -the filename are preserved, forced to upper case, and appear as the first (up -to) five characters of the mangled name. - -- a tilde ("~") is appended to the first part of the mangled name, followed -by a two-character unique sequence, based on the origonal root name -(i.e., the original filename minus its final extension). The final -extension is included in the hash calculation only if it contains any upper -case characters or is longer than three characters. - -Note that the character to use may be specified using the "mangling -char" option, if you don't like ~. - -- the first three alphanumeric characters of the final extension are preserved, -forced to upper case and appear as the extension of the mangled name. The -final extension is defined as that part of the original filename after the -rightmost dot. If there are no dots in the filename, the mangled name will -have no extension (except in the case of hidden files - see below). - -- files whose Unix name begins with a dot will be presented as DOS hidden -files. The mangled name will be created as for other filenames, but with the -leading dot removed and "___" as its extension regardless of actual original -extension (that's three underscores). +.TP 0.2i +\(bu +a network interface name (such as eth0). +This may include shell-like wildcards so eth* will match +any interface starting with the substring "eth" +.TP 0.2i +\(bu +an IP address. In this case the netmask is +determined from the list of interfaces obtained from the +kernel +.TP 0.2i +\(bu +an IP/mask pair. +.TP 0.2i +\(bu +a broadcast/mask pair. .RE +.PP +The "mask" parameters can either be a bit length (such +as 24 for a C class network) or a full netmask in dotted +decimal form. +.PP +.PP +The "IP" parameters above can either be a full dotted +decimal IP address or a hostname which will be looked up via +the OS's normal hostname resolution mechanisms. +.PP +.PP +For example, the following line: +.PP +.PP +\fBinterfaces = eth0 192.168.2.10/24 192.168.3.10/255.255.255.0 +\fR.PP +.PP +would configure three network interfaces corresponding +to the eth0 device and IP addresses 192.168.2.10 and 192.168.3.10. +The netmasks of the latter two interfaces would be set to 255.255.255.0. +.PP +.PP +See also \fIbind +interfaces only\fR. +.PP +.PP +Default: \fBall active interfaces except 127.0.0.1 +that are broadcast capable\fR +.PP +.TP +\fBinvalid users (S)\fR +This is a list of users that should not be allowed +to login to this service. This is really a \fBparanoid\fR +check to absolutely ensure an improper setting does not breach +your security. + +A name starting with a '@' is interpreted as an NIS +netgroup first (if your system supports NIS), and then as a UNIX +group if the name was not found in the NIS netgroup database. + +A name starting with '+' is interpreted only +by looking in the UNIX group database. A name starting with +\&'&' is interpreted only by looking in the NIS netgroup database +(this requires NIS to be working on your system). The characters +\&'+' and '&' may be used at the start of the name in either order +so the value \fI+&group\fR means check the +UNIX group database, followed by the NIS netgroup database, and +the value \fI&+group\fR means check the NIS +netgroup database, followed by the UNIX group database (the +same as the '@' prefix). + +The current servicename is substituted for \fI%S\fR. +This is useful in the [homes] section. + +See also \fIvalid users +\fR\&. + +Default: \fBno invalid users\fR + +Example: \fBinvalid users = root fred admin @wheel +\fR.TP +\fBkeepalive (G)\fR +The value of the parameter (an integer) represents +the number of seconds between \fIkeepalive\fR +packets. If this parameter is zero, no keepalive packets will be +sent. Keepalive packets, if sent, allow the server to tell whether +a client is still present and responding. + +Keepalives should, in general, not be needed if the socket +being used has the SO_KEEPALIVE attribute set on it (see \fIsocket options\fR). +Basically you should only use this option if you strike difficulties. + +Default: \fBkeepalive = 300\fR + +Example: \fBkeepalive = 600\fR +.TP +\fBkernel oplocks (G)\fR +For UNIXes that support kernel based \fIoplocks\fR +(currently only IRIX and the Linux 2.4 kernel), this parameter +allows the use of them to be turned on or off. + +Kernel oplocks support allows Samba \fIoplocks +\fRto be broken whenever a local UNIX process or NFS operation +accesses a file that \fBsmbd(8)\fR +has oplocked. This allows complete data consistency between +SMB/CIFS, NFS and local file access (and is a \fBvery\fR +cool feature :-). + +This parameter defaults to on, but is translated +to a no-op on systems that no not have the necessary kernel support. +You should never need to touch this parameter. + +See also the \fIoplocks\fR +and \fIlevel2 oplocks +\fRparameters. + +Default: \fBkernel oplocks = yes\fR +.TP +\fBlanman auth (G)\fR +This parameter determines whether or not smbdwill +attempt to authenticate users using the LANMAN password hash. +If disabled, only clients which support NT password hashes (e.g. Windows +NT/2000 clients, smbclient, etc... but not Windows 95/98 or the MS DOS +network client) will be able to connect to the Samba host. + +Default : \fBlanman auth = yes\fR +.TP +\fBlarge readwrite (G)\fR +This parameter determines whether or not smbd +supports the new 64k streaming read and write varient SMB requests introduced +with Windows 2000. Note that due to Windows 2000 client redirector bugs +this requires Samba to be running on a 64-bit capable operating system such +as IRIX, Solaris or a Linux 2.4 kernel. Can improve performance by 10% with +Windows 2000 clients. Defaults to off. Not as tested as some other Samba +code paths. + +Default : \fBlarge readwrite = no\fR +.TP +\fBldap admin dn (G)\fR +This parameter is only available if Samba has been +configure to include the \fB--with-ldapsam\fR option +at compile time. This option should be considered experimental and +under active development. + +The \fIldap admin dn\fR defines the Distinguished +Name (DN) name used by Samba to contact the ldap +server when retreiving user account information. The \fIldap +admin dn\fR is used in conjunction with the admin dn password +stored in the \fIprivate/secrets.tdb\fR file. See the +\fBsmbpasswd(8)\fRman +page for more information on how to accmplish this. + +Default : \fBnone\fR +.TP +\fBldap filter (G)\fR +This parameter is only available if Samba has been +configure to include the \fB--with-ldapsam\fR option +at compile time. This option should be considered experimental and +under active development. + +This parameter specifies the RFC 2254 compliant LDAP search filter. +The default is to match the login name with the uid +attribute for all entries matching the sambaAccount +objectclass. Note that this filter should only return one entry. + +Default : \fBldap filter = (&(uid=%u)(objectclass=sambaAccount))\fR +.TP +\fBldap port (G)\fR +This parameter is only available if Samba has been +configure to include the \fB--with-ldapsam\fR option +at compile time. This option should be considered experimental and +under active development. + +This option is used to control the tcp port number used to contact +the \fIldap server\fR. +The default is to use the stand LDAP port 389. + +Default : \fBldap port = 389\fR +.TP +\fBldap server (G)\fR +This parameter is only available if Samba has been +configure to include the \fB--with-ldapsam\fR option +at compile time. This option should be considered experimental and +under active development. + +This parameter should contains the FQDN of the ldap directory +server which should be queried to locate user account information. + +Default : \fBldap server = localhost\fR +.TP +\fBldap ssl (G)\fR +This parameter is only available if Samba has been +configure to include the \fB--with-ldapsam\fR option +at compile time. This option should be considered experimental and +under active development. + +This option is used to define whether or not Samba should +use SSL when connecting to the \fIldap +server\fR. This is \fBNOT\fR related to +Samba SSL support which is enabled by specifying the +\fB--with-ssl\fR option to the \fIconfigure\fR +script (see \fIssl\fR). + +The \fIldap ssl\fR can be set to one of three values: +(a) \fBon\fR - Always use SSL when contacting the +\fIldap server\fR, (b) \fBoff\fR - +Never use SSL when querying the directory, or (c) \fBstart +tls\fR - Use the LDAPv3 StartTLS extended operation +(RFC2830) for communicating with the directory server. + +Default : \fBldap ssl = off\fR +.TP +\fBldap suffix (G)\fR +This parameter is only available if Samba has been +configure to include the \fB--with-ldapsam\fR option +at compile time. This option should be considered experimental and +under active development. + +Default : \fBnone\fR +.TP +\fBlevel2 oplocks (S)\fR +This parameter controls whether Samba supports +level2 (read-only) oplocks on a share. + +Level2, or read-only oplocks allow Windows NT clients +that have an oplock on a file to downgrade from a read-write oplock +to a read-only oplock once a second client opens the file (instead +of releasing all oplocks on a second open, as in traditional, +exclusive oplocks). This allows all openers of the file that +support level2 oplocks to cache the file for read-ahead only (ie. +they may not cache writes or lock requests) and increases performance +for many accesses of files that are not commonly written (such as +application .EXE files). + +Once one of the clients which have a read-only oplock +writes to the file all clients are notified (no reply is needed +or waited for) and told to break their oplocks to "none" and +delete any read-ahead caches. + +It is recommended that this parameter be turned on +to speed access to shared executables. + +For more discussions on level2 oplocks see the CIFS spec. + +Currently, if \fIkernel +oplocks\fR are supported then level2 oplocks are +not granted (even if this parameter is set to yes). +Note also, the \fIoplocks\fR +parameter must be set to true on this share in order for +this parameter to have any effect. + +See also the \fIoplocks\fR +and \fIkernel oplocks\fR +parameters. + +Default: \fBlevel2 oplocks = yes\fR +.TP +\fBlm announce (G)\fR +This parameter determines if \fBnmbd(8)\fRwill produce Lanman announce +broadcasts that are needed by OS/2 clients in order for them to see +the Samba server in their browse list. This parameter can have three +values, true, false, or +auto. The default is auto. +If set to false Samba will never produce these +broadcasts. If set to true Samba will produce +Lanman announce broadcasts at a frequency set by the parameter +\fIlm interval\fR. If set to auto +Samba will not send Lanman announce broadcasts by default but will +listen for them. If it hears such a broadcast on the wire it will +then start sending them at a frequency set by the parameter +\fIlm interval\fR. + +See also \fIlm interval +\fR\&. + +Default: \fBlm announce = auto\fR + +Example: \fBlm announce = yes\fR +.TP +\fBlm interval (G)\fR +If Samba is set to produce Lanman announce +broadcasts needed by OS/2 clients (see the \fIlm announce\fR parameter) then this +parameter defines the frequency in seconds with which they will be +made. If this is set to zero then no Lanman announcements will be +made despite the setting of the \fIlm announce\fR +parameter. + +See also \fIlm +announce\fR. + +Default: \fBlm interval = 60\fR + +Example: \fBlm interval = 120\fR +.TP +\fBload printers (G)\fR +A boolean variable that controls whether all +printers in the printcap will be loaded for browsing by default. +See the printers section for +more details. + +Default: \fBload printers = yes\fR +.TP +\fBlocal master (G)\fR +This option allows \fB nmbd(8)\fRto try and become a local master browser +on a subnet. If set to false then \fB nmbd\fR will not attempt to become a local master browser +on a subnet and will also lose in all browsing elections. By +default this value is set to true. Setting this value to true doesn't +mean that Samba will \fBbecome\fR the local master +browser on a subnet, just that \fBnmbd\fR will \fB participate\fR in elections for local master browser. + +Setting this value to false will cause \fBnmbd\fR +\fBnever\fR to become a local master browser. + +Default: \fBlocal master = yes\fR +.TP +\fBlock dir (G)\fR +Synonym for \fI lock directory\fR. +.TP +\fBlock directory (G)\fR +This option specifies the directory where lock +files will be placed. The lock files are used to implement the +\fImax connections\fR +option. + +Default: \fBlock directory = ${prefix}/var/locks\fR + +Example: \fBlock directory = /var/run/samba/locks\fR +.TP +\fBlocking (S)\fR +This controls whether or not locking will be +performed by the server in response to lock requests from the +client. + +If \fBlocking = no\fR, all lock and unlock +requests will appear to succeed and all lock queries will report +that the file in question is available for locking. + +If \fBlocking = yes\fR, real locking will be performed +by the server. + +This option \fBmay\fR be useful for read-only +filesystems which \fBmay\fR not need locking (such as +CDROM drives), although setting this parameter of no +is not really recommended even in this case. + +Be careful about disabling locking either globally or in a +specific service, as lack of locking may result in data corruption. +You should never need to set this parameter. + +Default: \fBlocking = yes\fR +.TP +\fBlog file (G)\fR +This option allows you to override the name +of the Samba log file (also known as the debug file). + +This option takes the standard substitutions, allowing +you to have separate log files for each user or machine. + +Example: \fBlog file = /usr/local/samba/var/log.%m +\fR.TP +\fBlog level (G)\fR +The value of the parameter (an integer) allows +the debug level (logging level) to be specified in the +\fIsmb.conf\fR file. This is to give greater +flexibility in the configuration of the system. + +The default will be the log level specified on +the command line or level zero if none was specified. + +Example: \fBlog level = 3\fR +.TP +\fBlogon drive (G)\fR +This parameter specifies the local path to +which the home directory will be connected (see \fIlogon home\fR) +and is only used by NT Workstations. + +Note that this option is only useful if Samba is set up as a +logon server. + +Default: \fBlogon drive = z:\fR + +Example: \fBlogon drive = h:\fR +.TP +\fBlogon home (G)\fR +This parameter specifies the home directory +location when a Win95/98 or NT Workstation logs into a Samba PDC. +It allows you to do + +C:\\> \fBNET USE H: /HOME\fR + +from a command prompt, for example. + +This option takes the standard substitutions, allowing +you to have separate logon scripts for each user or machine. + +This parameter can be used with Win9X workstations to ensure +that roaming profiles are stored in a subdirectory of the user's +home directory. This is done in the following way: + +\fBlogon home = \\\\%N\\%U\\profile\fR + +This tells Samba to return the above string, with +substitutions made when a client requests the info, generally +in a NetUserGetInfo request. Win9X clients truncate the info to +\\\\server\\share when a user does \fBnet use /home\fR +but use the whole string when dealing with profiles. + +Note that in prior versions of Samba, the \fIlogon path\fR was returned rather than +\fIlogon home\fR. This broke \fBnet use +/home\fR but allowed profiles outside the home directory. +The current implementation is correct, and can be used for +profiles if you use the above trick. + +This option is only useful if Samba is set up as a logon +server. -The two-digit hash value consists of upper case alphanumeric characters. - -This algorithm can cause name collisions only if files in a directory share -the same first five alphanumeric characters. The probability of such a clash -is 1/1300. - -The name mangling (if enabled) allows a file to be copied between Unix -directories from DOS while retaining the long Unix filename. Unix files can -be renamed to a new extension from DOS and will retain the same basename. -Mangled names do not change between sessions. - -.B Default: - mangled names = yes - -.B Example: - mangled names = no -.SS mangling char (S) -This controls what character is used as the "magic" character in name -mangling. The default is a ~ but this may interfere with some -software. Use this option to set it to whatever you prefer. +Default: \fBlogon home = "\\\\%N\\%U"\fR + +Example: \fBlogon home = "\\\\remote_smb_server\\%U"\fR +.TP +\fBlogon path (G)\fR +This parameter specifies the home directory +where roaming profiles (NTuser.dat etc files for Windows NT) are +stored. Contrary to previous versions of these manual pages, it has +nothing to do with Win 9X roaming profiles. To find out how to +handle roaming profiles for Win 9X system, see the \fIlogon home\fR parameter. + +This option takes the standard substitutions, allowing you +to have separate logon scripts for each user or machine. It also +specifies the directory from which the "Application Data", +(\fIdesktop\fR, \fIstart menu\fR, +\fInetwork neighborhood\fR, \fIprograms\fR +and other folders, and their contents, are loaded and displayed on +your Windows NT client. + +The share and the path must be readable by the user for +the preferences and directories to be loaded onto the Windows NT +client. The share must be writeable when the user logs in for the first +time, in order that the Windows NT client can create the NTuser.dat +and other directories. + +Thereafter, the directories and any of the contents can, +if required, be made read-only. It is not advisable that the +NTuser.dat file be made read-only - rename it to NTuser.man to +achieve the desired effect (a \fBMAN\fRdatory +profile). + +Windows clients can sometimes maintain a connection to +the [homes] share, even though there is no user logged in. +Therefore, it is vital that the logon path does not include a +reference to the homes share (i.e. setting this parameter to +\\%N\\%U\\profile_path will cause problems). + +This option takes the standard substitutions, allowing +you to have separate logon scripts for each user or machine. + +Note that this option is only useful if Samba is set up +as a logon server. + +Default: \fBlogon path = \\\\%N\\%U\\profile\fR + +Example: \fBlogon path = \\\\PROFILESERVER\\PROFILE\\%U\fR +.TP +\fBlogon script (G)\fR +This parameter specifies the batch file (.bat) or +NT command file (.cmd) to be downloaded and run on a machine when +a user successfully logs in. The file must contain the DOS +style CR/LF line endings. Using a DOS-style editor to create the +file is recommended. + +The script must be a relative path to the [netlogon] +service. If the [netlogon] service specifies a \fIpath\fR of \fI/usr/local/samba/netlogon +\fR, and \fBlogon script = STARTUP.BAT\fR, then +the file that will be downloaded is: + +\fI/usr/local/samba/netlogon/STARTUP.BAT\fR + +The contents of the batch file are entirely your choice. A +suggested command would be to add \fBNET TIME \\\\SERVER /SET +/YES\fR, to force every machine to synchronize clocks with +the same time server. Another use would be to add \fBNET USE +U: \\\\SERVER\\UTILS\fR for commonly used utilities, or \fB NET USE Q: \\\\SERVER\\ISO9001_QA\fR for example. + +Note that it is particularly important not to allow write +access to the [netlogon] share, or to grant users write permission +on the batch files in a secure environment, as this would allow +the batch files to be arbitrarily modified and security to be +breached. + +This option takes the standard substitutions, allowing you +to have separate logon scripts for each user or machine. + +This option is only useful if Samba is set up as a logon +server. -.B Default: - mangling char = ~ +Default: \fBno logon script defined\fR + +Example: \fBlogon script = scripts\\%U.bat\fR +.TP +\fBlppause command (S)\fR +This parameter specifies the command to be +executed on the server host in order to stop printing or spooling +a specific print job. + +This command should be a program or script which takes +a printer name and job number to pause the print job. One way +of implementing this is by using job priorities, where jobs +having a too low priority won't be sent to the printer. + +If a \fI%p\fR is given then the printer name +is put in its place. A \fI%j\fR is replaced with +the job number (an integer). On HPUX (see \fIprinting=hpux +\fR), if the \fI-p%p\fR option is added +to the lpq command, the job will show up with the correct status, i.e. +if the job priority is lower than the set fence priority it will +have the PAUSED status, whereas if the priority is equal or higher it +will have the SPOOLED or PRINTING status. + +Note that it is good practice to include the absolute path +in the lppause command as the PATH may not be available to the server. + +See also the \fIprinting +\fRparameter. + +Default: Currently no default value is given to +this string, unless the value of the \fIprinting\fR +parameter is SYSV, in which case the default is : + +\fBlp -i %p-%j -H hold\fR + +or if the value of the \fIprinting\fR parameter +is SOFTQ, then the default is: + +\fBqstat -s -j%j -h\fR + +Example for HPUX: \fBlppause command = /usr/bin/lpalt +%p-%j -p0\fR +.TP +\fBlpq cache time (G)\fR +This controls how long lpq info will be cached +for to prevent the \fBlpq\fR command being called too +often. A separate cache is kept for each variation of the \fB lpq\fR command used by the system, so if you use different +\fBlpq\fR commands for different users then they won't +share cache information. + +The cache files are stored in \fI/tmp/lpq.xxxx\fR +where xxxx is a hash of the \fBlpq\fR command in use. + +The default is 10 seconds, meaning that the cached results +of a previous identical \fBlpq\fR command will be used +if the cached data is less than 10 seconds old. A large value may +be advisable if your \fBlpq\fR command is very slow. + +A value of 0 will disable caching completely. + +See also the \fIprinting +\fRparameter. + +Default: \fBlpq cache time = 10\fR + +Example: \fBlpq cache time = 30\fR +.TP +\fBlpq command (S)\fR +This parameter specifies the command to be +executed on the server host in order to obtain \fBlpq +\fR-style printer status information. + +This command should be a program or script which +takes a printer name as its only parameter and outputs printer +status information. + +Currently eight styles of printer status information +are supported; BSD, AIX, LPRNG, PLP, SYSV, HPUX, QNX and SOFTQ. +This covers most UNIX systems. You control which type is expected +using the \fIprinting =\fR option. + +Some clients (notably Windows for Workgroups) may not +correctly send the connection number for the printer they are +requesting status information about. To get around this, the +server reports on the first printer service connected to by the +client. This only happens if the connection number sent is invalid. + +If a \fI%p\fR is given then the printer name +is put in its place. Otherwise it is placed at the end of the +command. -.B Example: - mangling char = ^ +Note that it is good practice to include the absolute path +in the \fIlpq command\fR as the \fB$PATH +\fRmay not be available to the server. + +See also the \fIprinting +\fRparameter. + +Default: \fBdepends on the setting of \fI printing\fB\fR + +Example: \fBlpq command = /usr/bin/lpq -P%p\fR +.TP +\fBlpresume command (S)\fR +This parameter specifies the command to be +executed on the server host in order to restart or continue +printing or spooling a specific print job. + +This command should be a program or script which takes +a printer name and job number to resume the print job. See +also the \fIlppause command +\fRparameter. + +If a \fI%p\fR is given then the printer name +is put in its place. A \fI%j\fR is replaced with +the job number (an integer). + +Note that it is good practice to include the absolute path +in the \fIlpresume command\fR as the PATH may not +be available to the server. + +See also the \fIprinting +\fRparameter. + +Default: Currently no default value is given +to this string, unless the value of the \fIprinting\fR +parameter is SYSV, in which case the default is : + +\fBlp -i %p-%j -H resume\fR + +or if the value of the \fIprinting\fR parameter +is SOFTQ, then the default is: + +\fBqstat -s -j%j -r\fR + +Example for HPUX: \fBlpresume command = /usr/bin/lpalt +%p-%j -p2\fR +.TP +\fBlprm command (S)\fR +This parameter specifies the command to be +executed on the server host in order to delete a print job. + +This command should be a program or script which takes +a printer name and job number, and deletes the print job. + +If a \fI%p\fR is given then the printer name +is put in its place. A \fI%j\fR is replaced with +the job number (an integer). + +Note that it is good practice to include the absolute +path in the \fIlprm command\fR as the PATH may not be +available to the server. + +See also the \fIprinting +\fRparameter. + +Default: \fBdepends on the setting of \fIprinting +\fB\fR +Example 1: \fBlprm command = /usr/bin/lprm -P%p %j +\fR +Example 2: \fBlprm command = /usr/bin/cancel %p-%j +\fR.TP +\fBmachine password timeout (G)\fR +If a Samba server is a member of a Windows +NT Domain (see the security = domain) +parameter) then periodically a running smbd(8)process will try and change the MACHINE ACCOUNT +PASSWORD stored in the TDB called \fIprivate/secrets.tdb +\fR\&. This parameter specifies how often this password +will be changed, in seconds. The default is one week (expressed in +seconds), the same as a Windows NT Domain member server. + +See also \fBsmbpasswd(8) +\fR, and the security = domain) parameter. + +Default: \fBmachine password timeout = 604800\fR +.TP +\fBmagic output (S)\fR +This parameter specifies the name of a file +which will contain output created by a magic script (see the +\fImagic script\fR +parameter below). + +Warning: If two clients use the same \fImagic script +\fRin the same directory the output file content +is undefined. + +Default: \fBmagic output = <magic script name>.out +\fR +Example: \fBmagic output = myfile.txt\fR +.TP +\fBmagic script (S)\fR +This parameter specifies the name of a file which, +if opened, will be executed by the server when the file is closed. +This allows a UNIX script to be sent to the Samba host and +executed on behalf of the connected user. + +Scripts executed in this way will be deleted upon +completion assuming that the user has the appropriate level +of privilege and the file permissions allow the deletion. + +If the script generates output, output will be sent to +the file specified by the \fI magic output\fR parameter (see above). + +Note that some shells are unable to interpret scripts +containing CR/LF instead of CR as +the end-of-line marker. Magic scripts must be executable +\fBas is\fR on the host, which for some hosts and +some shells will require filtering at the DOS end. + +Magic scripts are \fBEXPERIMENTAL\fR and +should \fBNOT\fR be relied upon. + +Default: \fBNone. Magic scripts disabled.\fR + +Example: \fBmagic script = user.csh\fR +.TP +\fBmangle case (S)\fR +See the section on NAME MANGLING + +Default: \fBmangle case = no\fR +.TP +\fBmangled map (S)\fR +This is for those who want to directly map UNIX +file names which cannot be represented on Windows/DOS. The mangling +of names is not always what is needed. In particular you may have +documents with file extensions that differ between DOS and UNIX. +For example, under UNIX it is common to use \fI.html\fR +for HTML files, whereas under Windows/DOS \fI.htm\fR +is more commonly used. + +So to map \fIhtml\fR to \fIhtm\fR +you would use: + +\fBmangled map = (*.html *.htm)\fR + +One very useful case is to remove the annoying \fI;1 +\fRoff the ends of filenames on some CDROMs (only visible +under some UNIXes). To do this use a map of (*;1 *;). + +Default: \fBno mangled map\fR + +Example: \fBmangled map = (*;1 *;)\fR +.TP +\fBmangled names (S)\fR +This controls whether non-DOS names under UNIX +should be mapped to DOS-compatible names ("mangled") and made visible, +or whether non-DOS names should simply be ignored. + +See the section on NAME MANGLING for details on how to control the mangling process. -.SS max log size (G) +If mangling is used then the mangling algorithm is as follows: +.RS +.TP 0.2i +\(bu +The first (up to) five alphanumeric characters +before the rightmost dot of the filename are preserved, forced +to upper case, and appear as the first (up to) five characters +of the mangled name. +.TP 0.2i +\(bu +A tilde "~" is appended to the first part of the mangled +name, followed by a two-character unique sequence, based on the +original root name (i.e., the original filename minus its final +extension). The final extension is included in the hash calculation +only if it contains any upper case characters or is longer than three +characters. -This option (an integer in kilobytes) specifies the max size the log -file should grow to. Samba periodically checks the size and if it is -exceeded it will rename the file, adding a .old extension. +Note that the character to use may be specified using +the \fImangling char\fR +option, if you don't like '~'. +.TP 0.2i +\(bu +The first three alphanumeric characters of the final +extension are preserved, forced to upper case and appear as the +extension of the mangled name. The final extension is defined as that +part of the original filename after the rightmost dot. If there are no +dots in the filename, the mangled name will have no extension (except +in the case of "hidden files" - see below). +.TP 0.2i +\(bu +Files whose UNIX name begins with a dot will be +presented as DOS hidden files. The mangled name will be created as +for other filenames, but with the leading dot removed and "___" as +its extension regardless of actual original extension (that's three +underscores). +.RE +.PP +The two-digit hash value consists of upper case +alphanumeric characters. +.PP +.PP +This algorithm can cause name collisions only if files +in a directory share the same first five alphanumeric characters. +The probability of such a clash is 1/1300. +.PP +.PP +The name mangling (if enabled) allows a file to be +copied between UNIX directories from Windows/DOS while retaining +the long UNIX filename. UNIX files can be renamed to a new extension +from Windows/DOS and will retain the same basename. Mangled names +do not change between sessions. +.PP +.PP +Default: \fBmangled names = yes\fR +.PP +.TP +\fBmangled stack (G)\fR +This parameter controls the number of mangled names +that should be cached in the Samba server smbd(8). + +This stack is a list of recently mangled base names +(extensions are only maintained if they are longer than 3 characters +or contains upper case characters). + +The larger this value, the more likely it is that mangled +names can be successfully converted to correct long UNIX names. +However, large stack sizes will slow most directory accesses. Smaller +stacks save memory in the server (each stack element costs 256 bytes). + +It is not possible to absolutely guarantee correct long +filenames, so be prepared for some surprises! + +Default: \fBmangled stack = 50\fR + +Example: \fBmangled stack = 100\fR +.TP +\fBmangling char (S)\fR +This controls what character is used as +the \fBmagic\fR character in name mangling. The default is a '~' +but this may interfere with some software. Use this option to set +it to whatever you prefer. + +Default: \fBmangling char = ~\fR + +Example: \fBmangling char = ^\fR +.TP +\fBmap archive (S)\fR +This controls whether the DOS archive attribute +should be mapped to the UNIX owner execute bit. The DOS archive bit +is set when a file has been modified since its last backup. One +motivation for this option it to keep Samba/your PC from making +any file it touches from becoming executable under UNIX. This can +be quite annoying for shared source code, documents, etc... + +Note that this requires the \fIcreate mask\fR +parameter to be set such that owner execute bit is not masked out +(i.e. it must include 100). See the parameter \fIcreate mask\fR for details. + +Default: \fBmap archive = yes\fR +.TP +\fBmap hidden (S)\fR +This controls whether DOS style hidden files +should be mapped to the UNIX world execute bit. + +Note that this requires the \fIcreate mask\fR +to be set such that the world execute bit is not masked out (i.e. +it must include 001). See the parameter \fIcreate mask\fR for details. + +Default: \fBmap hidden = no\fR +.TP +\fBmap system (S)\fR +This controls whether DOS style system files +should be mapped to the UNIX group execute bit. + +Note that this requires the \fIcreate mask\fR +to be set such that the group execute bit is not masked out (i.e. +it must include 010). See the parameter \fIcreate mask\fR for details. + +Default: \fBmap system = no\fR +.TP +\fBmap to guest (G)\fR +This parameter is only useful in security modes other than \fIsecurity = share\fR +- i.e. user, server, +and domain. + +This parameter can take three different values, which tell +smbd(8)what to do with user +login requests that don't match a valid UNIX user in some way. + +The three settings are : +.RS +.TP 0.2i +\(bu +Never - Means user login +requests with an invalid password are rejected. This is the +default. +.TP 0.2i +\(bu +Bad User - Means user +logins with an invalid password are rejected, unless the username +does not exist, in which case it is treated as a guest login and +mapped into the \fI guest account\fR. +.TP 0.2i +\(bu +Bad Password - Means user logins +with an invalid password are treated as a guest login and mapped +into the guest account. Note that +this can cause problems as it means that any user incorrectly typing +their password will be silently logged on as "guest" - and +will not know the reason they cannot access files they think +they should - there will have been no message given to them +that they got their password wrong. Helpdesk services will +\fBhate\fR you if you set the \fImap to +guest\fR parameter this way :-). +.RE +.PP +Note that this parameter is needed to set up "Guest" +share services when using \fIsecurity\fR modes other than +share. This is because in these modes the name of the resource being +requested is \fBnot\fR sent to the server until after +the server has successfully authenticated the client so the server +cannot make authentication decisions at the correct time (connection +to the share) for "Guest" shares. +.PP +.PP +For people familiar with the older Samba releases, this +parameter maps to the old compile-time setting of the GUEST_SESSSETUP value in local.h. +.PP +.PP +Default: \fBmap to guest = Never\fR +.PP +.PP +Example: \fBmap to guest = Bad User\fR +.PP +.TP +\fBmax connections (S)\fR +This option allows the number of simultaneous +connections to a service to be limited. If \fImax connections +\fRis greater than 0 then connections will be refused if +this number of connections to the service are already open. A value +of zero mean an unlimited number of connections may be made. + +Record lock files are used to implement this feature. The +lock files will be stored in the directory specified by the \fIlock directory\fR +option. + +Default: \fBmax connections = 0\fR + +Example: \fBmax connections = 10\fR +.TP +\fBmax disk size (G)\fR +This option allows you to put an upper limit +on the apparent size of disks. If you set this option to 100 +then all shares will appear to be not larger than 100 MB in +size. + +Note that this option does not limit the amount of +data you can put on the disk. In the above case you could still +store much more than 100 MB on the disk, but if a client ever asks +for the amount of free disk space or the total disk size then the +result will be bounded by the amount specified in \fImax +disk size\fR. + +This option is primarily useful to work around bugs +in some pieces of software that can't handle very large disks, +particularly disks over 1GB in size. + +A \fImax disk size\fR of 0 means no limit. + +Default: \fBmax disk size = 0\fR + +Example: \fBmax disk size = 1000\fR +.TP +\fBmax log size (G)\fR +This option (an integer in kilobytes) specifies +the max size the log file should grow to. Samba periodically checks +the size and if it is exceeded it will rename the file, adding +a \fI.old\fR extension. A size of 0 means no limit. -.B Default: - max log size = 5000 - -.B Example: - max log size = 1000 - -.SS max xmit (G) - -This option controls the maximum packet size that will be negotiated -by Samba. The default is 65535, which is the maximum. In some cases -you may find you get better performance with a smaller value. A value -below 2048 is likely to cause problems. - -.B Default: - max xmit = 65535 - -.B Example: - max xmit = 8192 - -.SS mangled stack (G) -This parameter controls the number of mangled names that should be cached in -the Samba server. - -This stack is a list of recently mangled base names (extensions are only -maintained if they are longer than 3 characters or contains upper case -characters). - -The larger this value, the more likely it is that mangled names can be -successfully converted to correct long Unix names. However, large stack -sizes will slow most directory access. Smaller stacks save memory in the -server (each stack element costs 256 bytes). - -It is not possible to absolutely guarantee correct long file names, so -be prepared for some surprises! - -.B Default: - mangled stack = 50 - -.B Example: - mangled stack = 100 - -.SS map archive (S) -This controls whether the DOS archive attribute should be mapped to Unix -execute bits. The DOS archive bit is set when a file has been modified -since its last backup. One motivation for this option it to keep Samba/your -PC from making any file it touches from becoming executable under UNIX. -This can be quite annoying for shared source code, documents, etc... - -.B Default: - map archive = yes - -.B Example: - map archive = no - -.SS map hidden (S) -This controls whether DOS style hidden files should be mapped to Unix -execute bits. - -.B Default: - map hidden = no - -.B Example: - map hidden = yes -.SS map system (S) -This controls whether DOS style system files should be mapped to Unix -execute bits. - -.B Default: - map system = no - -.B Example: - map system = yes -.SS max connections (S) -This option allows the number of simultaneous connections to a -service to be limited. If "max connections" is greater than 0 then -connections will be refused if this number of connections to the -service are already open. A value of zero mean an unlimited number of -connections may be made. - -Record lock files are used to implement this feature. The lock files -will be stored in the directory specified by the "lock directory" option. - -.B Default: - max connections = 0 - -.B Example: - max connections = 10 -.SS only user (S) -This is a boolean option that controls whether connections with -usernames not in the user= list will be allowed. By default this -option is disabled so a client can supply a username to be used by -the server. - -Note that this also means Samba won't try to deduce usernames from the -service name. This can be annoying for the [homes] section. To get -around this you could use "user = %S" which means your "user" list -will be just the service name, which for home directories is the name -of the user. - -.B Default: - only user = False - -.B Example: - only user = True - -.SS message command (G) - -This specifies what command to run when the server receives a WinPopup -style message. - -This would normally be a command that would deliver the message -somehow. How this is to be done is up to your imagination. - -What I use is: - - message command = csh -c 'xedit %s;rm %s' & - -This delivers the message using xedit, then removes it -afterwards. NOTE THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN -IMMEDIATELY. That's why I have the & on the end. If it doesn't return -immediately then your PCs may freeze when sending messages (they -should recover after 30secs, hopefully). - -All messages are delivered as the global guest user. The command takes -the standard substitutions, although %u won't work (%U may be better +Default: \fBmax log size = 5000\fR + +Example: \fBmax log size = 1000\fR +.TP +\fBmax mux (G)\fR +This option controls the maximum number of +outstanding simultaneous SMB operations that Samba tells the client +it will allow. You should never need to set this parameter. + +Default: \fBmax mux = 50\fR +.TP +\fBmax open files (G)\fR +This parameter limits the maximum number of +open files that one smbd(8)file +serving process may have open for a client at any one time. The +default for this parameter is set very high (10,000) as Samba uses +only one bit per unopened file. + +The limit of the number of open files is usually set +by the UNIX per-process file descriptor limit rather than +this parameter so you should never need to touch this parameter. + +Default: \fBmax open files = 10000\fR +.TP +\fBmax print jobs (S)\fR +This parameter limits the maximum number of +jobs allowable in a Samba printer queue at any given moment. +If this number is exceeded, \fB smbd(8)\fRwill remote "Out of Space" to the client. +See all \fItotal +print jobs\fR. + +Default: \fBmax print jobs = 1000\fR + +Example: \fBmax print jobs = 5000\fR +.TP +\fBmax protocol (G)\fR +The value of the parameter (a string) is the highest +protocol level that will be supported by the server. + +Possible values are : +.RS +.TP 0.2i +\(bu +CORE: Earliest version. No +concept of user names. +.TP 0.2i +\(bu +COREPLUS: Slight improvements on +CORE for efficiency. +.TP 0.2i +\(bu +LANMAN1: First \fB modern\fR version of the protocol. Long filename +support. +.TP 0.2i +\(bu +LANMAN2: Updates to Lanman1 protocol. +.TP 0.2i +\(bu +NT1: Current up to date version of +the protocol. Used by Windows NT. Known as CIFS. +.RE +.PP +Normally this option should not be set as the automatic +negotiation phase in the SMB protocol takes care of choosing +the appropriate protocol. +.PP +.PP +See also \fImin +protocol\fR +.PP +.PP +Default: \fBmax protocol = NT1\fR +.PP +.PP +Example: \fBmax protocol = LANMAN1\fR +.PP +.TP +\fBmax smbd processes (G)\fR +This parameter limits the maximum number of +\fBsmbd(8)\fR +processes concurrently running on a system and is intended +as a stopgap to prevent degrading service to clients in the event +that the server has insufficient resources to handle more than this +number of connections. Remember that under normal operating +conditions, each user will have an smbdassociated with him or her +to handle connections to all shares from a given host. + +Default: \fBmax smbd processes = 0\fR ## no limit + +Example: \fBmax smbd processes = 1000\fR +.TP +\fBmax ttl (G)\fR +This option tells nmbd(8) +what the default 'time to live' of NetBIOS names should be (in seconds) +when \fBnmbd\fR is requesting a name using either a +broadcast packet or from a WINS server. You should never need to +change this parameter. The default is 3 days. + +Default: \fBmax ttl = 259200\fR +.TP +\fBmax wins ttl (G)\fR +This option tells nmbd(8) +when acting as a WINS server ( \fIwins support = yes\fR) what the maximum +\&'time to live' of NetBIOS names that \fBnmbd\fR +will grant will be (in seconds). You should never need to change this +parameter. The default is 6 days (518400 seconds). + +See also the \fImin +wins ttl\fR parameter. + +Default: \fBmax wins ttl = 518400\fR +.TP +\fBmax xmit (G)\fR +This option controls the maximum packet size +that will be negotiated by Samba. The default is 65535, which +is the maximum. In some cases you may find you get better performance +with a smaller value. A value below 2048 is likely to cause problems. + +Default: \fBmax xmit = 65535\fR + +Example: \fBmax xmit = 8192\fR +.TP +\fBmessage command (G)\fR +This specifies what command to run when the +server receives a WinPopup style message. + +This would normally be a command that would +deliver the message somehow. How this is to be done is +up to your imagination. + +An example is: + +\fBmessage command = csh -c 'xedit %s;rm %s' &\fR + +This delivers the message using \fBxedit\fR, then +removes it afterwards. \fBNOTE THAT IT IS VERY IMPORTANT +THAT THIS COMMAND RETURN IMMEDIATELY\fR. That's why I +have the '&' on the end. If it doesn't return immediately then +your PCs may freeze when sending messages (they should recover +after 30 seconds, hopefully). + +All messages are delivered as the global guest user. +The command takes the standard substitutions, although \fI %u\fR won't work (\fI%U\fR may be better in this case). -Apart from the standard substitutions, some additional ones apply. In -particular: - -%s = the filename containing the message - -%t = the destination that the message was sent to (probably the server -name) - -%f = who the message is from - -You could make this command send mail, or whatever else takes your -fancy. Please let me know of any really interesting ideas you have. - +Apart from the standard substitutions, some additional +ones apply. In particular: +.RS +.TP 0.2i +\(bu +\fI%s\fR = the filename containing +the message. +.TP 0.2i +\(bu +\fI%t\fR = the destination that +the message was sent to (probably the server name). +.TP 0.2i +\(bu +\fI%f\fR = who the message +is from. +.RE +.PP +You could make this command send mail, or whatever else +takes your fancy. Please let us know of any really interesting +ideas you have. +.PP +.PP Here's a way of sending the messages as mail to root: - -message command = /bin/mail -s 'message from %f on %m' root < %s; rm %s - -If you don't have a message command then the message won't be -delivered and Samba will tell the sender there was an -error. Unfortunately WfWg totally ignores the error code and carries -on regardless, saying that the message was delivered. - -If you want to silently delete it then try "message command = rm %s". - -For the really adventurous, try something like this: - -message command = csh -c 'csh < %s |& /usr/local/samba/smbclient \\ - -M %m; rm %s' & - -this would execute the command as a script on the server, then give -them the result in a WinPopup message. Note that this could cause a -loop if you send a message from the server using smbclient! You better -wrap the above in a script that checks for this :-) - -.B Default: - no message command - -.B Example: - message command = csh -c 'xedit %s;rm %s' & - -.SS min print space (S) - -This sets the minimum amount of free disk space that must be available -before a user will be able to spool a print job. It is specified in -kilobytes. The default is 0, which means no limit. - -.B Default: - min print space = 0 - -.B Example: - min print space = 2000 - -.SS null passwords (G) -Allow or disallow access to accounts that have null passwords. - -.B Default: - null passwords = no - -.B Example: - null passwords = yes - -.SS os level (G) -This integer value controls what level Samba advertises itself as for -browse elections. See BROWSING.txt for details. - -.SS packet size (G) -The maximum transmit packet size during a raw read. This option is no -longer implemented as of version 1.7.00, and is kept only so old -configuration files do not become invalid. - -.SS passwd chat (G) -This string coontrols the "chat" conversation that takes places -between smbd and the local password changing program to change the -users password. The string describes a sequence of response-receive -pairs that smbd uses to determine what to send to the passwd program -and what to expect back. If the expected output is not received then -the password is not changed. - -This chat sequence is often quite site specific, deppending on what -local methods are used for password control (such as NIS+ etc). - -The string can contain the macros %o and %n which are substituted for -the old and new passwords respectively. It can aso contain the -standard macros \\n \\r \\t and \\s to give line-feed, carriage-return, -tab and space. - -The string can also contain a * which matches any sequence of -characters. - -Double quotes can be used to collect strings with spaces in them into -a single string. - -If the send string in any part of the chat sequence is a fullstop "." -then no string is sent. Similarly, is the expect string is a fullstop -then no string is expected. - -.B Example: - passwd chat = "*Enter OLD password*" %o\\n "*Enter NEW password*" %n\\n \\ - "*Reenter NEW password*" %n\\n "*Password changed*" - -.B Default: - passwd chat = *old*password* %o\\n *new*password* %n\\n *new*password* %n\\n *changed* - -.SS passwd program (G) -The name of a program that can be used to set user passwords. - -This is only necessary if you have enabled remote password changing at -compile time. Any occurances of %u will be replaced with the user -name. - -Also note that many passwd programs insist in "reasonable" passwords, -such as a minimum length, or the inclusion of mixed case chars and -digits. This can pose a problem as some clients (such as Windows for -Workgroups) uppercase the password before sending it. - -.B Default: - passwd program = /bin/passwd - -.B Example: - passwd program = /sbin/passwd %u - -.SS password level (G) -Some client/server conbinations have difficulty with mixed-case passwords. -One offending client is Windows for Workgroups, which for some reason forces -passwords to upper case when using the LANMAN1 protocol, but leaves them alone -when using COREPLUS! - -This parameter defines the maximum number of characters that may be upper case -in passwords. - -For example, say the password given was "FRED". If -.B password level -is set to 1 (one), the following combinations would be tried if "FRED" failed: -"Fred", "fred", "fRed", "frEd", "freD". If -.B password level was set to 2 (two), the following combinations would also be -tried: "FRed", "FrEd", "FreD", "fREd", "fReD", "frED". And so on. - -The higher value this parameter is set to the more likely it is that a mixed -case password will be matched against a single case password. However, you -should be aware that use of this parameter reduces security and increases the -time taken to process a new connection. - -A value of zero will cause only two attempts to be made - the password as is -and the password in all-lower case. - -If you find the connections are taking too long with this option then -you probably have a slow crypt() routine. Samba now comes with a fast -"ufc crypt" that you can select in the Makefile. You should also make -sure the PASSWORD_LENGTH option is correct for your system in local.h -and includes.h. On most systems only the first 8 chars of a password -are significant so PASSWORD_LENGTH should be 8, but on some longer -passwords are significant. The inlcudes.h file tries to select the -right length for your system. - -.B Default: - password level = 0 - -.B Example: - password level = 4 - -.SS password server (G) - -By specifying the name of another SMB server (such as a WinNT box) -with this option, and using "security = server" you can get Samba to -do all it's username/password validation via a remote server. - -This options sets the name of the password server to use. It must be a -netbios name, so if the machines netbios name is different from it's -internet name then you may have to add it's netbios name to -/etc/hosts. - -The password server much be a machine capable of using the "LM1.2X002" -or the "LM NT 0.12" protocol, and it must be in user level security -mode. - -NOTE: Using a password server means your unix box (running Samba) is -only as secure as your password server. DO NOT CHOOSE A PASSWORD -SERVER THAT YOU DON'T COMPLETELY TRUST. - -Never point a Samba server at itself for password serving. This will -cause a loop and could lock up your Samba server! - -The name of the password server takes the standard substitutions, but -probably the only useful one is %m, which means the Samba server will -use the incoming client as the password server. If you use this then -you better trust your clients, and you better restrict them with hosts -allow! - -If you list several hosts in the "password server" option then smbd -will try each in turn till it finds one that responds. This is useful -in case your primary server goes down. - -.SS path (S) -A synonym for this parameter is 'directory'. - -This parameter specifies a directory to which the user of the service is to -be given access. In the case of printable services, this is where print data -will spool prior to being submitted to the host for printing. - -For a printable service offering guest access, the service should be readonly -and the path should be world-writable and have the sticky bit set. This is not -mandatory of course, but you probably won't get the results you expect if you -do otherwise. - -Any occurances of %u in the path will be replaced with the username -that the client is connecting as. Any occurances of %m will be -replaced by the name of the machine they are connecting from. These -replacements are very useful for setting up pseudo home directories -for users. - -Note that this path will be based on 'root dir' if one was specified. -.B Default: - none - -.B Example: - path = /home/fred+ - -.SS postexec (S) - -This option specifies a command to be run whenever the service is -disconnected. It takes the usual substitutions. The command may be run -as the root on some systems. - -An interesting example may be do unmount server resources: - -postexec = /etc/umount /cdrom - -See also preexec - -.B Default: - none (no command executed) - -.B Example: - postexec = echo \"%u disconnected from %S from %m (%I)\" >> /tmp/log - -.SS postscript (S) -This parameter forces a printer to interpret the print files as -postscript. This is done by adding a %! to the start of print output. - -This is most useful when you have lots of PCs that persist in putting -a control-D at the start of print jobs, which then confuses your -printer. - -.B Default: - postscript = False - -.B Example: - postscript = True - -.SS preexec (S) - -This option specifies a command to be run whenever the service is -connected to. It takes the usual substitutions. - -An interesting example is to send the users a welcome message every -time they log in. Maybe a message of the day? Here is an example: - -preexec = csh -c 'echo \"Welcome to %S!\" | \ - /usr/local/samba/smbclient -M %m -I %I' & +.PP +.PP +\fBmessage command = /bin/mail -s 'message from %f on +%m' root < %s; rm %s\fR +.PP +.PP +If you don't have a message command then the message +won't be delivered and Samba will tell the sender there was +an error. Unfortunately WfWg totally ignores the error code +and carries on regardless, saying that the message was delivered. +.PP +.PP +If you want to silently delete it then try: +.PP +.PP +\fBmessage command = rm %s\fR +.PP +.PP +Default: \fBno message command\fR +.PP +.PP +Example: \fBmessage command = csh -c 'xedit %s; +rm %s' &\fR +.PP +.TP +\fBmin passwd length (G)\fR +Synonym for \fImin password length\fR. +.TP +\fBmin password length (G)\fR +This option sets the minimum length in characters +of a plaintext password that \fBsmbd\fR will accept when performing +UNIX password changing. + +See also \fIunix +password sync\fR, \fIpasswd program\fR and \fIpasswd chat debug\fR +\&. + +Default: \fBmin password length = 5\fR +.TP +\fBmin print space (S)\fR +This sets the minimum amount of free disk +space that must be available before a user will be able to spool +a print job. It is specified in kilobytes. The default is 0, which +means a user can always spool a print job. + +See also the \fIprinting +\fRparameter. + +Default: \fBmin print space = 0\fR + +Example: \fBmin print space = 2000\fR +.TP +\fBmin protocol (G)\fR +The value of the parameter (a string) is the +lowest SMB protocol dialect than Samba will support. Please refer +to the \fImax protocol\fR +parameter for a list of valid protocol names and a brief description +of each. You may also wish to refer to the C source code in +\fIsource/smbd/negprot.c\fR for a listing of known protocol +dialects supported by clients. + +If you are viewing this parameter as a security measure, you should +also refer to the \fIlanman +auth\fR parameter. Otherwise, you should never need +to change this parameter. + +Default : \fBmin protocol = CORE\fR + +Example : \fBmin protocol = NT1\fR # disable DOS +clients +.TP +\fBmin wins ttl (G)\fR +This option tells nmbd(8) +when acting as a WINS server (\fI wins support = yes\fR) what the minimum 'time to live' +of NetBIOS names that \fBnmbd\fR will grant will be (in +seconds). You should never need to change this parameter. The default +is 6 hours (21600 seconds). + +Default: \fBmin wins ttl = 21600\fR +.TP +\fBmsdfs root (S)\fR +This boolean parameter is only available if +Samba is configured and compiled with the \fB --with-msdfs\fR option. If set to yes, +Samba treats the share as a Dfs root and allows clients to browse +the distributed file system tree rooted at the share directory. +Dfs links are specified in the share directory by symbolic +links of the form \fImsdfs:serverA\\shareA,serverB\\shareB +\fRand so on. For more information on setting up a Dfs tree +on Samba, refer to msdfs_setup.html +. + +See also \fIhost msdfs +\fR +Default: \fBmsdfs root = no\fR +.TP +\fBname resolve order (G)\fR +This option is used by the programs in the Samba +suite to determine what naming services to use and in what order +to resolve host names to IP addresses. The option takes a space +separated string of name resolution options. + +The options are :"lmhosts", "host", "wins" and "bcast". They +cause names to be resolved as follows : +.RS +.TP 0.2i +\(bu +lmhosts : Lookup an IP +address in the Samba lmhosts file. If the line in lmhosts has +no name type attached to the NetBIOS name (see the lmhosts(5)for details) then +any name type matches for lookup. +.TP 0.2i +\(bu +host : Do a standard host +name to IP address resolution, using the system \fI/etc/hosts +\fR, NIS, or DNS lookups. This method of name resolution +is operating system depended for instance on IRIX or Solaris this +may be controlled by the \fI/etc/nsswitch.conf\fR +file. Note that this method is only used if the NetBIOS name +type being queried is the 0x20 (server) name type, otherwise +it is ignored. +.TP 0.2i +\(bu +wins : Query a name with +the IP address listed in the \fI wins server\fR parameter. If no WINS server has +been specified this method will be ignored. +.TP 0.2i +\(bu +bcast : Do a broadcast on +each of the known local interfaces listed in the \fIinterfaces\fR +parameter. This is the least reliable of the name resolution +methods as it depends on the target host being on a locally +connected subnet. +.RE +.PP +Default: \fBname resolve order = lmhosts host wins bcast +\fR.PP +.PP +Example: \fBname resolve order = lmhosts bcast host +\fR.PP +.PP +This will cause the local lmhosts file to be examined +first, followed by a broadcast attempt, followed by a normal +system hostname lookup. +.PP +.TP +\fBnetbios aliases (G)\fR +This is a list of NetBIOS names that nmbd(8)will advertise as additional +names by which the Samba server is known. This allows one machine +to appear in browse lists under multiple names. If a machine is +acting as a browse server or logon server none +of these names will be advertised as either browse server or logon +servers, only the primary name of the machine will be advertised +with these capabilities. + +See also \fInetbios +name\fR. + +Default: \fBempty string (no additional names)\fR + +Example: \fBnetbios aliases = TEST TEST1 TEST2\fR +.TP +\fBnetbios name (G)\fR +This sets the NetBIOS name by which a Samba +server is known. By default it is the same as the first component +of the host's DNS name. If a machine is a browse server or +logon server this name (or the first component +of the hosts DNS name) will be the name that these services are +advertised under. + +See also \fInetbios +aliases\fR. + +Default: \fBmachine DNS name\fR + +Example: \fBnetbios name = MYNAME\fR +.TP +\fBnetbios scope (G)\fR +This sets the NetBIOS scope that Samba will +operate under. This should not be set unless every machine +on your LAN also sets this value. +.TP +\fBnis homedir (G)\fR +Get the home share server from a NIS map. For +UNIX systems that use an automounter, the user's home directory +will often be mounted on a workstation on demand from a remote +server. + +When the Samba logon server is not the actual home directory +server, but is mounting the home directories via NFS then two +network hops would be required to access the users home directory +if the logon server told the client to use itself as the SMB server +for home directories (one over SMB and one over NFS). This can +be very slow. + +This option allows Samba to return the home share as +being on a different server to the logon server and as +long as a Samba daemon is running on the home directory server, +it will be mounted on the Samba client directly from the directory +server. When Samba is returning the home share to the client, it +will consult the NIS map specified in \fIhomedir map\fR and return the server +listed there. + +Note that for this option to work there must be a working +NIS system and the Samba server with this option must also +be a logon server. + +Default: \fBnis homedir = no\fR +.TP +\fBnt acl support (S)\fR +This boolean parameter controls whether +smbd(8)will attempt to map +UNIX permissions into Windows NT access control lists. +This parameter was formally a global parameter in releases +prior to 2.2.2. + +Default: \fBnt acl support = yes\fR +.TP +\fBnt pipe support (G)\fR +This boolean parameter controls whether +smbd(8)will allow Windows NT +clients to connect to the NT SMB specific IPC$ +pipes. This is a developer debugging option and can be left +alone. + +Default: \fBnt pipe support = yes\fR +.TP +\fBnt smb support (G)\fR +This boolean parameter controls whether smbd(8)will negotiate NT specific SMB +support with Windows NT clients. Although this is a developer +debugging option and should be left alone, benchmarking has discovered +that Windows NT clients give faster performance with this option +set to no. This is still being investigated. +If this option is set to no then Samba offers +exactly the same SMB calls that versions prior to Samba 2.0 offered. +This information may be of use if any users are having problems +with NT SMB support. + +You should not need to ever disable this parameter. + +Default: \fBnt smb support = yes\fR +.TP +\fBnull passwords (G)\fR +Allow or disallow client access to accounts +that have null passwords. + +See also smbpasswd (5). + +Default: \fBnull passwords = no\fR +.TP +\fBobey pam restrictions (G)\fR +When Samba 2.2 is configured to enable PAM support +(i.e. --with-pam), 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. Note that Samba +always ignores PAM for authentication in the case of \fIencrypt passwords = yes\fR +\&. The reason is that PAM modules cannot support the challenge/response +authentication mechanism needed in the presence of SMB password encryption. + +Default: \fBobey pam restrictions = no\fR +.TP +\fBonly user (S)\fR +This is a boolean option that controls whether +connections with usernames not in the \fIuser\fR +list will be allowed. By default this option is disabled so that a +client can supply a username to be used by the server. Enabling +this parameter will force the server to only user the login +names from the \fIuser\fR list and is only really +useful in shave level +security. + +Note that this also means Samba won't try to deduce +usernames from the service name. This can be annoying for +the [homes] section. To get around this you could use \fBuser = +%S\fR which means your \fIuser\fR list +will be just the service name, which for home directories is the +name of the user. + +See also the \fIuser\fR +parameter. + +Default: \fBonly user = no\fR +.TP +\fBonly guest (S)\fR +A synonym for \fI guest only\fR. +.TP +\fBoplock break wait time (G)\fR +This is a tuning parameter added due to bugs in +both Windows 9x and WinNT. If Samba responds to a client too +quickly when that client issues an SMB that can cause an oplock +break request, then the network client can fail and not respond +to the break request. This tuning parameter (which is set in milliseconds) +is the amount of time Samba will wait before sending an oplock break +request to such (broken) clients. + +\fBDO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ +AND UNDERSTOOD THE SAMBA OPLOCK CODE\fR. + +Default: \fBoplock break wait time = 0\fR +.TP +\fBoplock contention limit (S)\fR +This is a \fBvery\fR advanced +smbd(8)tuning option to +improve the efficiency of the granting of oplocks under multiple +client contention for the same file. + +In brief it specifies a number, which causes smbdnot to +grant an oplock even when requested if the approximate number of +clients contending for an oplock on the same file goes over this +limit. This causes \fBsmbd\fR to behave in a similar +way to Windows NT. + +\fBDO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ +AND UNDERSTOOD THE SAMBA OPLOCK CODE\fR. + +Default: \fBoplock contention limit = 2\fR +.TP +\fBoplocks (S)\fR +This boolean option tells \fBsmbd\fR whether to +issue oplocks (opportunistic locks) to file open requests on this +share. The oplock code can dramatically (approx. 30% or more) improve +the speed of access to files on Samba servers. It allows the clients +to aggressively cache files locally and you may want to disable this +option for unreliable network environments (it is turned on by +default in Windows NT Servers). For more information see the file +\fISpeed.txt\fR in the Samba \fIdocs/\fR +directory. + +Oplocks may be selectively turned off on certain files with a +share. See the \fI veto oplock files\fR parameter. On some systems +oplocks are recognized by the underlying operating system. This +allows data synchronization between all access to oplocked files, +whether it be via Samba or NFS or a local UNIX process. See the +\fIkernel oplocks\fR parameter for details. + +See also the \fIkernel +oplocks\fR and \fI level2 oplocks\fR parameters. + +Default: \fBoplocks = yes\fR +.TP +\fBos level (G)\fR +This integer value controls what level Samba +advertises itself as for browse elections. The value of this +parameter determines whether nmbd(8) +has a chance of becoming a local master browser for the \fI WORKGROUP\fR in the local broadcast area. + +\fBNote :\fRBy default, Samba will win +a local master browsing election over all Microsoft operating +systems except a Windows NT 4.0/2000 Domain Controller. This +means that a misconfigured Samba host can effectively isolate +a subnet for browsing purposes. See \fIBROWSING.txt +\fRin the Samba \fIdocs/\fR directory +for details. + +Default: \fBos level = 20\fR + +Example: \fBos level = 65 \fR +.TP +\fBos2 driver map (G)\fR +The parameter is used to define the absolute +path to a file containing a mapping of Windows NT printer driver +names to OS/2 printer driver names. The format is: + +<nt driver name> = <os2 driver +name>.<device name> + +For example, a valid entry using the HP LaserJet 5 +printer driver would appear as \fBHP LaserJet 5L = LASERJET.HP +LaserJet 5L\fR. + +The need for the file is due to the printer driver namespace +problem described in the Samba +Printing HOWTO. For more details on OS/2 clients, please +refer to the OS2-Client-HOWTO +containing in the Samba documentation. + +Default: \fBos2 driver map = <empty string> +\fR.TP +\fBpam password change (G)\fR +With the addition of better PAM support in Samba 2.2, +this parameter, it is possible to use PAM's password change control +flag for Samba. If enabled, then PAM will be used for password +changes when requested by an SMB client instead of the program listed in +\fIpasswd program\fR. +It should be possible to enable this without changing your +\fIpasswd chat\fR +parameter for most setups. + +Default: \fBpam password change = no\fR +.TP +\fBpanic action (G)\fR +This is a Samba developer option that allows a +system command to be called when either smbd(8) +crashes. This is usually used to draw attention to the fact that +a problem occurred. + +Default: \fBpanic action = <empty string>\fR + +Example: \fBpanic action = "/bin/sleep 90000"\fR +.TP +\fBpasswd chat (G)\fR +This string controls the \fB"chat"\fR +conversation that takes places between smbdand the local password changing +program to change the user's password. The string describes a +sequence of response-receive pairs that smbd(8)uses to determine what to send to the +\fIpasswd program\fR +and what to expect back. If the expected output is not +received then the password is not changed. + +This chat sequence is often quite site specific, depending +on what local methods are used for password control (such as NIS +etc). + +Note that this parameter only is only used if the \fIunix +password sync\fR parameter is set to yes. This +sequence is then called \fBAS ROOT\fR when the SMB password +in the smbpasswd file is being changed, without access to the old +password cleartext. This means that root must be able to reset the user's password +without knowing the text of the previous password. In the presence of NIS/YP, +this means that the passwd program must be +executed on the NIS master. + +The string can contain the macro \fI%n\fR which is substituted +for the new password. The chat sequence can also contain the standard +macros \\n, \\r, \\t and \\s to give line-feed, +carriage-return, tab and space. The chat sequence string can also contain +a '*' which matches any sequence of characters. +Double quotes can be used to collect strings with spaces +in them into a single string. + +If the send string in any part of the chat sequence +is a full stop ".", then no string is sent. Similarly, +if the expect string is a full stop then no string is expected. + +If the \fIpam +password change\fR parameter is set to true, the chat pairs +may be matched in any order, and success is determined by the PAM result, +not any particular output. The \\n macro is ignored for PAM conversions. + +See also \fIunix password +sync\fR, \fI passwd program\fR , \fIpasswd chat debug\fR and \fIpam password change\fR. + +Default: \fBpasswd chat = *new*password* %n\\n +*new*password* %n\\n *changed*\fR + +Example: \fBpasswd chat = "*Enter OLD password*" %o\\n +"*Enter NEW password*" %n\\n "*Reenter NEW password*" %n\\n "*Password +changed*"\fR +.TP +\fBpasswd chat debug (G)\fR +This boolean specifies if the passwd chat script +parameter is run in \fBdebug\fR mode. In this mode the +strings passed to and received from the passwd chat are printed +in the smbd(8)log with a +\fIdebug level\fR +of 100. This is a dangerous option as it will allow plaintext passwords +to be seen in the \fBsmbd\fR log. It is available to help +Samba admins debug their \fIpasswd chat\fR scripts +when calling the \fIpasswd program\fR and should +be turned off after this has been done. This option has no effect if the +\fIpam password change\fR +paramter is set. This parameter is off by default. + +See also \fIpasswd chat\fR +, \fIpam password change\fR +, \fIpasswd program\fR +\&. + +Default: \fBpasswd chat debug = no\fR +.TP +\fBpasswd program (G)\fR +The name of a program that can be used to set +UNIX user passwords. Any occurrences of \fI%u\fR +will be replaced with the user name. The user name is checked for +existence before calling the password changing program. + +Also note that many passwd programs insist in \fBreasonable +\fRpasswords, such as a minimum length, or the inclusion +of mixed case chars and digits. This can pose a problem as some clients +(such as Windows for Workgroups) uppercase the password before sending +it. + +\fBNote\fR that if the \fIunix +password sync\fR parameter is set to true +then this program is called \fBAS ROOT\fR +before the SMB password in the smbpasswd(5) +file is changed. If this UNIX password change fails, then +\fBsmbd\fR will fail to change the SMB password also +(this is by design). + +If the \fIunix password sync\fR parameter +is set this parameter \fBMUST USE ABSOLUTE PATHS\fR +for \fBALL\fR programs called, and must be examined +for security implications. Note that by default \fIunix +password sync\fR is set to false. + +See also \fIunix +password sync\fR. + +Default: \fBpasswd program = /bin/passwd\fR + +Example: \fBpasswd program = /sbin/npasswd %u\fR +.TP +\fBpassword level (G)\fR +Some client/server combinations have difficulty +with mixed-case passwords. One offending client is Windows for +Workgroups, which for some reason forces passwords to upper +case when using the LANMAN1 protocol, but leaves them alone when +using COREPLUS! Another problem child is the Windows 95/98 +family of operating systems. These clients upper case clear +text passwords even when NT LM 0.12 selected by the protocol +negotiation request/response. + +This parameter defines the maximum number of characters +that may be upper case in passwords. + +For example, say the password given was "FRED". If \fI password level\fR is set to 1, the following combinations +would be tried if "FRED" failed: + +"Fred", "fred", "fRed", "frEd","freD" + +If \fIpassword level\fR was set to 2, +the following combinations would also be tried: + +"FRed", "FrEd", "FreD", "fREd", "fReD", "frED", .. + +And so on. + +The higher value this parameter is set to the more likely +it is that a mixed case password will be matched against a single +case password. However, you should be aware that use of this +parameter reduces security and increases the time taken to +process a new connection. + +A value of zero will cause only two attempts to be +made - the password as is and the password in all-lower case. + +Default: \fBpassword level = 0\fR + +Example: \fBpassword level = 4\fR +.TP +\fBpassword server (G)\fR +By specifying the name of another SMB server (such +as a WinNT box) with this option, and using \fBsecurity = domain +\fRor \fBsecurity = server\fR you can get Samba +to do all its username/password validation via a remote server. + +This option sets the name of the password server to use. +It must be a NetBIOS name, so if the machine's NetBIOS name is +different from its Internet name then you may have to add its NetBIOS +name to the lmhosts file which is stored in the same directory +as the \fIsmb.conf\fR file. + +The name of the password server is looked up using the +parameter \fIname +resolve order\fR and so may resolved +by any method and order described in that parameter. + +The password server much be a machine capable of using +the "LM1.2X002" or the "NT LM 0.12" protocol, and it must be in +user level security mode. + +\fBNOTE:\fR Using a password server +means your UNIX box (running Samba) is only as secure as your +password server. \fBDO NOT CHOOSE A PASSWORD SERVER THAT +YOU DON'T COMPLETELY TRUST\fR. + +Never point a Samba server at itself for password +serving. This will cause a loop and could lock up your Samba +server! + +The name of the password server takes the standard +substitutions, but probably the only useful one is \fI%m +\fR, which means the Samba server will use the incoming +client as the password server. If you use this then you better +trust your clients, and you had better restrict them with hosts allow! + +If the \fIsecurity\fR parameter is set to +domain, then the list of machines in this +option must be a list of Primary or Backup Domain controllers for the +Domain or the character '*', as the Samba server is effectively +in that domain, and will use cryptographically authenticated RPC calls +to authenticate the user logging on. The advantage of using \fB security = domain\fR is that if you list several hosts in the +\fIpassword server\fR option then \fBsmbd +\fRwill try each in turn till it finds one that responds. This +is useful in case your primary server goes down. + +If the \fIpassword server\fR option is set +to the character '*', then Samba will attempt to auto-locate the +Primary or Backup Domain controllers to authenticate against by +doing a query for the name WORKGROUP<1C> +and then contacting each server returned in the list of IP +addresses from the name resolution source. + +If the \fIsecurity\fR parameter is +set to server, then there are different +restrictions that \fBsecurity = domain\fR doesn't +suffer from: +.RS +.TP 0.2i +\(bu +You may list several password servers in +the \fIpassword server\fR parameter, however if an +\fBsmbd\fR makes a connection to a password server, +and then the password server fails, no more users will be able +to be authenticated from this \fBsmbd\fR. This is a +restriction of the SMB/CIFS protocol when in \fBsecurity = server +\fRmode and cannot be fixed in Samba. +.TP 0.2i +\(bu +If you are using a Windows NT server as your +password server then you will have to ensure that your users +are able to login from the Samba server, as when in \fB security = server\fR mode the network logon will appear to +come from there rather than from the users workstation. +.RE +.PP +See also the \fIsecurity +\fRparameter. +.PP +.PP +Default: \fBpassword server = <empty string>\fR +.PP +.PP +Example: \fBpassword server = NT-PDC, NT-BDC1, NT-BDC2 +\fR.PP +.PP +Example: \fBpassword server = *\fR +.PP +.TP +\fBpath (S)\fR +This parameter specifies a directory to which +the user of the service is to be given access. In the case of +printable services, this is where print data will spool prior to +being submitted to the host for printing. + +For a printable service offering guest access, the service +should be readonly and the path should be world-writeable and +have the sticky bit set. This is not mandatory of course, but +you probably won't get the results you expect if you do +otherwise. + +Any occurrences of \fI%u\fR in the path +will be replaced with the UNIX username that the client is using +on this connection. Any occurrences of \fI%m\fR +will be replaced by the NetBIOS name of the machine they are +connecting from. These replacements are very useful for setting +up pseudo home directories for users. + +Note that this path will be based on \fIroot dir\fR if one was specified. + +Default: \fBnone\fR + +Example: \fBpath = /home/fred\fR +.TP +\fBposix locking (S)\fR +The \fBsmbd(8)\fR +daemon maintains an database of file locks obtained by SMB clients. +The default behavior is to map this internal database to POSIX +locks. This means that file locks obtained by SMB clients are +consistent with those seen by POSIX compliant applications accessing +the files via a non-SMB method (e.g. NFS or local file access). +You should never need to disable this parameter. + +Default: \fBposix locking = yes\fR +.TP +\fBpostexec (S)\fR +This option specifies a command to be run +whenever the service is disconnected. It takes the usual +substitutions. The command may be run as the root on some +systems. + +An interesting example may be to unmount server +resources: + +\fBpostexec = /etc/umount /cdrom\fR + +See also \fIpreexec\fR +\&. + +Default: \fBnone (no command executed)\fR + +Example: \fBpostexec = echo \\"%u disconnected from %S +from %m (%I)\\" >> /tmp/log\fR +.TP +\fBpostscript (S)\fR +This parameter forces a printer to interpret +the print files as PostScript. This is done by adding a %! +to the start of print output. + +This is most useful when you have lots of PCs that persist +in putting a control-D at the start of print jobs, which then +confuses your printer. + +Default: \fBpostscript = no\fR +.TP +\fBpreexec (S)\fR +This option specifies a command to be run whenever +the service is connected to. It takes the usual substitutions. + +An interesting example is to send the users a welcome +message every time they log in. Maybe a message of the day? Here +is an example: + +\fBpreexec = csh -c 'echo \\"Welcome to %S!\\" | +/usr/local/samba/bin/smbclient -M %m -I %I' & \fR Of course, this could get annoying after a while :-) -See also postexec - -.B Default: - none (no command executed) - -.B Example: - preexec = echo \"%u connected to %S from %m (%I)\" >> /tmp/log - -.SS preferred master (G) -This boolean parameter controls if Samba is a preferred master browser -for its workgroup. Setting this gives it a slight edge in elections -and also means it will automatically start an election when it starts -up. - -It is on by default. - -.SS preload -This is an alias for "auto services" - -.SS preserve case (S) - -This controls if new filenames are created with the case that the -client passes, or if they are forced to be the "default" case. - -.B Default: - preserve case = no - -See the section on "NAME MANGLING" for a fuller discussion. - -.SS print command (S) -After a print job has finished spooling to a service, this command will be -used via a system() call to process the spool file. Typically the command -specified will submit the spool file to the host's printing subsystem, but -there is no requirement that this be the case. The server will not remove the -spool file, so whatever command you specify should remove the spool file when -it has been processed, otherwise you will need to manually remove old spool -files. - -The print command is simply a text string. It will be used verbatim, -with two exceptions: All occurrences of "%s" will be replaced by the -appropriate spool file name, and all occurrences of "%p" will be -replaced by the appropriate printer name. The spool file name is -generated automatically by the server, the printer name is discussed -below. - -The full path name will be used for the filename if %s is not preceded -by a /. If you don't like this (it can stuff up some lpq output) then -use %f instead. Any occurances of %f get replaced by the spool -filename without the full path at the front. - -The print command MUST contain at least one occurrence of "%s" or %f - -the "%p" is optional. At the time a job is submitted, if no printer -name is supplied the "%p" will be silently removed from the printer -command. - -If specified in the [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 and (most -importantly) not removed. - -Note that printing may fail on some unixes from the "nobody" -account. If this happens then create an alternative guest account that -can print and set the "guest account" in the [global] section. - -You can form quite complex print commands by realising that they are -just passed to a shell. For example the following will log a print -job, print the file, then remove it. Note that ; is the usual -separator for command in shell scripts. - -print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s - -You may have to vary this command considerably depending on how you -normally print files on your system. - -.B Default: - print command = lpr -r -P %p %s - -.B Example: - print command = /usr/local/samba/myprintscript %p %s -.SS print ok (S) -See -.B printable. -.SS printable (S) -A synonym for this parameter is 'print ok'. - -If this parameter is 'yes', then clients may open, write to and submit spool -files on the directory specified for the service. - -Note that a printable service will ALWAYS allow writing to the service path -(user privileges permitting) via the spooling of print data. The 'read only' -parameter controls only non-printing access to the resource. - -.B Default: - printable = no - -.B Example: - printable = yes - -.SS printing (G) -This parameters controls how printer status information is interpreted -on your system, and also affects the default values for the "print -command", "lpq command" and "lprm command". - -Currently three printing styles are supported. They are "printing = -bsd", "printing = sysv", "printing = hpux" and "printing = aix". - -To see what the defaults are for the other print commands when using -these three options use the "testparm" program. - - -.SS printcap name (G) -This parameter may be used to override the compiled-in default printcap -name used by the server (usually /etc/printcap). See the discussion of the -[printers] section above for reasons why you might want to do this. - -For those of you without a printcap (say on SysV) you can just create a -minimal file that looks like a printcap and set "printcap name =" in -[global] to point at it. +See also \fIpreexec close +\fRand \fIpostexec +\fR\&. + +Default: \fBnone (no command executed)\fR + +Example: \fBpreexec = echo \\"%u connected to %S from %m +(%I)\\" >> /tmp/log\fR +.TP +\fBpreexec close (S)\fR +This boolean option controls whether a non-zero +return code from \fIpreexec +\fRshould close the service being connected to. + +Default: \fBpreexec close = no\fR +.TP +\fBpreferred master (G)\fR +This boolean parameter controls if nmbd(8)is a preferred master browser +for its workgroup. + +If this is set to true, on startup, \fBnmbd\fR +will force an election, and it will have a slight advantage in +winning the election. It is recommended that this parameter is +used in conjunction with \fB\fI domain master\fB = yes\fR, so that \fB nmbd\fR can guarantee becoming a domain master. + +Use this option with caution, because if there are several +hosts (whether Samba servers, Windows 95 or NT) that are preferred +master browsers on the same subnet, they will each periodically +and continuously attempt to become the local master browser. +This will result in unnecessary broadcast traffic and reduced browsing +capabilities. + +See also \fIos level\fR +\&. + +Default: \fBpreferred master = auto\fR +.TP +\fBprefered master (G)\fR +Synonym for \fI preferred master\fR for people who cannot spell :-). +.TP +\fBpreload\fR +This is a list of services that you want to be +automatically added to the browse lists. This is most useful +for homes and printers services that would otherwise not be +visible. + +Note that if you just want all printers in your +printcap file loaded then the \fIload printers\fR option is easier. + +Default: \fBno preloaded services\fR + +Example: \fBpreload = fred lp colorlp\fR +.TP +\fBpreserve case (S)\fR +This controls if new filenames are created +with the case that the client passes, or if they are forced to +be the \fIdefault case +\fR\&. + +Default: \fBpreserve case = yes\fR + +See the section on NAME +MANGLING for a fuller discussion. +.TP +\fBprint command (S)\fR +After a print job has finished spooling to +a service, this command will be used via a \fBsystem()\fR +call to process the spool file. Typically the command specified will +submit the spool file to the host's printing subsystem, but there +is no requirement that this be the case. The server will not remove +the spool file, so whatever command you specify should remove the +spool file when it has been processed, otherwise you will need to +manually remove old spool files. + +The print command is simply a text string. It will be used +verbatim, with two exceptions: All occurrences of \fI%s +\fRand \fI%f\fR will be replaced by the +appropriate spool file name, and all occurrences of \fI%p +\fRwill be replaced by the appropriate printer name. The +spool file name is generated automatically by the server. The +\fI%J\fR macro can be used to access the job +name as transmitted by the client. + +The print command \fBMUST\fR contain at least +one occurrence of \fI%s\fR or \fI%f +\fR- the \fI%p\fR is optional. At the time +a job is submitted, if no printer name is supplied the \fI%p +\fRwill be silently removed from the printer command. + +If specified in the [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 and (most importantly) not removed. + +Note that printing may fail on some UNIXes from the +nobody account. If this happens then create +an alternative guest account that can print and set the \fIguest account\fR +in the [global] section. + +You can form quite complex print commands by realizing +that they are just passed to a shell. For example the following +will log a print job, print the file, then remove it. Note that +\&';' is the usual separator for command in shell scripts. + +\fBprint command = echo Printing %s >> +/tmp/print.log; lpr -P %p %s; rm %s\fR + +You may have to vary this command considerably depending +on how you normally print files on your system. The default for +the parameter varies depending on the setting of the \fIprinting\fR parameter. + +Default: For \fBprinting = BSD, AIX, QNX, LPRNG +or PLP :\fR + +\fBprint command = lpr -r -P%p %s\fR + +For \fBprinting = SYSV or HPUX :\fR + +\fBprint command = lp -c -d%p %s; rm %s\fR + +For \fBprinting = SOFTQ :\fR + +\fBprint command = lp -d%p -s %s; rm %s\fR + +Example: \fBprint command = /usr/local/samba/bin/myprintscript +%p %s\fR +.TP +\fBprint ok (S)\fR +Synonym for \fIprintable\fR. +.TP +\fBprintable (S)\fR +If this parameter is yes, then +clients may open, write to and submit spool files on the directory +specified for the service. + +Note that a printable service will ALWAYS allow writing +to the service path (user privileges permitting) via the spooling +of print data. The \fIwriteable +\fRparameter controls only non-printing access to +the resource. + +Default: \fBprintable = no\fR +.TP +\fBprintcap (G)\fR +Synonym for \fI printcap name\fR. +.TP +\fBprintcap name (G)\fR +This parameter may be used to override the +compiled-in default printcap name used by the server (usually \fI /etc/printcap\fR). See the discussion of the [printers] section above for reasons +why you might want to do this. + +On System V systems that use \fBlpstat\fR to +list available printers you can use \fBprintcap name = lpstat +\fRto automatically obtain lists of available printers. This +is the default for systems that define SYSV at configure time in +Samba (this includes most System V based systems). If \fI printcap name\fR is set to \fBlpstat\fR on +these systems then Samba will launch \fBlpstat -v\fR and +attempt to parse the output to obtain a printer list. A minimal printcap file would look something like this: -print1|My Printer 1 -print2|My Printer 2 -print3|My Printer 3 -print4|My Printer 4 -print5|My Printer 5 - -where the | separates aliases of a printer. The fact that the second -alias has a space in it gives a hint to Samba that it's a comment. - -NOTE: Under AIX the default printcap name is "/etc/qconfig". Samba -will assume the file is in AIX "qconfig" format if the string -"/qconfig" appears in the printcap filename. - -.B Default: - printcap name = /etc/printcap - -.B Example: - printcap name = /etc/myprintcap -.SS printer (S) -A synonym for this parameter is 'printer name'. - -This parameter specifies the name of the printer to which print jobs spooled -through a printable service will be sent. - -If specified in the [global] section, the printer name given will be used -for any printable service that does not have its own printer name specified. - -.B Default: - none (but may be 'lp' on many systems) - -.B Example: - printer name = laserwriter -.SS printer name (S) -See -.B printer. -.SS protocol (G) -The value of the parameter (a string) is the highest protocol level that will -be supported by the server. - -Possible values are CORE, COREPLUS, LANMAN1, LANMAN2 and NT1. The relative -merits of each are discussed in the README file. - -.B Default: - protocol = NT1 - -.B Example: - protocol = LANMAN1 -.SS public (S) -A synonym for this parameter is 'guest ok'. - -If this parameter is 'yes' for a service, then no password is required -to connect to the service. Privileges will be those of the guest -account. - -See the section below on user/password validation for more information about -this option. - -.B Default: - public = no - -.B Example: - public = yes -.SS read list (S) -This is a list of users that are given read-only access to a -service. If the connecting user is in this list then they will -not be given write access, no matter what the "read only" option -is set to. The list can include group names using the @group syntax. - -See also the "write list" option - -.B Default: - read list = - -.B Example: - read list = mary, @students - -.SS read only (S) -See -.B writable -and -.B write ok. -Note that this is an inverted synonym for writable and write ok. -.SS read prediction (G) -This options enables or disables the read prediction code used to -speed up reads from the server. When enabled the server will try to -pre-read data from the last accessed file that was opened read-only -while waiting for packets. - -.SS Default: - read prediction = False - -.SS Example: - read prediction = True -.SS read raw (G) -This parameter controls whether or not the server will support raw reads when -transferring data to clients. - -If enabled, raw reads allow reads of 65535 bytes in one packet. This -typically provides a major performance benefit. - -However, some clients either negotiate the allowable block size incorrectly -or are incapable of supporting larger block sizes, and for these clients you -may need to disable raw reads. - -In general this parameter should be viewed as a system tuning tool and left -severely alone. See also -.B write raw. - -.B Default: - read raw = yes - -.B Example: - read raw = no -.SS read size (G) - -The option "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. - -This overlapping works best when the speeds of disk and network access -are similar, having very little effect when the speed of one is much -greater than the other. - -The default value is 2048, but very little experimentation has been -done 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. - -.B Default: - read size = 2048 - -.B Example: - read size = 8192 - -.SS revalidate (S) - -This options controls whether Samba will allow a previously validated -username/password pair to be used to attach to a share. Thus if you -connect to \\\\server\\share1 then to \\\\server\\share2 it won't -automatically allow the client to request connection to the second -share as the same username as the first without a password. - -If "revalidate" is True then the client will be denied automatic -access as the same username. - -.B Default: - revalidate = False - -.B Example: - revalidate = True - -.SS root (G) -See -.B root directory. -.SS root dir (G) -See -.B root directory. -.SS root directory (G) -Synonyms for this parameter are 'root dir' and 'root'. - -The server will chroot() to this directory on startup. This is not -strictly necessary for secure operation. Even without it the server -will deny access to files not in one of the service entries. It may -also check for, and deny access to, soft links to other parts of the -filesystem, or attempts to use .. in file names to access other -directories (depending on the setting of the "wide links" parameter). - -Adding a "root dir" entry other than "/" adds an extra level of security, -but at a price. It absolutely ensures that no access is given to files not -in the sub-tree specified in the "root dir" option, *including* some files -needed for complete operation of the server. To maintain full operability -of the server you will need to mirror some system files into the "root dir" -tree. In particular you will need to mirror /etc/passwd (or a subset of it), -and any binaries or configuration files needed for printing (if required). -The set of files that must be mirrored is operating system dependent. - -.B Default: - root directory = / - -.B Example: - root directory = /homes/smb -.SS security (G) -This option does affects how clients respond to Samba. - -The option sets the "security mode bit" in replies to protocol negotiations -to turn share level security on or off. Clients decide based on this bit -whether (and how) to transfer user and password information to the server. - -The default is "security=SHARE", mainly because that was the only -option at one stage. - -The alternatives are "security = user" or "security = server". - -If your PCs use usernames that are the same as their usernames on the -unix machine then you will want to use "security = user". If you -mostly use usernames that don't exist on the unix box then use -"security = share". - -There is a bug in WfWg that may affect your decision. When in user -level security a WfWg client will totally ignore the password you type -in the "connect drive" dialog box. This makes it very difficult (if -not impossible) to connect to a Samba service as anyone except the -user that you are logged into WfWg as. - -If you use "security = server" then Samba will try to validate the -username/password by passing it to another SMB server, such as an NT -box. If this fails it will revert to "security = USER". - -See the "password server" option for more details. - -.B Default: - security = SHARE - -.B Example: - security = USER -.SS server string (G) -This controls what string will show up in the printer comment box in -print manager and next to the IPC connection in "net view". It can be -any string that you wish to show to your users. - -Note that it DOES NOT affect the string that appears in browse -lists. That is controlled by a nmbd command line option instead. - -A %v will be replaced with the Samba version number. - -A %h will be replaced with the hostname. - -.B Default: - server string = Samba %v - -.B Example: - server string = University of GNUs Samba Server - -.SS smbrun (G) -This sets the full path to the smbrun binary. This defaults to the -value in the Makefile. - -You must get this path right for many services to work correctly. - -.B Default: taken from Makefile - -.B Example: - smbrun = /usr/local/samba/bin/smbrun - -.SS short preserve case (S) - -This controls if new short filenames are created with the case that -the client passes, or if they are forced to be the "default" case. - -.B Default: - short preserve case = no - -See the section on "NAME MANGLING" for a fuller discussion. - -.SS root preexec (S) - -This is the same as preexec except that the command is run as -root. This is useful for mounting filesystems (such as cdroms) before -a connection is finalised. - -.SS root postexec (S) - -This is the same as postexec except that the command is run as -root. This is useful for unmounting filesystems (such as cdroms) after -a connection is closed. - -.SS set directory (S) -If 'set directory = no', then users of the service may not use the setdir -command to change directory. - -The setdir comand is only implemented in the Digital Pathworks client. See the -Pathworks documentation for details. -.B Default: - set directory = no - -.B Example: - set directory = yes - -.SS share modes (S) - -This enables or disables the honouring of the "share modes" during a -file open. These modes are used by clients to gain exclusive read or -write access to a file. - -These open modes are not directly supported by unix, so they are -simulated using lock files in the "lock directory". The "lock -directory" specified in smb.conf must be readable by all users. - -The share modes that are enabled by this option are DENY_DOS, -DENY_ALL, DENY_READ, DENY_WRITE, DENY_NONE and DENY_FCB. - -Enabling this option gives full share compatability but may cost a bit -of processing time on the unix server. They are enabled by default. - -.B Default: - share modes = yes - -.B Example: - share modes = no - -.SS socket options (G) -This option (which can also be invoked with the -O command line -option) allows you to set socket options to be used when talking with -the client. - -Socket options are controls on the networking layer of the operating -systems which allow the connection to be tuned. - -This option will typically be used to tune your Samba server for -optimal performance for your local network. There is no way that Samba -can know what the optimal parameters are for your net, so you must -experiment and choose them yourself. I strongly suggest you read the -appropriate documentation for your operating system first (perhaps -"man setsockopt" will help). - -You may find that on some systems Samba will say "Unknown socket -option" when you supply an option. This means you either mis-typed it -or you need to add an include file to includes.h for your OS. If the -latter is the case please send the patch to me -(samba-bugs@anu.edu.au). - -Any of the supported socket options may be combined in any way you -like, as long as your OS allows it. - -This is the list of socket options currently settable using this -option: - - SO_KEEPALIVE - - SO_REUSEADDR - - SO_BROADCAST - - TCP_NODELAY - - IPTOS_LOWDELAY - - IPTOS_THROUGHPUT - - SO_SNDBUF * - - SO_RCVBUF * - - SO_SNDLOWAT * - - SO_RCVLOWAT * - -Those marked with a * take an integer argument. The others can -optionally take a 1 or 0 argument to enable or disable the option, by -default they will be enabled if you don't specify 1 or 0. - -To specify an argument use the syntax SOME_OPTION=VALUE for example -SO_SNDBUF=8192. Note that you must not have any spaces before or after -the = sign. - -If you are on a local network then a sensible option might be - -socket options = IPTOS_LOWDELAY - -If you have an almost unloaded local network and you don't mind a lot -of extra CPU usage in the server then you could try - -socket options = IPTOS_LOWDELAY TCP_NODELAY - -If you are on a wide area network then perhaps try setting -IPTOS_THROUGHPUT. - -Note that several of the options may cause your Samba server to fail -completely. Use these options with caution! - -.B Default: - no socket options - -.B Example: - socket options = IPTOS_LOWDELAY - - - - -.SS status (G) -This enables or disables logging of connections to a status file that -smbstatus can read. - -With this disabled smbstatus won't be able to tell you what -connections are active. - -.B Default: - status = yes - -.B Example: - status = no - -.SS strip dot (G) -This is a boolean that controls whether to strup trailing dots off -filenames. This helps with some CDROMs that have filenames ending in a -single dot. - -NOTE: This option is now obsolete, and may be removed in future. You -should use the "mangled map" option instead as it is much more -general. - -.SS strict locking (S) -This is a boolean that controls the handling of file locking in the -server. When this is set to yes the server will check every read and -write access for file locks, and deny access if locks exist. This can -be slow on some systems. - -When strict locking is "no" the server does file lock checks only when -the client explicitly asks for them. - -Well behaved clients always ask for lock checks when it is important, -so in the vast majority of cases "strict locking = no" is preferable. - -.B Default: - strict locking = no - -.B Example: - strict locking = yes - -.SS sync always (S) - -This is a boolean parameter that controls whether writes will always -be written to stable storage before the write call returns. If this is -false then the server will be guided by the clients request in each -write call (clients can set a bit indicating that a particular write -should be synchronous). If this is true then every write will be -followed by a fsync() call to ensure the data is written to disk. - -.B Default: - sync always = no - -.B Example: - sync always = yes - -.SS time offset (G) -This parameter is a setting in minutes to add to the normal GMT to -local time conversion. This is useful if you are serving a lot of PCs -that have incorrect daylight saving time handling. - -.B Default: - time offset = 0 - -.B Example: - time offset = 60 - -.SS user (S) -See -.B username. -.SS username (S) -A synonym for this parameter is 'user'. - -Multiple users may be specified in a comma-delimited list, in which case the -supplied password will be tested against each username in turn (left to right). - -The username= line is needed only when the PC is unable to supply it's own -username. This is the case for the coreplus protocol or where your -users have different WfWg usernames to unix usernames. In both these -cases you may also be better using the \\\\server\\share%user syntax -instead. - -The username= line is not a great solution in many cases as it means Samba -will try to validate the supplied password against each of the -usernames in the username= line in turn. This is slow and a bad idea for -lots of users in case of duplicate passwords. You may get timeouts or -security breaches using this parameter unwisely. - -Samba relies on the underlying unix security. This parameter does not -restrict who can login, it just offers hints to the Samba server as to -what usernames might correspond to the supplied password. Users can -login as whoever they please and they will be able to do no more -damage than if they started a telnet session. The daemon runs as the -user that they log in as, so they cannot do anything that user cannot -do. - -To restrict a service to a particular set of users you can use the -"valid users=" line. - -If any of the usernames begin with a @ then the name will be looked up -in the groups file and will expand to a list of all users in the group -of that name. Note that searching though a groups file can take quite -some time, and some clients may time out during the search. - -See the section below on username/password validation for more information -on how this parameter determines access to the services. - -.B Default: - The guest account if a guest service, else the name of the service. - -.B Examples: - username = fred - username = fred, mary, jack, jane, @users, @pcgroup - -.SS username map (G) - -This option allows you to to specify a file containing a mapping of -usernames from the clients to the server. This can be used for several -purposes. The most common is to map usernames that users use on dos or -windows machines to those that the unix box uses. The other is to map -multiple users to a single username so that they can more easily share -files. - -The map file is parsed line by line. Each line should contain a single -unix username on the left then a '=' followed by a list of usernames -on the right. The list of usernames on the right may contain names of -the form @group in which case they will match any unix username in -that group. The special client name '*' is a wildcard and matches any -name. - -The file is processed on each line by taking the supplied username and -comparing it with each username on the right hand side of the '=' -signs. If the supplied name matrches any of the names on the right -hand side then it is replaced with the name on the left. Processing -then continues with the next line. - -If any line begins with a '#' or a ';' then it is ignored - -For example to map from he name "admin" or "administrator" to the unix -name "root" you would use - - root = admin administrator - -Or to map anyone in the unix group "system" to the unix name "sys" you -would use - - sys = @system - -You can have as many mappings as you like in a username map file. - -Note that the remapping is applied to all occurances of -usernames. Thus if you connect to "\\\\server\\fred" and "fred" is -remapped to "mary" then you will actually be connecting to -"\\\\server\\mary" and will need to supply a password suitable for -"mary" not "fred". The only exception to this is the username passwed -to the "password server" (if you have one). The password server will -receive whatever username the client supplies without modification. - -Also note that no reverse mapping is done. The main effect this has is -with printing. Users who have been mapped may have trouble deleting -print jobs as PrintManager under WfWg will think they don't own the -print job. - -.B Default - no username map - -.B Example - username map = /usr/local/samba/lib/users.map - -.SS valid chars (S) - -The option allows you to specify additional characters that should be -considered valid by the server in filenames. This is particularly -useful for national character sets, such as adding u-umlaut or a-ring. - -The option takes a list of characters in either integer or character -form with spaces between them. If you give two characters with a colon -between them then it will be taken as an lowercase:uppercase pair. - -If you have an editor capable of entering the characters into the -config file then it is probably easiest to use this method. Otherwise -you can specify the characters in octal, decimal or hexidecimal form -using the usual C notation. - -For example to add the single character 'Z' to the charset (which is a -pointless thing to do as it's already there) you could do one of the -following - -valid chars = Z -valid chars = z:Z -valid chars = 0132:0172 - -The last two examples above actually add two characters, and alters -the uppercase and lowercase mappings appropriately. - -.B Default - Samba defaults to using a reasonable set of valid characters - for english systems - -.B Example - valid chars = 0345:0305 0366:0326 0344:0304 - -The above example allows filenames to have the swedish characters in -them. - -.SS valid users (S) -This is a list of users that should be allowed to login to this -service. A name starting with @ is interpreted as a unix group. - -If this is empty (the default) then any user can login. If a username -is in both this list and the "invalid users" list then access is -denied for that user. - -The current servicename is substituted for %S. This is useful in the -[homes] section. - -See also "invalid users" - -.B Default - No valid users list. (anyone can login) - -.B Example - valid users = greg, @pcusers - -.SS volume (S) -This allows you to override the volume label returned for a -share. Useful for CDROMs whos installation programs insist on a -particular volume label. - -The default is the name of the share - -.SS wide links (S) -This parameter controls whether or not links in the Unix file system may be -followed by the server. Links that point to areas within the directory tree -exported by the server are always allowed; this parameter controls access -only to areas that are outside the directory tree being exported. - -.B Default: - wide links = yes - -.B Example: - wide links = no - -.SS workgroup (G) - -This controls what workgroup your server will appear to be in when -queried by clients. This can be different to the workgroup specified -in the nmbd configuration, but it is probably best if you set them to -the same value. - -.B Default: - set in the Makefile - -.B Example: - workgroup = MYGROUP +.sp +.nf + print1|My Printer 1 + print2|My Printer 2 + print3|My Printer 3 + print4|My Printer 4 + print5|My Printer 5 + +.sp +.fi + +where the '|' separates aliases of a printer. The fact +that the second alias has a space in it gives a hint to Samba +that it's a comment. + +\fBNOTE\fR: Under AIX the default printcap +name is \fI/etc/qconfig\fR. Samba will assume the +file is in AIX \fIqconfig\fR format if the string +\fIqconfig\fR appears in the printcap filename. + +Default: \fBprintcap name = /etc/printcap\fR + +Example: \fBprintcap name = /etc/myprintcap\fR +.TP +\fBprinter admin (S)\fR +This is a list of users that can do anything to +printers via the remote administration interfaces offered by MS-RPC +(usually using a NT workstation). Note that the root user always +has admin rights. + +Default: \fBprinter admin = <empty string>\fR + +Example: \fBprinter admin = admin, @staff\fR +.TP +\fBprinter driver (S)\fR +\fBNote :\fRThis is a deprecated +parameter and will be removed in the next major release +following version 2.2. Please see the instructions in +the Samba 2.2. Printing +HOWTOfor more information +on the new method of loading printer drivers onto a Samba server. + +This option allows you to control the string +that clients receive when they ask the server for the printer driver +associated with a printer. If you are using Windows95 or Windows NT +then you can use this to automate the setup of printers on your +system. + +You need to set this parameter to the exact string (case +sensitive) that describes the appropriate printer driver for your +system. If you don't know the exact string to use then you should +first try with no \fI printer driver\fR option set and the client will +give you a list of printer drivers. The appropriate strings are +shown in a scroll box after you have chosen the printer manufacturer. + +See also \fIprinter +driver file\fR. + +Example: \fBprinter driver = HP LaserJet 4L\fR +.TP +\fBprinter driver file (G)\fR +\fBNote :\fRThis is a deprecated +parameter and will be removed in the next major release +following version 2.2. Please see the instructions in +the Samba 2.2. Printing +HOWTOfor more information +on the new method of loading printer drivers onto a Samba server. + +This parameter tells Samba where the printer driver +definition file, used when serving drivers to Windows 95 clients, is +to be found. If this is not set, the default is : + +\fISAMBA_INSTALL_DIRECTORY +/lib/printers.def\fR + +This file is created from Windows 95 \fImsprint.inf +\fRfiles found on the Windows 95 client system. For more +details on setting up serving of printer drivers to Windows 95 +clients, see the outdated documentation file in the \fIdocs/\fR +directory, \fIPRINTER_DRIVER.txt\fR. + +See also \fI printer driver location\fR. + +Default: \fBNone (set in compile).\fR + +Example: \fBprinter driver file = +/usr/local/samba/printers/drivers.def\fR +.TP +\fBprinter driver location (S)\fR +\fBNote :\fRThis is a deprecated +parameter and will be removed in the next major release +following version 2.2. Please see the instructions in +the Samba 2.2. Printing +HOWTOfor more information +on the new method of loading printer drivers onto a Samba server. + +This parameter tells clients of a particular printer +share where to find the printer driver files for the automatic +installation of drivers for Windows 95 machines. If Samba is set up +to serve printer drivers to Windows 95 machines, this should be set to + +\fB\\\\MACHINE\\PRINTER$\fR + +Where MACHINE is the NetBIOS name of your Samba server, +and PRINTER$ is a share you set up for serving printer driver +files. For more details on setting this up see the outdated documentation +file in the \fIdocs/\fR directory, \fI PRINTER_DRIVER.txt\fR. + +See also \fI printer driver file\fR. + +Default: \fBnone\fR + +Example: \fBprinter driver location = \\\\MACHINE\\PRINTER$ +\fR.TP +\fBprinter name (S)\fR +This parameter specifies the name of the printer +to which print jobs spooled through a printable service will be sent. + +If specified in the [global] section, the printer +name given will be used for any printable service that does +not have its own printer name specified. + +Default: \fBnone (but may be lp +on many systems)\fR + +Example: \fBprinter name = laserwriter\fR +.TP +\fBprinter (S)\fR +Synonym for \fI printer name\fR. +.TP +\fBprinting (S)\fR +This parameters controls how printer status +information is interpreted on your system. It also affects the +default values for the \fIprint command\fR, +\fIlpq command\fR, \fIlppause command +\fR, \fIlpresume command\fR, and +\fIlprm command\fR if specified in the +[global] section. + +Currently nine printing styles are supported. They are +BSD, AIX, +LPRNG, PLP, +SYSV, HPUX, +QNX, SOFTQ, +and CUPS. + +To see what the defaults are for the other print +commands when using the various options use the testparm(1)program. + +This option can be set on a per printer basis + +See also the discussion in the [printers] section. +.TP +\fBprotocol (G)\fR +Synonym for \fImax protocol\fR. +.TP +\fBpublic (S)\fR +Synonym for \fIguest +ok\fR. +.TP +\fBqueuepause command (S)\fR +This parameter specifies the command to be +executed on the server host in order to pause the printer queue. + +This command should be a program or script which takes +a printer name as its only parameter and stops the printer queue, +such that no longer jobs are submitted to the printer. + +This command is not supported by Windows for Workgroups, +but can be issued from the Printers window under Windows 95 +and NT. + +If a \fI%p\fR is given then the printer name +is put in its place. Otherwise it is placed at the end of the command. + +Note that it is good practice to include the absolute +path in the command as the PATH may not be available to the +server. -.SS write ok (S) -See -.B writable -and -.B read only. -.SS writable (S) -A synonym for this parameter is 'write ok'. An inverted synonym is 'read only'. - -If this parameter is 'no', then users of a service may not create or modify -files in the service's directory. - -Note that a printable service ('printable = yes') will ALWAYS allow -writing to the directory (user privileges permitting), but only via -spooling operations. - -.B Default: - writable = no - -.B Examples: - read only = no - writable = yes - write ok = yes -.SS write list (S) -This is a list of users that are given read-write access to a -service. If the connecting user is in this list then they will be -given write access, no matter what the "read only" option is set -to. The list can include group names using the @group syntax. - -Note that if a user is in both the read list and the write list then -they will be given write access. - -See also the "read list" option - -.B Default: - write list = - -.B Example: - write list = admin, root, @staff - -.SS write raw (G) -This parameter controls whether or not the server will support raw writes when -transferring data from clients. - -.B Default: - write raw = yes - -.B Example: - write raw = no -.SH NOTE ABOUT USERNAME/PASSWORD VALIDATION -There are a number of ways in which a user can connect to a -service. The server follows the following steps in determining if it -will allow a connection to a specified service. If all the steps fail -then the connection request is rejected. If one of the steps pass then -the following steps are not checked. - -If the service is marked "guest only = yes" then steps 1 to 5 are skipped - -Step 1: If the client has passed a username/password pair and that -username/password pair is validated by the unix systems password -programs then the connection is made as that username. Note that this -includes the \\\\server\\service%username method of passing a username. - -Step 2: If the client has previously registered a username with the -system and now supplies a correct password for that username then the -connection is allowed. - -Step 3: The clients netbios name and any previously used user names -are checked against the supplied password, if they match then the -connection is allowed as the corresponding user. - -Step 4: If the client has previously validated a username/password -pair with the server and the client has passed the validation token -then that username is used. This step is skipped if "revalidate = yes" -for this service. - -Step 5: If a "user = " field is given in the smb.conf file for the -service and the client has supplied a password, and that password -matches (according to the unix systems password checking) with one of -the usernames from the user= field then the connection is made as the -username in the "user=" line. If one of the username in the user= list -begins with a @ then that name expands to a list of names in the group -of the same name. - -Step 6: If the service is a guest service then a connection is made as -the username given in the "guest account =" for the service, -irrespective of the supplied password. - - -.SH WARNINGS -Although the configuration file permits service names to contain spaces, -your client software may not. Spaces will be ignored in comparisons anyway, -so it shouldn't be a problem - but be aware of the possibility. - -On a similar note, many clients - especially DOS clients - limit service -names to eight characters. Smbd has no such limitation, but attempts -to connect from such clients will fail if they truncate the service names. -For this reason you should probably keep your service names down to eight -characters in length. - -Use of the [homes] and [printers] special sections make life for an -administrator easy, but the various combinations of default attributes can be -tricky. Take extreme care when designing these sections. In particular, -ensure that the permissions on spool directories are correct. -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the server has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. - -Prior to version 1.5.21 of the Samba suite, the configuration file was -radically different (more primitive). If you are using a version earlier than -1.8.05, it is STRONGLY recommended that you upgrade. -.SH OPTIONS -Not applicable. - -.SH FILES -Not applicable. - -.SH ENVIRONMENT VARIABLES -Not applicable. - -.SH SEE ALSO -.B smbd(8), -.B smbclient(1), -.B nmbd(8), -.B testparm(1), -.B testprns(1), -.B lpq(1), -.B hosts_access(5) -.SH DIAGNOSTICS -[This section under construction] - -Most diagnostics issued by the server are logged in a specified log file. The -log file name is specified at compile time, but may be overridden on the -smbd (see smbd(8)) command line. - -The number and nature of diagnostics available depends on the debug level used -by the server. If you have problems, set the debug level to 3 and peruse the -log files. - -Most messages are reasonably self-explanatory. Unfortunately, at time of -creation of this man page the source code is still too fluid to warrant -describing each and every diagnostic. At this stage your best bet is still -to grep the source code and inspect the conditions that gave rise to the -diagnostics you are seeing. - -.SH BUGS -None known. - -Please send bug reports, comments and so on to: - -.RS 3 -.B samba-bugs@anu.edu.au (Andrew Tridgell) - -.RS 3 -or to the mailing list -.RE +Default: \fBdepends on the setting of \fIprinting +\fB\fR +Example: \fBqueuepause command = disable %p\fR +.TP +\fBqueueresume command (S)\fR +This parameter specifies the command to be +executed on the server host in order to resume the printer queue. It +is the command to undo the behavior that is caused by the +previous parameter (\fI queuepause command\fR). + +This command should be a program or script which takes +a printer name as its only parameter and resumes the printer queue, +such that queued jobs are resubmitted to the printer. + +This command is not supported by Windows for Workgroups, +but can be issued from the Printers window under Windows 95 +and NT. + +If a \fI%p\fR is given then the printer name +is put in its place. Otherwise it is placed at the end of the +command. -.B samba@listproc.anu.edu.au +Note that it is good practice to include the absolute +path in the command as the PATH may not be available to the +server. +Default: \fBdepends on the setting of \fIprinting\fB\fR + +Example: \fBqueuepause command = enable %p +\fR.TP +\fBread bmpx (G)\fR +This boolean parameter controls whether smbd(8)will support the "Read +Block Multiplex" SMB. This is now rarely used and defaults to +no. You should never need to set this +parameter. + +Default: \fBread bmpx = no\fR +.TP +\fBread list (S)\fR +This is a list of users that are given read-only +access to a service. If the connecting user is in this list then +they will not be given write access, no matter what the \fIwriteable\fR +option is set to. The list can include group names using the +syntax described in the \fI invalid users\fR parameter. + +See also the \fI write list\fR parameter and the \fIinvalid users\fR +parameter. + +Default: \fBread list = <empty string>\fR + +Example: \fBread list = mary, @students\fR +.TP +\fBread only (S)\fR +Note that this is an inverted synonym for \fIwriteable\fR. +.TP +\fBread raw (G)\fR +This parameter controls whether or not the server +will support the raw read SMB requests when transferring data +to clients. + +If enabled, raw reads allow reads of 65535 bytes in +one packet. This typically provides a major performance benefit. + +However, some clients either negotiate the allowable +block size incorrectly or are incapable of supporting larger block +sizes, and for these clients you may need to disable raw reads. + +In general this parameter should be viewed as a system tuning +tool and left severely alone. See also \fIwrite raw\fR. + +Default: \fBread raw = yes\fR +.TP +\fBread size (G)\fR +The option \fIread size\fR +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. + +This overlapping works best when the speeds of disk and +network access are similar, having very little effect when the +speed of one is much greater than the other. + +The default value is 16384, but very little experimentation +has been done 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. + +Default: \fBread size = 16384\fR + +Example: \fBread size = 8192\fR +.TP +\fBremote announce (G)\fR +This option allows you to setup nmbd(8)to periodically announce itself +to arbitrary IP addresses with an arbitrary workgroup name. + +This is useful if you want your Samba server to appear +in a remote workgroup for which the normal browse propagation +rules don't work. The remote workgroup can be anywhere that you +can send IP packets to. + +For example: + +\fBremote announce = 192.168.2.255/SERVERS +192.168.4.255/STAFF\fR + +the above line would cause \fBnmbd\fR to announce itself +to the two given IP addresses using the given workgroup names. +If you leave out the workgroup name then the one given in +the \fIworkgroup\fR +parameter is used instead. + +The IP addresses you choose would normally be the broadcast +addresses of the remote networks, but can also be the IP addresses +of known browse masters if your network config is that stable. + +See the documentation file \fIBROWSING.txt\fR +in the \fIdocs/\fR directory. + +Default: \fBremote announce = <empty string> +\fR.TP +\fBremote browse sync (G)\fR +This option allows you to setup nmbd(8)to periodically request +synchronization of browse lists with the master browser of a Samba +server that is on a remote segment. This option will allow you to +gain browse lists for multiple workgroups across routed networks. This +is done in a manner that does not work with any non-Samba servers. + +This is useful if you want your Samba server and all local +clients to appear in a remote workgroup for which the normal browse +propagation rules don't work. The remote workgroup can be anywhere +that you can send IP packets to. + +For example: + +\fBremote browse sync = 192.168.2.255 192.168.4.255 +\fR +the above line would cause \fBnmbd\fR to request +the master browser on the specified subnets or addresses to +synchronize their browse lists with the local server. + +The IP addresses you choose would normally be the broadcast +addresses of the remote networks, but can also be the IP addresses +of known browse masters if your network config is that stable. If +a machine IP address is given Samba makes NO attempt to validate +that the remote machine is available, is listening, nor that it +is in fact the browse master on its segment. + +Default: \fBremote browse sync = <empty string> +\fR.TP +\fBrestrict anonymous (G)\fR +This is a boolean parameter. If it is true, then +anonymous access to the server will be restricted, namely in the +case where the server is expecting the client to send a username, +but it doesn't. Setting it to true will force these anonymous +connections to be denied, and the client will be required to always +supply a username and password when connecting. Use of this parameter +is only recommended for homogeneous NT client environments. + +This parameter makes the use of macro expansions that rely +on the username (%U, %G, etc) consistent. NT 4.0 +likes to use anonymous connections when refreshing the share list, +and this is a way to work around that. + +When restrict anonymous is true, all anonymous connections +are denied no matter what they are for. This can effect the ability +of a machine to access the Samba Primary Domain Controller to revalidate +its machine account after someone else has logged on the client +interactively. The NT client will display a message saying that +the machine's account in the domain doesn't exist or the password is +bad. The best way to deal with this is to reboot NT client machines +between interactive logons, using "Shutdown and Restart", rather +than "Close all programs and logon as a different user". + +Default: \fBrestrict anonymous = no\fR +.TP +\fBroot (G)\fR +Synonym for \fIroot directory"\fR. +.TP +\fBroot dir (G)\fR +Synonym for \fIroot directory"\fR. +.TP +\fBroot directory (G)\fR +The server will \fBchroot()\fR (i.e. +Change its root directory) to this directory on startup. This is +not strictly necessary for secure operation. Even without it the +server will deny access to files not in one of the service entries. +It may also check for, and deny access to, soft links to other +parts of the filesystem, or attempts to use ".." in file names +to access other directories (depending on the setting of the \fIwide links\fR +parameter). + +Adding a \fIroot directory\fR entry other +than "/" adds an extra level of security, but at a price. It +absolutely ensures that no access is given to files not in the +sub-tree specified in the \fIroot directory\fR +option, \fBincluding\fR some files needed for +complete operation of the server. To maintain full operability +of the server you will need to mirror some system files +into the \fIroot directory\fR tree. In particular +you will need to mirror \fI/etc/passwd\fR (or a +subset of it), and any binaries or configuration files needed for +printing (if required). The set of files that must be mirrored is +operating system dependent. + +Default: \fBroot directory = /\fR + +Example: \fBroot directory = /homes/smb\fR +.TP +\fBroot postexec (S)\fR +This is the same as the \fIpostexec\fR +parameter except that the command is run as root. This +is useful for unmounting filesystems +(such as CDROMs) after a connection is closed. + +See also \fI postexec\fR. + +Default: \fBroot postexec = <empty string> +\fR.TP +\fBroot preexec (S)\fR +This is the same as the \fIpreexec\fR +parameter except that the command is run as root. This +is useful for mounting filesystems (such as CDROMs) when a +connection is opened. + +See also \fI preexec\fR and \fIpreexec close\fR. + +Default: \fBroot preexec = <empty string> +\fR.TP +\fBroot preexec close (S)\fR +This is the same as the \fIpreexec close +\fRparameter except that the command is run as root. + +See also \fI preexec\fR and \fIpreexec close\fR. + +Default: \fBroot preexec close = no\fR +.TP +\fBsecurity (G)\fR +This option affects how clients respond to +Samba and is one of the most important settings in the \fI smb.conf\fR file. + +The option sets the "security mode bit" in replies to +protocol negotiations with smbd(8) +to turn share level security on or off. Clients decide +based on this bit whether (and how) to transfer user and password +information to the server. + +The default is \fBsecurity = user\fR, as this is +the most common setting needed when talking to Windows 98 and +Windows NT. + +The alternatives are \fBsecurity = share\fR, +\fBsecurity = server\fR or \fBsecurity = domain +\fR\&. + +In versions of Samba prior to 2.0.0, the default was +\fBsecurity = share\fR mainly because that was +the only option at one stage. + +There is a bug in WfWg that has relevance to this +setting. When in user or server level security a WfWg client +will totally ignore the password you type in the "connect +drive" dialog box. This makes it very difficult (if not impossible) +to connect to a Samba service as anyone except the user that +you are logged into WfWg as. + +If your PCs use usernames that are the same as their +usernames on the UNIX machine then you will want to use +\fBsecurity = user\fR. If you mostly use usernames +that don't exist on the UNIX box then use \fBsecurity = +share\fR. + +You should also use \fBsecurity = share\fR if you +want to mainly setup shares without a password (guest shares). This +is commonly used for a shared printer server. It is more difficult +to setup guest shares with \fBsecurity = user\fR, see +the \fImap to guest\fR +parameter for details. + +It is possible to use \fBsmbd\fR in a \fB hybrid mode\fR where it is offers both user and share +level security under different \fINetBIOS aliases\fR. + +The different settings will now be explained. + +\fBSECURITY = SHARE +\fR +When clients connect to a share level security server they +need not log onto the server with a valid username and password before +attempting to connect to a shared resource (although modern clients +such as Windows 95/98 and Windows NT will send a logon request with +a username but no password when talking to a \fBsecurity = share +\fRserver). Instead, the clients send authentication information +(passwords) on a per-share basis, at the time they attempt to connect +to that share. + +Note that \fBsmbd\fR \fBALWAYS\fR +uses a valid UNIX user to act on behalf of the client, even in +\fBsecurity = share\fR level security. + +As clients are not required to send a username to the server +in share level security, \fBsmbd\fR uses several +techniques to determine the correct UNIX user to use on behalf +of the client. + +A list of possible UNIX usernames to match with the given +client password is constructed using the following methods : +.RS +.TP 0.2i +\(bu +If the \fIguest +only\fR parameter is set, then all the other +stages are missed and only the \fIguest account\fR username is checked. +.TP 0.2i +\(bu +Is a username is sent with the share connection +request, then this username (after mapping - see \fIusername map\fR), +is added as a potential username. +.TP 0.2i +\(bu +If the client did a previous \fBlogon +\fRrequest (the SessionSetup SMB call) then the +username sent in this SMB will be added as a potential username. +.TP 0.2i +\(bu +The name of the service the client requested is +added as a potential username. +.TP 0.2i +\(bu +The NetBIOS name of the client is added to +the list as a potential username. +.TP 0.2i +\(bu +Any users on the \fI user\fR list are added as potential usernames. .RE -You may also like to subscribe to the announcement channel +.PP +If the \fIguest only\fR parameter is +not set, then this list is then tried with the supplied password. +The first user for whom the password matches will be used as the +UNIX user. +.PP +.PP +If the \fIguest only\fR parameter is +set, or no username can be determined then if the share is marked +as available to the \fIguest account\fR, then this +guest user will be used, otherwise access is denied. +.PP +.PP +Note that it can be \fBvery\fR confusing +in share-level security as to which UNIX username will eventually +be used in granting access. +.PP +.PP +See also the section NOTE ABOUT USERNAME/PASSWORD VALIDATION. +.PP +.PP +\fBSECURITY = USER +\fR.PP +.PP +This is the default security setting in Samba 2.2. +With user-level security a client must first "log-on" with a +valid username and password (which can be mapped using the \fIusername map\fR +parameter). Encrypted passwords (see the \fIencrypted passwords\fR parameter) can also +be used in this security mode. Parameters such as \fIuser\fR and \fIguest only\fR if set are then applied and +may change the UNIX user to use on this connection, but only after +the user has been successfully authenticated. +.PP +.PP +\fBNote\fR that the name of the resource being +requested is \fBnot\fR sent to the server until after +the server has successfully authenticated the client. This is why +guest shares don't work in user level security without allowing +the server to automatically map unknown users into the \fIguest account\fR. +See the \fImap to guest\fR +parameter for details on doing this. +.PP +.PP +See also the section NOTE ABOUT USERNAME/PASSWORD VALIDATION. +.PP +.PP +\fBSECURITY = SERVER +\fR.PP +.PP +In this mode Samba will try to validate the username/password +by passing it to another SMB server, such as an NT box. If this +fails it will revert to \fBsecurity = user\fR, but note +that if encrypted passwords have been negotiated then Samba cannot +revert back to checking the UNIX password file, it must have a valid +\fIsmbpasswd\fR file to check users against. See the +documentation file in the \fIdocs/\fR directory +\fIENCRYPTION.txt\fR for details on how to set this +up. +.PP +.PP +\fBNote\fR that from the client's point of +view \fBsecurity = server\fR is the same as \fB security = user\fR. It only affects how the server deals +with the authentication, it does not in any way affect what the +client sees. +.PP +.PP +\fBNote\fR that the name of the resource being +requested is \fBnot\fR sent to the server until after +the server has successfully authenticated the client. This is why +guest shares don't work in user level security without allowing +the server to automatically map unknown users into the \fIguest account\fR. +See the \fImap to guest\fR +parameter for details on doing this. +.PP +.PP +See also the section NOTE ABOUT USERNAME/PASSWORD VALIDATION. +.PP +.PP +See also the \fIpassword +server\fR parameter and the \fIencrypted passwords\fR +parameter. +.PP +.PP +\fBSECURITY = DOMAIN +\fR.PP +.PP +This mode will only work correctly if smbpasswd(8)has been used to add this +machine into a Windows NT Domain. It expects the \fIencrypted passwords\fR +parameter to be set to true. In this +mode Samba will try to validate the username/password by passing +it to a Windows NT Primary or Backup Domain Controller, in exactly +the same way that a Windows NT Server would do. +.PP +.PP +\fBNote\fR that a valid UNIX user must still +exist as well as the account on the Domain Controller to allow +Samba to have a valid UNIX account to map file access to. +.PP +.PP +\fBNote\fR that from the client's point +of view \fBsecurity = domain\fR is the same as \fBsecurity = user +\fR\&. It only affects how the server deals with the authentication, +it does not in any way affect what the client sees. +.PP +.PP +\fBNote\fR that the name of the resource being +requested is \fBnot\fR sent to the server until after +the server has successfully authenticated the client. This is why +guest shares don't work in user level security without allowing +the server to automatically map unknown users into the \fIguest account\fR. +See the \fImap to guest\fR +parameter for details on doing this. +.PP +.PP +\fBBUG:\fR There is currently a bug in the +implementation of \fBsecurity = domain\fR with respect +to multi-byte character set usernames. The communication with a +Domain Controller must be done in UNICODE and Samba currently +does not widen multi-byte user names to UNICODE correctly, thus +a multi-byte username will not be recognized correctly at the +Domain Controller. This issue will be addressed in a future release. +.PP +.PP +See also the section NOTE ABOUT USERNAME/PASSWORD VALIDATION. +.PP +.PP +See also the \fIpassword +server\fR parameter and the \fIencrypted passwords\fR +parameter. +.PP +.PP +Default: \fBsecurity = USER\fR +.PP +.PP +Example: \fBsecurity = DOMAIN\fR +.PP +.TP +\fBsecurity mask (S)\fR +This parameter controls what UNIX permission +bits can be modified when a Windows NT client is manipulating +the UNIX permission on a file using the native NT security +dialog box. + +This parameter is applied as a mask (AND'ed with) to +the changed permission bits, thus preventing any bits not in +this mask from being modified. Essentially, zero bits in this +mask may be treated as a set of bits the user is not allowed +to change. + +If not set explicitly this parameter is 0777, allowing +a user to modify all the user/group/world permissions on a file. + +\fBNote\fR that users who can access the +Samba server through other means can easily bypass this +restriction, so it is primarily useful for standalone +"appliance" systems. Administrators of most normal systems will +probably want to leave it set to 0777. + +See also the \fIforce directory security mode\fR, +\fIdirectory +security mask\fR, \fIforce security mode\fR parameters. + +Default: \fBsecurity mask = 0777\fR + +Example: \fBsecurity mask = 0770\fR +.TP +\fBserver string (G)\fR +This controls what string will show up in the +printer comment box in print manager and next to the IPC connection +in \fBnet view\fR. It can be any string that you wish +to show to your users. + +It also sets what will appear in browse lists next +to the machine name. + +A \fI%v\fR will be replaced with the Samba +version number. + +A \fI%h\fR will be replaced with the +hostname. + +Default: \fBserver string = Samba %v\fR + +Example: \fBserver string = University of GNUs Samba +Server\fR +.TP +\fBset directory (S)\fR +If \fBset directory = no\fR, then +users of the service may not use the setdir command to change +directory. + +The \fBsetdir\fR command is only implemented +in the Digital Pathworks client. See the Pathworks documentation +for details. + +Default: \fBset directory = no\fR +.TP +\fBshort preserve case (S)\fR +This boolean parameter controls if new files +which conform to 8.3 syntax, that is all in upper case and of +suitable length, are created upper case, or if they are forced +to be the \fIdefault case +\fR\&. This option can be use with \fBpreserve case = yes\fR +to permit long filenames to retain their case, while short +names are lowered. + +See the section on NAME MANGLING. + +Default: \fBshort preserve case = yes\fR +.TP +\fBshow add printer wizard (G)\fR +With the introduction of MS-RPC based printing support +for Windows NT/2000 client in Samba 2.2, a "Printers..." folder will +appear on Samba hosts in the share listing. Normally this folder will +contain an icon for the MS Add Printer Wizard (APW). However, it is +possible to disable this feature regardless of the level of privilege +of the connected user. + +Under normal circumstances, the Windows NT/2000 client will +open a handle on the printer server with OpenPrinterEx() asking for +Administrator privileges. If the user does not have administrative +access on the print server (i.e is not root or a member of the +\fIprinter admin\fR group), the OpenPrinterEx() +call fails and the client makes another open call with a request for +a lower privilege level. This should succeed, however the APW +icon will not be displayed. + +Disabling the \fIshow add printer wizard\fR +parameter will always cause the OpenPrinterEx() on the server +to fail. Thus the APW icon will never be displayed. \fB Note :\fRThis does not prevent the same user from having +administrative privilege on an individual printer. + +See also \fIaddprinter +command\fR, \fIdeleteprinter command\fR, \fIprinter admin\fR + +Default :\fBshow add printer wizard = yes\fR +.TP +\fBshutdown script (G)\fR +\fBThis parameter only exists in the HEAD cvs branch\fR +This a full path name to a script called by +\fBsmbd(8)\fRthat +should start a shutdown procedure. + +This command will be run as the user connected to the +server. -.RS 3 -samba-announce@listproc.anu.edu.au +%m %t %r %f parameters are expanded + +\fI%m\fR will be substituted with the +shutdown message sent to the server. + +\fI%t\fR will be substituted with the +number of seconds to wait before effectively starting the +shutdown procedure. + +\fI%r\fR will be substituted with the +switch \fB-r\fR. It means reboot after shutdown +for NT. + +\fI%f\fR will be substituted with the +switch \fB-f\fR. It means force the shutdown +even if applications do not respond for NT. + +Default: \fBNone\fR. + +Example: \fBabort shutdown script = /usr/local/samba/sbin/shutdown %m %t %r %f\fR + +Shutdown script example: +.sp +.nf + #!/bin/bash + + $time=0 + let "time/60" + let "time++" + + /sbin/shutdown $3 $4 +$time $1 & + +.sp +.fi +Shutdown does not return so we need to launch it in background. + +See also \fIabort shutdown script\fR. +.TP +\fBsmb passwd file (G)\fR +This option sets the path to the encrypted +smbpasswd file. By default the path to the smbpasswd file +is compiled into Samba. + +Default: \fBsmb passwd file = ${prefix}/private/smbpasswd +\fR +Example: \fBsmb passwd file = /etc/samba/smbpasswd +\fR.TP +\fBsocket address (G)\fR +This option allows you to control what +address Samba will listen for connections on. This is used to +support multiple virtual interfaces on the one server, each +with a different configuration. + +By default Samba will accept connections on any +address. + +Example: \fBsocket address = 192.168.2.20\fR +.TP +\fBsocket options (G)\fR +This option allows you to set socket options +to be used when talking with the client. + +Socket options are controls on the networking layer +of the operating systems which allow the connection to be +tuned. + +This option will typically be used to tune your Samba +server for optimal performance for your local network. There is +no way that Samba can know what the optimal parameters are for +your net, so you must experiment and choose them yourself. We +strongly suggest you read the appropriate documentation for your +operating system first (perhaps \fBman setsockopt\fR +will help). + +You may find that on some systems Samba will say +"Unknown socket option" when you supply an option. This means you +either incorrectly typed it or you need to add an include file +to includes.h for your OS. If the latter is the case please +send the patch to samba@samba.org <URL:mailto:samba@samba.org>. + +Any of the supported socket options may be combined +in any way you like, as long as your OS allows it. + +This is the list of socket options currently settable +using this option: +.RS +.TP 0.2i +\(bu +SO_KEEPALIVE +.TP 0.2i +\(bu +SO_REUSEADDR +.TP 0.2i +\(bu +SO_BROADCAST +.TP 0.2i +\(bu +TCP_NODELAY +.TP 0.2i +\(bu +IPTOS_LOWDELAY +.TP 0.2i +\(bu +IPTOS_THROUGHPUT +.TP 0.2i +\(bu +SO_SNDBUF * +.TP 0.2i +\(bu +SO_RCVBUF * +.TP 0.2i +\(bu +SO_SNDLOWAT * +.TP 0.2i +\(bu +SO_RCVLOWAT * .RE - -To subscribe to these lists send a message to -listproc@listproc.anu.edu.au with a body of "subscribe samba Your -Name" or "subscribe samba-announce Your Name". - -Errors or suggestions for improvements to the Samba man pages should be -mailed to: - -.RS 3 -.B samba-bugs@anu.edu.au (Andrew Tridgell) +.PP +Those marked with a \fB'*'\fR take an integer +argument. The others can optionally take a 1 or 0 argument to enable +or disable the option, by default they will be enabled if you +don't specify 1 or 0. +.PP +.PP +To specify an argument use the syntax SOME_OPTION = VALUE +for example \fBSO_SNDBUF = 8192\fR. Note that you must +not have any spaces before or after the = sign. +.PP +.PP +If you are on a local network then a sensible option +might be +.PP +.PP +\fBsocket options = IPTOS_LOWDELAY\fR +.PP +.PP +If you have a local network then you could try: +.PP +.PP +\fBsocket options = IPTOS_LOWDELAY TCP_NODELAY\fR +.PP +.PP +If you are on a wide area network then perhaps try +setting IPTOS_THROUGHPUT. +.PP +.PP +Note that several of the options may cause your Samba +server to fail completely. Use these options with caution! +.PP +.PP +Default: \fBsocket options = TCP_NODELAY\fR +.PP +.PP +Example: \fBsocket options = IPTOS_LOWDELAY\fR +.PP +.TP +\fBsource environment (G)\fR +This parameter causes Samba to set environment +variables as per the content of the file named. + +If the value of this parameter starts with a "|" character +then Samba will treat that value as a pipe command to open and +will set the environment variables from the output of the pipe. + +The contents of the file or the output of the pipe should +be formatted as the output of the standard Unix \fBenv(1) +\fRcommand. This is of the form : + +Example environment entry: + +\fBSAMBA_NETBIOS_NAME = myhostname\fR + +Default: \fBNo default value\fR + +Examples: \fBsource environment = |/etc/smb.conf.sh +\fR +Example: \fBsource environment = +/usr/local/smb_env_vars\fR +.TP +\fBssl (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This variable enables or disables the entire SSL mode. If +it is set to no, the SSL-enabled Samba behaves +exactly like the non-SSL Samba. If set to yes, +it depends on the variables \fI ssl hosts\fR and \fIssl hosts resign\fR whether an SSL +connection will be required. + +Default: \fBssl = no\fR +.TP +\fBssl CA certDir (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This variable defines where to look up the Certification +Authorities. The given directory should contain one file for +each CA that Samba will trust. The file name must be the hash +value over the "Distinguished Name" of the CA. How this directory +is set up is explained later in this document. All files within the +directory that don't fit into this naming scheme are ignored. You +don't need this variable if you don't verify client certificates. + +Default: \fBssl CA certDir = /usr/local/ssl/certs +\fR.TP +\fBssl CA certFile (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This variable is a second way to define the trusted CAs. +The certificates of the trusted CAs are collected in one big +file and this variable points to the file. You will probably +only use one of the two ways to define your CAs. The first choice is +preferable if you have many CAs or want to be flexible, the second +is preferable if you only have one CA and want to keep things +simple (you won't need to create the hashed file names). You +don't need this variable if you don't verify client certificates. + +Default: \fBssl CA certFile = /usr/local/ssl/certs/trustedCAs.pem +\fR.TP +\fBssl ciphers (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This variable defines the ciphers that should be offered +during SSL negotiation. You should not set this variable unless +you know what you are doing. +.TP +\fBssl client cert (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +The certificate in this file is used by \fBsmbclient(1)\fRif it exists. It's needed +if the server requires a client certificate. + +Default: \fBssl client cert = /usr/local/ssl/certs/smbclient.pem +\fR.TP +\fBssl client key (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This is the private key for \fBsmbclient(1)\fR. It's only needed if the +client should have a certificate. + +Default: \fBssl client key = /usr/local/ssl/private/smbclient.pem +\fR.TP +\fBssl compatibility (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This variable defines whether OpenSSL should be configured +for bug compatibility with other SSL implementations. This is +probably not desirable because currently no clients with SSL +implementations other than OpenSSL exist. + +Default: \fBssl compatibility = no\fR +.TP +\fBssl egd socket (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This option is used to define the location of the communiation socket of +an EGD or PRNGD daemon, from which entropy can be retrieved. This option +can be used instead of or together with the \fIssl entropy file\fR +directive. 255 bytes of entropy will be retrieved from the daemon. + +Default: \fBnone\fR +.TP +\fBssl entropy bytes (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This parameter is used to define the number of bytes which should +be read from the \fIssl entropy +file\fR If a -1 is specified, the entire file will +be read. + +Default: \fBssl entropy bytes = 255\fR +.TP +\fBssl entropy file (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This parameter is used to specify a file from which processes will +read "random bytes" on startup. In order to seed the internal pseudo +random number generator, entropy must be provided. On system with a +\fI/dev/urandom\fR device file, the processes +will retrieve its entropy from the kernel. On systems without kernel +entropy support, a file can be supplied that will be read on startup +and that will be used to seed the PRNG. + +Default: \fBnone\fR +.TP +\fBssl hosts (G)\fR +See \fI ssl hosts resign\fR. +.TP +\fBssl hosts resign (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +These two variables define whether Samba will go +into SSL mode or not. If none of them is defined, Samba will +allow only SSL connections. If the \fIssl hosts\fR variable lists +hosts (by IP-address, IP-address range, net group or name), +only these hosts will be forced into SSL mode. If the \fI ssl hosts resign\fR variable lists hosts, only these +hosts will \fBNOT\fR be forced into SSL mode. The syntax for these two +variables is the same as for the \fI hosts allow\fR and \fIhosts deny\fR pair of variables, only +that the subject of the decision is different: It's not the access +right but whether SSL is used or not. + +The example below requires SSL connections from all hosts +outside the local net (which is 192.168.*.*). + +Default: \fBssl hosts = <empty string>\fR + +\fBssl hosts resign = <empty string>\fR + +Example: \fBssl hosts resign = 192.168.\fR +.TP +\fBssl require clientcert (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +If this variable is set to yes, the +server will not tolerate connections from clients that don't +have a valid certificate. The directory/file given in \fIssl CA certDir\fR +and \fIssl CA certFile +\fRwill be used to look up the CAs that issued +the client's certificate. If the certificate can't be verified +positively, the connection will be terminated. If this variable +is set to no, clients don't need certificates. +Contrary to web applications you really \fBshould\fR +require client certificates. In the web environment the client's +data is sensitive (credit card numbers) and the server must prove +to be trustworthy. In a file server environment the server's data +will be sensitive and the clients must prove to be trustworthy. + +Default: \fBssl require clientcert = no\fR +.TP +\fBssl require servercert (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +If this variable is set to yes, the +\fBsmbclient(1)\fR +will request a certificate from the server. Same as +\fIssl require +clientcert\fR for the server. + +Default: \fBssl require servercert = no\fR +.TP +\fBssl server cert (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This is the file containing the server's certificate. +The server \fBmust\fR have a certificate. The +file may also contain the server's private key. See later for +how certificates and private keys are created. + +Default: \fBssl server cert = <empty string> +\fR.TP +\fBssl server key (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This file contains the private key of the server. If +this variable is not defined, the key is looked up in the +certificate file (it may be appended to the certificate). +The server \fBmust\fR have a private key +and the certificate \fBmust\fR +match this private key. + +Default: \fBssl server key = <empty string> +\fR.TP +\fBssl version (G)\fR +This variable is part of SSL-enabled Samba. This +is only available if the SSL libraries have been compiled on your +system and the configure option \fB--with-ssl\fR was +given at configure time. + +This enumeration variable defines the versions of the +SSL protocol that will be used. ssl2or3 allows +dynamic negotiation of SSL v2 or v3, ssl2 results +in SSL v2, ssl3 results in SSL v3 and +tls1 results in TLS v1. TLS (Transport Layer +Security) is the new standard for SSL. + +Default: \fBssl version = "ssl2or3"\fR +.TP +\fBstat cache (G)\fR +This parameter determines if smbd(8)will use a cache in order to +speed up case insensitive name mappings. You should never need +to change this parameter. + +Default: \fBstat cache = yes\fR +.TP +\fBstat cache size (G)\fR +This parameter determines the number of +entries in the \fIstat cache\fR. You should +never need to change this parameter. + +Default: \fBstat cache size = 50\fR +.TP +\fBstatus (G)\fR +This enables or disables logging of connections +to a status file that smbstatus(1) +can read. + +With this disabled \fBsmbstatus\fR won't be able +to tell you what connections are active. You should never need to +change this parameter. + +Default: \fBstatus = yes\fR +.TP +\fBstrict allocate (S)\fR +This is a boolean that controls the handling of +disk space allocation in the server. When this is set to yes +the server will change from UNIX behaviour of not committing real +disk storage blocks when a file is extended to the Windows behaviour +of actually forcing the disk system to allocate real storage blocks +when a file is created or extended to be a given size. In UNIX +terminology this means that Samba will stop creating sparse files. +This can be slow on some systems. + +When strict allocate is no the server does sparse +disk block allocation when a file is extended. + +Setting this to yes can help Samba return +out of quota messages on systems that are restricting the disk quota +of users. + +Default: \fBstrict allocate = no\fR +.TP +\fBstrict locking (S)\fR +This is a boolean that controls the handling of +file locking in the server. When this is set to yes +the server will check every read and write access for file locks, and +deny access if locks exist. This can be slow on some systems. + +When strict locking is no the server does file +lock checks only when the client explicitly asks for them. + +Well-behaved clients always ask for lock checks when it +is important, so in the vast majority of cases \fBstrict +locking = no\fR is preferable. + +Default: \fBstrict locking = no\fR +.TP +\fBstrict sync (S)\fR +Many Windows applications (including the Windows +98 explorer shell) seem to confuse flushing buffer contents to +disk with doing a sync to disk. Under UNIX, a sync call forces +the process to be suspended until the kernel has ensured that +all outstanding data in kernel disk buffers has been safely stored +onto stable storage. This is very slow and should only be done +rarely. Setting this parameter to no (the +default) means that smbdignores the Windows applications requests for +a sync call. There is only a possibility of losing data if the +operating system itself that Samba is running on crashes, so there is +little danger in this default setting. In addition, this fixes many +performance problems that people have reported with the new Windows98 +explorer shell file copies. + +See also the \fIsync +always>\fR parameter. + +Default: \fBstrict sync = no\fR +.TP +\fBstrip dot (G)\fR +This is a boolean that controls whether to +strip trailing dots off UNIX filenames. This helps with some +CDROMs that have filenames ending in a single dot. + +Default: \fBstrip dot = no\fR +.TP +\fBsync always (S)\fR +This is a boolean parameter that controls +whether writes will always be written to stable storage before +the write call returns. If this is false then the server will be +guided by the client's request in each write call (clients can +set a bit indicating that a particular write should be synchronous). +If this is true then every write will be followed by a \fBfsync() +\fRcall to ensure the data is written to disk. Note that +the \fIstrict sync\fR parameter must be set to +yes in order for this parameter to have +any affect. + +See also the \fIstrict +sync\fR parameter. + +Default: \fBsync always = no\fR +.TP +\fBsyslog (G)\fR +This parameter maps how Samba debug messages +are logged onto the system syslog logging levels. Samba debug +level zero maps onto syslog LOG_ERR, debug +level one maps onto LOG_WARNING, debug level +two maps onto LOG_NOTICE, debug level three +maps onto LOG_INFO. All higher levels are mapped to LOG_DEBUG. + +This parameter sets the threshold for sending messages +to syslog. Only messages with debug level less than this value +will be sent to syslog. + +Default: \fBsyslog = 1\fR +.TP +\fBsyslog only (G)\fR +If this parameter is set then Samba debug +messages are logged into the system syslog only, and not to +the debug log files. + +Default: \fBsyslog only = no\fR +.TP +\fBtemplate homedir (G)\fR +When filling out the user information for a Windows NT +user, the winbindd(8)daemon +uses this parameter to fill in the home directory for that user. +If the string \fI%D\fR is present it is substituted +with the user's Windows NT domain name. If the string \fI%U +\fRis present it is substituted with the user's Windows +NT user name. + +Default: \fBtemplate homedir = /home/%D/%U\fR +.TP +\fBtemplate shell (G)\fR +When filling out the user information for a Windows NT +user, the winbindd(8)daemon +uses this parameter to fill in the login shell for that user. + +Default: \fBtemplate shell = /bin/false\fR +.TP +\fBtime offset (G)\fR +This parameter is a setting in minutes to add +to the normal GMT to local time conversion. This is useful if +you are serving a lot of PCs that have incorrect daylight +saving time handling. + +Default: \fBtime offset = 0\fR + +Example: \fBtime offset = 60\fR +.TP +\fBtime server (G)\fR +This parameter determines if +nmbd(8)advertises itself as a time server to Windows +clients. + +Default: \fBtime server = no\fR +.TP +\fBtimestamp logs (G)\fR +Synonym for \fI debug timestamp\fR. +.TP +\fBtotal print jobs (G)\fR +This parameter accepts an integer value which defines +a limit on the maximum number of print jobs that will be accepted +system wide at any given time. If a print job is submitted +by a client which will exceed this number, then smbdwill return an +error indicating that no space is available on the server. The +default value of 0 means that no such limit exists. This parameter +can be used to prevent a server from exceeding its capacity and is +designed as a printing throttle. See also +\fImax print jobs\fR. + +Default: \fBtotal print jobs = 0\fR + +Example: \fBtotal print jobs = 5000\fR +.TP +\fBunix password sync (G)\fR +This boolean parameter controls whether Samba +attempts to synchronize the UNIX password with the SMB password +when the encrypted SMB password in the smbpasswd file is changed. +If this is set to true the program specified in the \fIpasswd +program\fRparameter is called \fBAS ROOT\fR - +to allow the new UNIX password to be set without access to the +old UNIX password (as the SMB password change code has no +access to the old password cleartext, only the new). + +See also \fIpasswd +program\fR, \fI passwd chat\fR. + +Default: \fBunix password sync = no\fR +.TP +\fBupdate encrypted (G)\fR +This boolean parameter allows a user logging +on with a plaintext password to have their encrypted (hashed) +password in the smbpasswd file to be updated automatically as +they log on. This option allows a site to migrate from plaintext +password authentication (users authenticate with plaintext +password over the wire, and are checked against a UNIX account +database) to encrypted password authentication (the SMB +challenge/response authentication mechanism) without forcing +all users to re-enter their passwords via smbpasswd at the time the +change is made. This is a convenience option to allow the change over +to encrypted passwords to be made over a longer period. Once all users +have encrypted representations of their passwords in the smbpasswd +file this parameter should be set to no. + +In order for this parameter to work correctly the \fIencrypt passwords\fR +parameter must be set to no when +this parameter is set to yes. + +Note that even when this parameter is set a user +authenticating to \fBsmbd\fR must still enter a valid +password in order to connect correctly, and to update their hashed +(smbpasswd) passwords. + +Default: \fBupdate encrypted = no\fR +.TP +\fBuse client driver (S)\fR +This parameter applies only to Windows NT/2000 +clients. It has no affect on Windows 95/98/ME clients. When +serving a printer to Windows NT/2000 clients without first installing +a valid printer driver on the Samba host, the client will be required +to install a local printer driver. From this point on, the client +will treat the print as a local printer and not a network printer +connection. This is much the same behavior that will occur +when \fBdisable spoolss = yes\fR. + +The differentiating +factor is that under normal circumstances, the NT/2000 client will +attempt to open the network printer using MS-RPC. The problem is that +because the client considers the printer to be local, it will attempt +to issue the OpenPrinterEx() call requesting access rights associated +with the logged on user. If the user possesses local administator rights +but not root privilegde on the Samba host (often the case), the OpenPrinterEx() +call will fail. The result is that the client will now display an "Access +Denied; Unable to connect" message in the printer queue window (even though +jobs may successfully be printed). + +If this parameter is enabled for a printer, then any attempt +to open the printer with the PRINTER_ACCESS_ADMINISTER right is mapped +to PRINTER_ACCESS_USE instead. Thus allowing the OpenPrinterEx() +call to succeed. \fBThis parameter MUST not be able enabled +on a print share which has valid print driver installed on the Samba +server.\fR + +See also disable spoolss + +Default: \fBuse client driver = no\fR +.TP +\fBuse mmap (G)\fR +This global parameter determines if the tdb internals of Samba can +depend on mmap working correctly on the running system. Samba requires a coherent +mmap/read-write system memory cache. Currently only HPUX does not have such a +coherent cache, and so this parameter is set to false by +default on HPUX. On all other systems this parameter should be left alone. This +parameter is provided to help the Samba developers track down problems with +the tdb internal code. + +Default: \fBuse mmap = yes\fR +.TP +\fBuse rhosts (G)\fR +If this global parameter is true, it specifies +that the UNIX user's \fI.rhosts\fR file in their home directory +will be read to find the names of hosts and users who will be allowed +access without specifying a password. + +\fBNOTE:\fR The use of \fIuse rhosts +\fRcan be a major security hole. This is because you are +trusting the PC to supply the correct username. It is very easy to +get a PC to supply a false username. I recommend that the \fI use rhosts\fR option be only used if you really know what +you are doing. + +Default: \fBuse rhosts = no\fR +.TP +\fBuser (S)\fR +Synonym for \fI username\fR. +.TP +\fBusers (S)\fR +Synonym for \fI username\fR. +.TP +\fBusername (S)\fR +Multiple users may be specified in a comma-delimited +list, in which case the supplied password will be tested against +each username in turn (left to right). + +The \fIusername\fR line is needed only when +the PC is unable to supply its own username. This is the case +for the COREPLUS protocol or where your users have different WfWg +usernames to UNIX usernames. In both these cases you may also be +better using the \\\\server\\share%user syntax instead. + +The \fIusername\fR line is not a great +solution in many cases as it means Samba will try to validate +the supplied password against each of the usernames in the +\fIusername\fR line in turn. This is slow and +a bad idea for lots of users in case of duplicate passwords. +You may get timeouts or security breaches using this parameter +unwisely. + +Samba relies on the underlying UNIX security. This +parameter does not restrict who can login, it just offers hints +to the Samba server as to what usernames might correspond to the +supplied password. Users can login as whoever they please and +they will be able to do no more damage than if they started a +telnet session. The daemon runs as the user that they log in as, +so they cannot do anything that user cannot do. + +To restrict a service to a particular set of users you +can use the \fIvalid users +\fRparameter. + +If any of the usernames begin with a '@' then the name +will be looked up first in the NIS netgroups list (if Samba +is compiled with netgroup support), followed by a lookup in +the UNIX groups database and will expand to a list of all users +in the group of that name. + +If any of the usernames begin with a '+' then the name +will be looked up only in the UNIX groups database and will +expand to a list of all users in the group of that name. + +If any of the usernames begin with a '&'then the name +will be looked up only in the NIS netgroups database (if Samba +is compiled with netgroup support) and will expand to a list +of all users in the netgroup group of that name. + +Note that searching though a groups database can take +quite some time, and some clients may time out during the +search. + +See the section NOTE ABOUT +USERNAME/PASSWORD VALIDATION for more information on how +this parameter determines access to the services. + +Default: \fBThe guest account if a guest service, +else <empty string>.\fR + +Examples:\fBusername = fred, mary, jack, jane, +@users, @pcgroup\fR +.TP +\fBusername level (G)\fR +This option helps Samba to try and 'guess' at +the real UNIX username, as many DOS clients send an all-uppercase +username. By default Samba tries all lowercase, followed by the +username with the first letter capitalized, and fails if the +username is not found on the UNIX machine. + +If this parameter is set to non-zero the behavior changes. +This parameter is a number that specifies the number of uppercase +combinations to try while trying to determine the UNIX user name. The +higher the number the more combinations will be tried, but the slower +the discovery of usernames will be. Use this parameter when you have +strange usernames on your UNIX machine, such as AstrangeUser +\&. + +Default: \fBusername level = 0\fR + +Example: \fBusername level = 5\fR +.TP +\fBusername map (G)\fR +This option allows you to specify a file containing +a mapping of usernames from the clients to the server. This can be +used for several purposes. The most common is to map usernames +that users use on DOS or Windows machines to those that the UNIX +box uses. The other is to map multiple users to a single username +so that they can more easily share files. + +The map file is parsed line by line. Each line should +contain a single UNIX username on the left then a '=' followed +by a list of usernames on the right. The list of usernames on the +right may contain names of the form @group in which case they +will match any UNIX username in that group. The special client +name '*' is a wildcard and matches any name. Each line of the +map file may be up to 1023 characters long. + +The file is processed on each line by taking the +supplied username and comparing it with each username on the right +hand side of the '=' signs. If the supplied name matches any of +the names on the right hand side then it is replaced with the name +on the left. Processing then continues with the next line. + +If any line begins with a '#' or a ';' then it is +ignored + +If any line begins with an '!' then the processing +will stop after that line if a mapping was done by the line. +Otherwise mapping continues with every line being processed. +Using '!' is most useful when you have a wildcard mapping line +later in the file. + +For example to map from the name admin +or administrator to the UNIX name root you would use: + +\fBroot = admin administrator\fR + +Or to map anyone in the UNIX group system +to the UNIX name sys you would use: + +\fBsys = @system\fR + +You can have as many mappings as you like in a username +map file. + +If your system supports the NIS NETGROUP option then +the netgroup database is checked before the \fI/etc/group +\fRdatabase for matching groups. + +You can map Windows usernames that have spaces in them +by using double quotes around the name. For example: + +\fBtridge = "Andrew Tridgell"\fR + +would map the windows username "Andrew Tridgell" to the +unix username "tridge". + +The following example would map mary and fred to the +unix user sys, and map the rest to guest. Note the use of the +\&'!' to tell Samba to stop processing if it gets a match on +that line. + +.sp +.nf + !sys = mary fred + guest = * + +.sp +.fi + +Note that the remapping is applied to all occurrences +of usernames. Thus if you connect to \\\\server\\fred and fred is remapped to mary then you +will actually be connecting to \\\\server\\mary and will need to +supply a password suitable for mary not +fred. The only exception to this is the +username passed to the \fI password server\fR (if you have one). The password +server will receive whatever username the client supplies without +modification. + +Also note that no reverse mapping is done. The main effect +this has is with printing. Users who have been mapped may have +trouble deleting print jobs as PrintManager under WfWg will think +they don't own the print job. + +Default: \fBno username map\fR + +Example: \fBusername map = /usr/local/samba/lib/users.map +\fR.TP +\fButmp (G)\fR +This boolean parameter is only available if +Samba has been configured and compiled with the option \fB --with-utmp\fR. If set to true then Samba will attempt +to add utmp or utmpx records (depending on the UNIX system) whenever a +connection is made to a Samba server. Sites may use this to record the +user connecting to a Samba share. + +See also the \fI utmp directory\fR parameter. + +Default: \fButmp = no\fR +.TP +\fButmp directory(G)\fR +This parameter is only available if Samba has +been configured and compiled with the option \fB --with-utmp\fR. It specifies a directory pathname that is +used to store the utmp or utmpx files (depending on the UNIX system) that +record user connections to a Samba server. See also the \fIutmp\fR parameter. By default this is +not set, meaning the system will use whatever utmp file the +native system is set to use (usually +\fI/var/run/utmp\fR on Linux). + +Default: \fBno utmp directory\fR +.TP +\fBvalid chars (G)\fR +The option allows you to specify additional +characters that should be considered valid by the server in +filenames. This is particularly useful for national character +sets, such as adding u-umlaut or a-ring. + +The option takes a list of characters in either integer +or character form with spaces between them. If you give two +characters with a colon between them then it will be taken as +an lowercase:uppercase pair. + +If you have an editor capable of entering the characters +into the config file then it is probably easiest to use this +method. Otherwise you can specify the characters in octal, +decimal or hexadecimal form using the usual C notation. + +For example to add the single character 'Z' to the charset +(which is a pointless thing to do as it's already there) you could +do one of the following + +.sp +.nf + valid chars = Z + valid chars = z:Z + valid chars = 0132:0172 + +.sp +.fi + +The last two examples above actually add two characters, +and alter the uppercase and lowercase mappings appropriately. + +Note that you \fBMUST\fR specify this parameter +after the \fIclient code page\fR parameter if you +have both set. If \fIclient code page\fR is set after +the \fIvalid chars\fR parameter the \fIvalid +chars\fR settings will be overwritten. + +See also the \fIclient +code page\fR parameter. + +Default: \fBSamba defaults to using a reasonable set +of valid characters for English systems\fR + +Example: \fBvalid chars = 0345:0305 0366:0326 0344:0304 +\fR +The above example allows filenames to have the Swedish +characters in them. + +\fBNOTE:\fR It is actually quite difficult to +correctly produce a \fIvalid chars\fR line for +a particular system. To automate the process tino@augsburg.net <URL:mailto:tino@augsburg.net> has written +a package called \fBvalidchars\fR which will automatically +produce a complete \fIvalid chars\fR line for +a given client system. Look in the \fIexamples/validchars/ +\fRsubdirectory of your Samba source code distribution +for this package. +.TP +\fBvalid users (S)\fR +This is a list of users that should be allowed +to login to this service. Names starting with '@', '+' and '&' +are interpreted using the same rules as described in the +\fIinvalid users\fR parameter. + +If this is empty (the default) then any user can login. +If a username is in both this list and the \fIinvalid +users\fR list then access is denied for that user. + +The current servicename is substituted for \fI%S +\fR\&. This is useful in the [homes] section. + +See also \fIinvalid users +\fR +Default: \fBNo valid users list (anyone can login) +\fR +Example: \fBvalid users = greg, @pcusers\fR +.TP +\fBveto files(S)\fR +This is a list of files and directories that +are neither visible nor accessible. Each entry in the list must +be separated by a '/', which allows spaces to be included +in the entry. '*' and '?' can be used to specify multiple files +or directories as in DOS wildcards. + +Each entry must be a unix path, not a DOS path and +must \fBnot\fR include the unix directory +separator '/'. + +Note that the \fIcase sensitive\fR option +is applicable in vetoing files. + +One feature of the veto files parameter that it +is important to be aware of is Samba's behaviour when +trying to delete a directory. If a directory that is +to be deleted contains nothing but veto files this +deletion will \fBfail\fR unless you also set +the \fIdelete veto files\fR parameter to +\fIyes\fR. + +Setting this parameter will affect the performance +of Samba, as it will be forced to check all files and directories +for a match as they are scanned. + +See also \fIhide files +\fRand \fI case sensitive\fR. + +Default: \fBNo files or directories are vetoed. +\fR +Examples: +.sp +.nf +; Veto any files containing the word Security, +; any ending in .tmp, and any directory containing the +; word root. +veto files = /*Security*/*.tmp/*root*/ + +; Veto the Apple specific files that a NetAtalk server +; creates. +veto files = /.AppleDouble/.bin/.AppleDesktop/Network Trash Folder/ +.sp +.fi +.TP +\fBveto oplock files (S)\fR +This parameter is only valid when the \fIoplocks\fR +parameter is turned on for a share. It allows the Samba administrator +to selectively turn off the granting of oplocks on selected files that +match a wildcarded list, similar to the wildcarded list used in the +\fIveto files\fR +parameter. + +Default: \fBNo files are vetoed for oplock +grants\fR + +You might want to do this on files that you know will +be heavily contended for by clients. A good example of this +is in the NetBench SMB benchmark program, which causes heavy +client contention for files ending in \fI.SEM\fR. +To cause Samba not to grant oplocks on these files you would use +the line (either in the [global] section or in the section for +the particular NetBench share : + +Example: \fBveto oplock files = /*.SEM/ +\fR.TP +\fBvfs object (S)\fR +This parameter specifies a shared object file that +is used for Samba VFS I/O operations. By default, normal +disk I/O operations are used but these can be overloaded +with a VFS object. The Samba VFS layer is new to Samba 2.2 and +must be enabled at compile time with --with-vfs. + +Default : \fBno value\fR +.TP +\fBvfs options (S)\fR +This parameter allows parameters to be passed +to the vfs layer at initialization time. The Samba VFS layer +is new to Samba 2.2 and must be enabled at compile time +with --with-vfs. See also \fI vfs object\fR. + +Default : \fBno value\fR +.TP +\fBvolume (S)\fR +This allows you to override the volume label +returned for a share. Useful for CDROMs with installation programs +that insist on a particular volume label. + +Default: \fBthe name of the share\fR +.TP +\fBwide links (S)\fR +This parameter controls whether or not links +in the UNIX file system may be followed by the server. Links +that point to areas within the directory tree exported by the +server are always allowed; this parameter controls access only +to areas that are outside the directory tree being exported. + +Note that setting this parameter can have a negative +effect on your server performance due to the extra system calls +that Samba has to do in order to perform the link checks. + +Default: \fBwide links = yes\fR +.TP +\fBwinbind cache time\fR +This parameter specifies the number of seconds the +winbindd(8)daemon will cache +user and group information before querying a Windows NT server +again. + +Default: \fBwinbind cache type = 15\fR +.TP +\fBwinbind enum users\fR +On large installations using +winbindd(8)it may be +necessary to suppress the enumeration of users through the +\fBsetpwent()\fR, +\fBgetpwent()\fR and +\fBendpwent()\fR group of system calls. If +the \fIwinbind enum users\fR parameter is +false, calls to the \fBgetpwent\fR system call +will not return any data. + +\fBWarning:\fR Turning off user +enumeration may cause some programs to behave oddly. For +example, the finger program relies on having access to the +full user list when searching for matching +usernames. + +Default: \fBwinbind enum users = yes \fR +.TP +\fBwinbind enum groups\fR +On large installations using +winbindd(8)it may be +necessary to suppress the enumeration of groups through the +\fBsetgrent()\fR, +\fBgetgrent()\fR and +\fBendgrent()\fR group of system calls. If +the \fIwinbind enum groups\fR parameter is +false, calls to the \fBgetgrent()\fR system +call will not return any data. + +\fBWarning:\fR Turning off group +enumeration may cause some programs to behave oddly. + +Default: \fBwinbind enum groups = yes \fR +.TP +\fBwinbind gid\fR +The winbind gid parameter specifies the range of group +ids that are allocated by the winbindd(8)daemon. This range of group ids should have no +existing local or NIS groups within it as strange conflicts can +occur otherwise. + +Default: \fBwinbind gid = <empty string> +\fR +Example: \fBwinbind gid = 10000-20000\fR +.TP +\fBwinbind separator\fR +This parameter allows an admin to define the character +used when listing a username of the form of \fIDOMAIN +\fR\\\fIuser\fR. This parameter +is only applicable when using the \fIpam_winbind.so\fR +and \fInss_winbind.so\fR modules for UNIX services. + +Example: \fBwinbind separator = \\\fR + +Example: \fBwinbind separator = +\fR +.TP +\fBwinbind uid\fR +The winbind gid parameter specifies the range of group +ids that are allocated by the winbindd(8)daemon. This range of ids should have no +existing local or NIS users within it as strange conflicts can +occur otherwise. + +Default: \fBwinbind uid = <empty string> +\fR +Example: \fBwinbind uid = 10000-20000\fR +.TP +\fBwins hook (G)\fR +When Samba is running as a WINS server this +allows you to call an external program for all changes to the +WINS database. The primary use for this option is to allow the +dynamic update of external name resolution databases such as +dynamic DNS. + +The wins hook parameter specifies the name of a script +or executable that will be called as follows: + +\fBwins_hook operation name nametype ttl IP_list +\fR.RS +.TP 0.2i +\(bu +The first argument is the operation and is one +of "add", "delete", or "refresh". In most cases the operation can +be ignored as the rest of the parameters provide sufficient +information. Note that "refresh" may sometimes be called when the +name has not previously been added, in that case it should be treated +as an add. +.TP 0.2i +\(bu +The second argument is the NetBIOS name. If the +name is not a legal name then the wins hook is not called. +Legal names contain only letters, digits, hyphens, underscores +and periods. +.TP 0.2i +\(bu +The third argument is the NetBIOS name +type as a 2 digit hexadecimal number. +.TP 0.2i +\(bu +The fourth argument is the TTL (time to live) +for the name in seconds. +.TP 0.2i +\(bu +The fifth and subsequent arguments are the IP +addresses currently registered for that name. If this list is +empty then the name should be deleted. .RE - +.PP +An example script that calls the BIND dynamic DNS update +program \fBnsupdate\fR is provided in the examples +directory of the Samba source code. +.PP +.TP +\fBwins proxy (G)\fR +This is a boolean that controls if nmbd(8)will respond to broadcast name +queries on behalf of other hosts. You may need to set this +to yes for some older clients. + +Default: \fBwins proxy = no\fR +.TP +\fBwins server (G)\fR +This specifies the IP address (or DNS name: IP +address for preference) of the WINS server that nmbd(8)should register with. If you have a WINS server on +your network then you should set this to the WINS server's IP. + +You should point this at your WINS server if you have a +multi-subnetted network. + +\fBNOTE\fR. You need to set up Samba to point +to a WINS server if you have multiple subnets and wish cross-subnet +browsing to work correctly. + +See the documentation file \fIBROWSING.txt\fR +in the docs/ directory of your Samba source distribution. + +Default: \fBnot enabled\fR + +Example: \fBwins server = 192.9.200.1\fR +.TP +\fBwins support (G)\fR +This boolean controls if the +nmbd(8)process in Samba will act as a WINS server. You should +not set this to true unless you have a multi-subnetted network and +you wish a particular \fBnmbd\fR to be your WINS server. +Note that you should \fBNEVER\fR set this to true +on more than one machine in your network. + +Default: \fBwins support = no\fR +.TP +\fBworkgroup (G)\fR +This controls what workgroup your server will +appear to be in when queried by clients. Note that this parameter +also controls the Domain name used with the \fBsecurity = domain\fR +setting. + +Default: \fBset at compile time to WORKGROUP\fR + +Example: \fBworkgroup = MYGROUP\fR +.TP +\fBwritable (S)\fR +Synonym for \fI writeable\fR for people who can't spell :-). +.TP +\fBwrite cache size (S)\fR +If this integer parameter is set to non-zero value, +Samba will create an in-memory cache for each oplocked file +(it does \fBnot\fR do this for +non-oplocked files). All writes that the client does not request +to be flushed directly to disk will be stored in this cache if possible. +The cache is flushed onto disk when a write comes in whose offset +would not fit into the cache or when the file is closed by the client. +Reads for the file are also served from this cache if the data is stored +within it. + +This cache allows Samba to batch client writes into a more +efficient write size for RAID disks (i.e. writes may be tuned to +be the RAID stripe size) and can improve performance on systems +where the disk subsystem is a bottleneck but there is free +memory for userspace programs. + +The integer parameter specifies the size of this cache +(per oplocked file) in bytes. + +Default: \fBwrite cache size = 0\fR + +Example: \fBwrite cache size = 262144\fR + +for a 256k cache size per file. +.TP +\fBwrite list (S)\fR +This is a list of users that are given read-write +access to a service. If the connecting user is in this list then +they will be given write access, no matter what the \fIwriteable\fR +option is set to. The list can include group names using the +@group syntax. + +Note that if a user is in both the read list and the +write list then they will be given write access. + +See also the \fIread list +\fRoption. + +Default: \fBwrite list = <empty string> +\fR +Example: \fBwrite list = admin, root, @staff +\fR.TP +\fBwrite ok (S)\fR +Synonym for \fI writeable\fR. +.TP +\fBwrite raw (G)\fR +This parameter controls whether or not the server +will support raw write SMB's when transferring data from clients. +You should never need to change this parameter. + +Default: \fBwrite raw = yes\fR +.TP +\fBwriteable (S)\fR +An inverted synonym is \fIread only\fR. + +If this parameter is no, then users +of a service may not create or modify files in the service's +directory. + +Note that a printable service (\fBprintable = yes\fR) +will \fBALWAYS\fR allow writing to the directory +(user privileges permitting), but only via spooling operations. + +Default: \fBwriteable = no\fR +.SH "WARNINGS" +.PP +Although the configuration file permits service names +to contain spaces, your client software may not. Spaces will +be ignored in comparisons anyway, so it shouldn't be a +problem - but be aware of the possibility. +.PP +On a similar note, many clients - especially DOS clients - +limit service names to eight characters. smbd(8) +has no such limitation, but attempts to connect from such +clients will fail if they truncate the service names. For this reason +you should probably keep your service names down to eight characters +in length. +.PP +Use of the [homes] and [printers] special sections make life +for an administrator easy, but the various combinations of default +attributes can be tricky. Take extreme care when designing these +sections. In particular, ensure that the permissions on spool +directories are correct. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +samba(7), +\fBsmbpasswd(8)\fR, +\fBswat(8)\fR, +\fBsmbd(8)\fR, +\fBnmbd(8)\fR, +\fBsmbclient(1)\fR, +\fBnmblookup(1)\fR, +\fBtestparm(1)\fR, +\fBtestprns(1)\fR +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbcacls.1 b/docs/manpages/smbcacls.1 new file mode 100644 index 00000000000..d2da694a263 --- /dev/null +++ b/docs/manpages/smbcacls.1 @@ -0,0 +1,191 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBCACLS" "1" "06 December 2001" "" "" +.SH NAME +smbcacls \- Set or get ACLs on an NT file or directory names +.SH SYNOPSIS +.sp +\fBsmbcacls\fR \fB//server/share\fR \fBfilename\fR [ \fB-U username\fR ] [ \fB-A acls\fR ] [ \fB-M acls\fR ] [ \fB-D acls\fR ] [ \fB-S acls\fR ] [ \fB-C name\fR ] [ \fB-G name\fR ] [ \fB-n\fR ] [ \fB-h\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +The \fBsmbcacls\fR program manipulates NT Access Control Lists +(ACLs) on SMB file shares. +.SH "OPTIONS" +.PP +The following options are available to the \fBsmbcacls\fR program. +The format of ACLs is described in the section ACL FORMAT +.TP +\fB-A acls\fR +Add the ACLs specified to the ACL list. Existing +access control entries are unchanged. +.TP +\fB-M acls\fR +Modify the mask value (permissions) for the ACLs +specified on the command line. An error will be printed for each +ACL specified that was not already present in the ACL list +.TP +\fB-D acls\fR +Delete any ACLs specified on the command line. +An error will be printed for each ACL specified that was not +already present in the ACL list. +.TP +\fB-S acls\fR +This command sets the ACLs on the file with +only the ones specified on the command line. All other ACLs are +erased. Note that the ACL specified must contain at least a revision, +type, owner and group for the call to succeed. +.TP +\fB-U username\fR +Specifies a username used to connect to the +specified service. The username may be of the form "username" in +which case the user is prompted to enter in a password and the +workgroup specified in the \fIsmb.conf\fR file is +used, or "username%password" or "DOMAIN\\username%password" and the +password and workgroup names are used as provided. +.TP +\fB-C name\fR +The owner of a file or directory can be changed +to the name given using the \fI-C\fR option. +The name can be a sid in the form S-1-x-y-z or a name resolved +against the server specified in the first argument. + +This command is a shortcut for -M OWNER:name. +.TP +\fB-G name\fR +The group owner of a file or directory can +be changed to the name given using the \fI-G\fR +option. The name can be a sid in the form S-1-x-y-z or a name +resolved against the server specified n the first argument. + +This command is a shortcut for -M GROUP:name. +.TP +\fB-n\fR +This option displays all ACL information in numeric +format. The default is to convert SIDs to names and ACE types +and masks to a readable string format. +.TP +\fB-h\fR +Print usage information on the \fBsmbcacls +\fRprogram. +.SH "ACL FORMAT" +.PP +The format of an ACL is one or more ACL entries separated by +either commas or newlines. An ACL entry is one of the following: +.PP +.sp +.nf + +REVISION:<revision number> +OWNER:<sid or name> +GROUP:<sid or name> +ACL:<sid or name>:<type>/<flags>/<mask> + +.sp +.fi +.PP +The revision of the ACL specifies the internal Windows +NT ACL revision for the security descriptor. +If not specified it defaults to 1. Using values other than 1 may +cause strange behaviour. +.PP +The owner and group specify the owner and group sids for the +object. If a SID in the format CWS-1-x-y-z is specified this is used, +otherwise the name specified is resolved using the server on which +the file or directory resides. +.PP +ACLs specify permissions granted to the SID. This SID again +can be specified in CWS-1-x-y-z format or as a name in which case +it is resolved against the server on which the file or directory +resides. The type, flags and mask values determine the type of +access granted to the SID. +.PP +The type can be either 0 or 1 corresponding to ALLOWED or +DENIED access to the SID. The flags values are generally +zero for file ACLs and either 9 or 2 for directory ACLs. Some +common flags are: +.TP 0.2i +\(bu +#define SEC_ACE_FLAG_OBJECT_INHERIT 0x1 +.TP 0.2i +\(bu +#define SEC_ACE_FLAG_CONTAINER_INHERIT 0x2 +.TP 0.2i +\(bu +#define SEC_ACE_FLAG_NO_PROPAGATE_INHERIT 0x4 +.TP 0.2i +\(bu +#define SEC_ACE_FLAG_INHERIT_ONLY 0x8 +.PP +At present flags can only be specified as decimal or +hexadecimal values. +.PP +.PP +The mask is a value which expresses the access right +granted to the SID. It can be given as a decimal or hexadecimal value, +or by using one of the following text strings which map to the NT +file permissions of the same name. +.PP +.TP 0.2i +\(bu +\fBR\fR - Allow read access +.TP 0.2i +\(bu +\fBW\fR - Allow write access +.TP 0.2i +\(bu +\fBX\fR - Execute permission on the object +.TP 0.2i +\(bu +\fBD\fR - Delete the object +.TP 0.2i +\(bu +\fBP\fR - Change permissions +.TP 0.2i +\(bu +\fBO\fR - Take ownership +.PP +The following combined permissions can be specified: +.PP +.TP 0.2i +\(bu +\fBREAD\fR - Equivalent to 'RX' +permissions +.TP 0.2i +\(bu +\fBCHANGE\fR - Equivalent to 'RXWD' permissions +.TP 0.2i +\(bu +\fBFULL\fR - Equivalent to 'RWXDPO' +permissions +.SH "EXIT STATUS" +.PP +The \fBsmbcacls\fR program sets the exit status +depending on the success or otherwise of the operations performed. +The exit status may be one of the following values. +.PP +If the operation succeeded, smbcacls returns and exit +status of 0. If \fBsmbcacls\fR couldn't connect to the specified server, +or there was an error getting or setting the ACLs, an exit status +of 1 is returned. If there was an error parsing any command line +arguments, an exit status of 2 is returned. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +\fBsmbcacls\fR was written by Andrew Tridgell +and Tim Potter. +.PP +The conversion to DocBook for Samba 2.2 was done +by Gerald Carter diff --git a/docs/manpages/smbclient.1 b/docs/manpages/smbclient.1 index 5590e01296e..4c5ef0b3e4b 100644 --- a/docs/manpages/smbclient.1 +++ b/docs/manpages/smbclient.1 @@ -1,1133 +1,777 @@ -.TH SMBCLIENT 1 17/1/1995 smbclient smbclient +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBCLIENT" "1" "06 December 2001" "" "" .SH NAME -smbclient \- ftp-like Lan Manager client program +smbclient \- ftp-like client to access SMB/CIFS resources on servers .SH SYNOPSIS -.B smbclient -.B servicename -[ -.B password -] [ -.B -A -] [ -.B -E -] [ -.B -L -.I host -] [ -.B -M -.I host -] [ -.B -I -.I IP number -] [ -.B -N -] [ -.B -P -] [ -.B -U -.I username -] [ -.B -d -.I debuglevel -] [ -.B -l -.I log basename -] [ -.B -n -.I netbios name -] [ -.B -O -.I socket options -] [ -.B -p -.I port number -.B -T -.I tar options -.B -D -.I initial directory -] -.SH DESCRIPTION -This program is part of the Samba suite. - -.B smbclient -is a client that can 'talk' to a Lan Manager server. It offers -an interface similar to that of the -.B ftp -program (see -.B ftp(1)). Operations include things like getting files from the -server to the local machine, putting files from the local machine to -the server, retrieving directory information from the server and so on. - -.SH OPTIONS -.B servicename -.RS 3 -.B servicename -is the name of the service you want to use on the server. A service -name takes the form -.B "\\\\\\\\server\\\\service" -where -.B server -is the netbios name of the Lan Manager server offering the desired service and -.B service -is the name of the service offered. Thus to connect to the service "printer" -on the Lan Manager server "lanman", you would use the servicename - -.RS 10 -.B "\\\\\\\\lanman\\\\printer" -.RE - -Note that the server name required is NOT necessarily the host name of the -server! The name required is a Lan Manager server name, which may or may not -be the same as the hostname of the machine running the server. -.RE - -.B password -.RS 3 -.B -password -is the password required to access the specified service on the -specified server. If supplied, the -.B -N -option (suppress password prompt) is assumed. - -There is no default password. If no password is supplied on the command line -(either here or using the -.B -U -option (see below)) and -.B -N -is not specified, the client will prompt for a password, even if the desired -service does not require one. (If prompted for a password and none is +.sp +\fBsmbclient\fR \fBservicename\fR [ \fBpassword\fR ] [ \fB-b <buffer size>\fR ] [ \fB-d debuglevel\fR ] [ \fB-D Directory\fR ] [ \fB-U username\fR ] [ \fB-W workgroup\fR ] [ \fB-M <netbios name>\fR ] [ \fB-m maxprotocol\fR ] [ \fB-A authfile\fR ] [ \fB-N\fR ] [ \fB-l logfile\fR ] [ \fB-L <netbios name>\fR ] [ \fB-I destinationIP\fR ] [ \fB-E <terminal code>\fR ] [ \fB-c <command string>\fR ] [ \fB-i scope\fR ] [ \fB-O <socket options>\fR ] [ \fB-p port\fR ] [ \fB-R <name resolve order>\fR ] [ \fB-s <smb config file>\fR ] [ \fB-T<c|x>IXFqgbNan\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBsmbclient\fR is a client that can +\&'talk' to an SMB/CIFS server. It offers an interface +similar to that of the ftp program (see \fBftp(1)\fR). +Operations include things like getting files from the server +to the local machine, putting files from the local machine to +the server, retrieving directory information from the server +and so on. +.SH "OPTIONS" +.TP +\fBservicename\fR +servicename is the name of the service +you want to use on the server. A service name takes the form +\fI//server/service\fR where \fIserver +\fRis the NetBIOS name of the SMB/CIFS server +offering the desired service and \fIservice\fR +is the name of the service offered. Thus to connect to +the service "printer" on the SMB/CIFS server "smbserver", +you would use the servicename \fI//smbserver/printer +\fR +Note that the server name required is NOT necessarily +the IP (DNS) host name of the server ! The name required is +a NetBIOS server name, which may or may not be the +same as the IP hostname of the machine running the server. + +The server name is looked up according to either +the \fI-R\fR parameter to \fBsmbclient\fR or +using the name resolve order parameter in the \fIsmb.conf\fR file, +allowing an administrator to change the order and methods +by which server names are looked up. +.TP +\fBpassword\fR +The password required to access the specified +service on the specified server. If this parameter is +supplied, the \fI-N\fR option (suppress +password prompt) is assumed. + +There is no default password. If no password is supplied +on the command line (either by using this parameter or adding +a password to the \fI-U\fR option (see +below)) and the \fI-N\fR option is not +specified, the client will prompt for a password, even if +the desired service does not require one. (If no password is required, simply press ENTER to provide a null password.) -Note: Some servers (including OS/2 and Windows for Workgroups) insist -on an uppercase password. Lowercase or mixed case passwords may be -rejected by these servers. +Note: Some servers (including OS/2 and Windows for +Workgroups) insist on an uppercase password. Lowercase +or mixed case passwords may be rejected by these servers. Be cautious about including passwords in scripts. -.RE - -.B -A - -.RS 3 -This parameter, if specified, causes the maximum debug level to be selected. -Be warned that this generates prodigious amounts of debug data. There is also -a security issue involved, as at the maximum debug level cleartext passwords -may be written to some log files. -.RE - -.B -L - -.RS 3 -This option allows you to look at what services are available on a -server. You use it as "smbclient -L host" and a list should appear. -The -I option may be useful if your netbios names don't match your -tcp/ip host names or if you are trying to reach a host on another -network. For example: - -smbclient -L ftp -I ftp.microsoft.com - -will list the shares available on microsofts public server. -.RE - -.B -M - -.RS 3 -This options allows you to send messages, using the "WinPopup" -protocol, to another computer. Once a connection is established you -then type your message, pressing ^D (control-D) to end. - -If the receiving computer is running WinPopup the user will receive -the message and probably a beep. If they are not running WinPopup the -message will be lost, and no error message will occur. - -The message is also automatically truncated if the message is over -1600 bytes, as this is the limit of the protocol. - -One useful trick is to cat the message through smbclient. For example: - -cat mymessage.txt | smbclient -M FRED - -will send the message in the file "mymessage.txt" to the machine FRED. - -You may also find the -U and -I options useful, as they allow you to +.TP +\fB-s smb.conf\fR +Specifies the location of the all important +\fIsmb.conf\fR file. +.TP +\fB-O socket options\fR +TCP socket options to set on the client +socket. See the socket options parameter in the \fI smb.conf (5)\fR manpage for the list of valid +options. +.TP +\fB-R <name resolve order>\fR +This option is used by the programs in the Samba +suite to determine what naming services and in what order to resolve +host names to IP addresses. The option takes a space-separated +string of different name resolution options. + +The options are :"lmhosts", "host", "wins" and "bcast". They +cause names to be resolved as follows : +.RS +.TP 0.2i +\(bu +lmhosts : Lookup an IP +address in the Samba lmhosts file. If the line in lmhosts has +no name type attached to the NetBIOS name (see the lmhosts(5)for details) then +any name type matches for lookup. +.TP 0.2i +\(bu +host : Do a standard host +name to IP address resolution, using the system \fI/etc/hosts +\fR, NIS, or DNS lookups. This method of name resolution +is operating system dependent, for instance on IRIX or Solaris this +may be controlled by the \fI/etc/nsswitch.conf\fR +file). Note that this method is only used if the NetBIOS name +type being queried is the 0x20 (server) name type, otherwise +it is ignored. +.TP 0.2i +\(bu +wins : Query a name with +the IP address listed in the \fIwins server\fR +parameter. If no WINS server has +been specified this method will be ignored. +.TP 0.2i +\(bu +bcast : Do a broadcast on +each of the known local interfaces listed in the +\fIinterfaces\fR +parameter. This is the least reliable of the name resolution +methods as it depends on the target host being on a locally +connected subnet. +.RE +.PP +If this parameter is not set then the name resolve order +defined in the \fIsmb.conf\fR file parameter +(name resolve order) will be used. +.PP +.PP +The default order is lmhosts, host, wins, bcast and without +this parameter or any entry in the \fIname resolve order +\fRparameter of the \fIsmb.conf\fR file the name resolution +methods will be attempted in this order. +.PP +.TP +\fB-M NetBIOS name\fR +This options allows you to send messages, using +the "WinPopup" protocol, to another computer. Once a connection is +established you then type your message, pressing ^D (control-D) to +end. + +If the receiving computer is running WinPopup the user will +receive the message and probably a beep. If they are not running +WinPopup the message will be lost, and no error message will +occur. + +The message is also automatically truncated if the message +is over 1600 bytes, as this is the limit of the protocol. + +One useful trick is to cat the message through +\fBsmbclient\fR. For example: \fB cat mymessage.txt | smbclient -M FRED \fR will +send the message in the file \fImymessage.txt\fR +to the machine FRED. + +You may also find the \fI-U\fR and +\fI-I\fR options useful, as they allow you to control the FROM and TO parts of the message. -Samba currently has no way of receiving WinPopup messages. - -Note: Copy WinPopup into the startup group on your WfWg PCs if you -want them to always be able to receive messages. -.RE - -.B -E - -.RS 3 -This parameter, if specified, causes the client to write messages to the -standard error stream (stderr) rather than to the standard output stream. - -By default, the client writes messages to standard output - typically the -user's tty. -.RE - -.B -I -.I IP number - -.RS 3 -.I IP number -represents the IP number of the server to connect to. It should -be specified in standard "a.b.c.d" notation. - -Normally the client will attempt to locate the specified Lan Manager server -by looking it up - that is, broadcasting a request for the given server to -identify itself. Using this parameter will force the client to assume that -the server is on the machine with the specified IP number. - -There is no default for this parameter. If not supplied, it will be determined -automatically by the client as described above. -.RE - -.B -N - -.RS 3 -If specified, this parameter suppresses the normal password prompt from the -client to the user. This is useful when accessing a service that does not -require a password. - -Unless a password is specified on the command line or this parameter is -specified, the client will request a password. -.RE - -.B -O -.I socket options -.RS 3 - -See the socket options section of smb.conf(5) for details - -.RE -.B -P - -.RS 3 -If specified, the service requested will be connected to as a printer service -rather than as a normal filespace service. Operations such as put and get -will not be applicable for such a connection. - -By default, services will be connected to as NON-printer services. -.RE - -.B -U -.I username - -.RS 3 -.I username -is the user name that will be used by the client to make a connection, -assuming your server is running a protocol that allows for usernames. - -Some servers are fussy about the case of this name, and some insist -that it must be a valid netbios name. - -If no -.I username -is supplied, it will default to an uppercase version of the -environment variable -.B USER -or -.B LOGNAME -in that order. -If no -.I username -is supplied and neither environment variable exists the user name will -be empty. - -If the service you are connecting to requires a password, it can be supplied -using the -.B -U -option, by appending a percent symbol ("%") then the password to -.I username. -For example, to attach to a service as user "fred" with password "secret", you -would specify -.B -U -.I fred%secret -on the command line. Note that there are no spaces around the percent symbol. - -If you specify the password as part of -.I username -then the -.B -N -option (suppress password prompt) is assumed. - -If you specify the password as a parameter AND as part of -.I username -then the password as part of -.I username -will take precedence. Putting nothing before or nothing after the percent -symbol will cause an empty username or an empty password to be used, -respectively. - -Note: Some servers (including OS/2 and Windows for Workgroups) insist -on an uppercase password. Lowercase or mixed case passwords may be -rejected by these servers. - -Be cautious about including passwords in scripts. -.RE - -.B -d -.I debuglevel -.RS 3 - -debuglevel is an integer from 0 to 5. - -The default value if this parameter is not specified is zero. - -The higher this value, the more detail will be logged to the log files about -the activities of the client. At level 0, only critical errors and serious -warnings will be logged. Level 1 is a reasonable level for day to day running -- it generates a small amount of information about operations carried out. - -Levels above 1 will generate considerable amounts of log data, and should -only be used when investigating a problem. Levels above 3 are designed for -use only by developers and generate HUGE amounts of log data, most of which -is extremely cryptic. -.RE - -.B -l -.I log basename - -.RS 3 -If specified, -.I log basename -specifies a base filename into which operational data from the running client -will be logged. +See the message command parameter in the \fI smb.conf(5)\fR for a description of how to handle incoming +WinPopup messages in Samba. + +\fBNote\fR: Copy WinPopup into the startup group +on your WfWg PCs if you want them to always be able to receive +messages. +.TP +\fB-i scope\fR +This specifies a NetBIOS scope that smbclient will +use to communicate with when generating NetBIOS names. For details +on the use of NetBIOS scopes, see \fIrfc1001.txt\fR +and \fIrfc1002.txt\fR. +NetBIOS scopes are \fBvery\fR rarely used, only set +this parameter if you are the system administrator in charge of all +the NetBIOS systems you communicate with. +.TP +\fB-N\fR +If specified, this parameter suppresses the normal +password prompt from the client to the user. This is useful when +accessing a service that does not require a password. + +Unless a password is specified on the command line or +this parameter is specified, the client will request a +password. +.TP +\fB-n NetBIOS name\fR +By default, the client will use the local +machine's hostname (in uppercase) as its NetBIOS name. This parameter +allows you to override the host name and use whatever NetBIOS +name you wish. +.TP +\fB-d debuglevel\fR +\fIdebuglevel\fR is an integer from 0 to 10, or +the letter 'A'. + +The default value if this parameter is not specified +is zero. + +The higher this value, the more detail will be logged to +the log files about the activities of the +client. At level 0, only critical errors and serious warnings will +be logged. Level 1 is a reasonable level for day to day running - +it generates a small amount of information about operations +carried out. + +Levels above 1 will generate considerable amounts of log +data, and should only be used when investigating a problem. +Levels above 3 are designed for use only by developers and +generate HUGE amounts of log data, most of which is extremely +cryptic. If \fIdebuglevel\fR is set to the letter 'A', then \fBall +\fRdebug messages will be printed. This setting +is for developers only (and people who \fBreally\fR want +to know how the code works internally). + +Note that specifying this parameter here will override +the log level parameter in the \fIsmb.conf (5)\fR +file. +.TP +\fB-p port\fR +This number is the TCP port number that will be used +when making connections to the server. The standard (well-known) +TCP port number for an SMB/CIFS server is 139, which is the +default. +.TP +\fB-l logfilename\fR +If specified, \fIlogfilename\fR specifies a base filename +into which operational data from the running client will be +logged. The default base name is specified at compile time. -The base name is used to generate actual log file names. For example, if the -name specified was "log", the following files would be used for log data: - -.RS 3 -log.client.debug (containing debugging information) - -log.client.in (containing inbound transaction data) - -log.client.out (containing outbound transaction data) -.RE - -The log files generated are never removed by the client. -.RE -.RE - -.B -n -.I netbios name - -.RS 3 -By default, the client will use the local machine's hostname (in -uppercase) as its netbios name. This parameter allows you to override -the host name and use whatever netbios name you wish. -.RE - -.B -p -.I port number -.RS 3 - -port number is a positive integer value. - -The default value if this parameter is not specified is 139. - -This number is the port number that will be used when making connections to -the server. The standard (well-known) port number for the server is 139, -hence the default. - -This parameter is not normally specified. - -.B -T -.I tar options -.RS3 - -where tar options are one or more of c,x,I,X,b,g,N or a; used as: -.LP -smbclient -.B "\\\\\\\\server\\\\share" -\-TcxIXbgNa -[ -.IR blocksize -] -[ -.IR newer-file -] -.IR tarfile -[ -.IR filenames.... -] - -.RS3 -.B c -Create a tar file on UNIX. Must be followed by the name of a tar file, -tape device or "-" for standard output. (May be useful to set debugging -low (-d0)) to avoid corrupting your tar file if using "-"). Mutually -exclusive with the x flag. - -.B x -Extract (restore) a local tar file back to a share. Unless the -D -option is given, the tar files will be restored from the top level of -the share. Must be followed by the name of the tar file, device or "-" -for standard input. Mutually exclusive with the c flag. - -.B I -Include files and directories. Is the default behaviour when -.IR filenames -are specified above. Causes tar files to be included in an extract or create -(and therefore everything else to be excluded). See example below. -Filename globbing does not work for included files for extractions (yet). - -.B X -Exclude files and directories. Causes tar files to be excluded from -an extract or create. See example below. -Filename globbing does not work for excluded files (yet). - -.B b -Blocksize. Must be followed by a valid (greater than zero) blocksize. -Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte) -blocks. - -.B g -Incremental. Only back up files that have the archive bit set. Useful -only with the c flag. - -.B N -Newer than. Must be followed by the name of a file whose date is -compared against files found on the share during a create. Only files -newer than the file specified are backed up to the tar file. Useful -only with the c flag. - -.B a -Set archive bit. Causes the archive bit to be reset when a file is backed -up. Useful with the g (and c) flags. -.LP - -.B Examples - -smbclient \\\\mypc\\myshare "" -N -Tx backup.tar - -Restore from tar file backup.tar into myshare on mypc (no password on share). - -smbclient \\\\mypc\\myshare "" -N -TXx backup.tar users/docs - -Restore everything except users/docs - -smbclient \\\\mypc\\myshare "" -N -Tc backup.tar users/docs - -Create a tar file of the files beneath users/docs. - -.RE - -.B -D -.I initial directory - -.RS3 - -Change to initial directory before starting. Probably only of any use -with the tar (\-T) option. - - -.RE - -.SH OPERATIONS -Once the client is running, the user is presented with a prompt, "smb: \\>". -The backslash ("\\") indicates the current working directory on the server, -and will change if the current working directory is changed. - -The prompt indicates that the client is ready and waiting to carry out a user -command. Each command is a single word, optionally followed by parameters -specific to that command. Command and parameters are space-delimited unless -these notes specifically state otherwise. All commands are case-insensitive. -Parameters to commands may or may not be case sensitive, depending on the -command. - -You can specify file names which have spaces in them by quoting the -name with double quotes, for example "a long file name". - -Parameters shown in square brackets (eg., "[parameter]") are optional. If not -given, the command will use suitable defaults. Parameters shown in angle -brackets (eg., "<parameter>") are required. - -Note that all commands operating on the server are actually performed by -issuing a request to the server. Thus the behaviour may vary from server to -server, depending on how the server was implemented. - -The commands available are given here in alphabetical order. - -.B ? -.RS 3 -.B Parameters: -.RS 3 -.I [command] - -.RE -.B Description: -.RS 3 -If -.I command -is specified, the -.B ? -command will display a brief informative message about the specified command. - -If no command is specified, a list of available commands will be displayed. -.RE -.RE - -.B ! -.RS 3 -.B Parameters: -.RS 3 -.I [shell command] - -.RE -.B Description: -.RS 3 -If -.I shell command -is specified, the -.B ! -command will execute a shell locally and run the specified shell command. If -no command is specified, a shell will be run. -.RE -.RE - -.B cd -.RS 3 -.B Parameters: -.RS 3 -.I [directory name] - -.RE -.B Description: -.RS 3 -If -.I directory name -is specified, the current working directory -.B on the server -will be changed to the directory specified. This operation will fail if for -any reason the specified directory is inaccessible. - -If no directory name is specified, the current working directory -.B on the server -will be reported. -.RE -.RE - -.B del -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -The client will request that the server attempt to delete all files matching -.I mask -from the current working directory -.B on the server. -.RE -.RE - -.B dir -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -A list of the files matching -.I mask -in the current working directory -.B on the server -will be retrieved from the server and displayed. -.RE -.RE - -.B exit -.RS 3 -.B Parameters: -.RS 3 -None. - -.RE -.B Description: -.RS 3 -Terminate the connection with the server and exit from the program. -.RE -.RE - -.B get -.RS 3 -.B Parameters: -.RS 3 -.I <remote file name> [local file name] - -.RE -.B Description: -.RS 3 -Copy the file called -.I remote file name -from the server to the machine running the client. If specified, name the -local copy -.I local file name. -Note that all transfers in smbclient are binary. See also the -.B lowercase -command. -.RE -.RE - -.B help -.RS 3 -.B Parameters: -.RS 3 -.I [command] - -.RE -.B Description: -.RS 3 -See the -.B ? -command above. -.RE -.RE - -.B lcd -.RS 3 -.B Parameters: -.RS 3 -.I [directory name] - -.RE -.B Description: -.RS 3 -If -.I directory name -is specified, the current working directory -.B on the local machine -will be changed to the directory specified. This operation will fail if for -any reason the specified directory is inaccessible. - -If no directory name is specified, the name of the current working directory -.B on the local machine -will be reported. -.RE -.RE - -.B lowercase -.RS 3 -.B Parameters: -.RS 3 -None. - -.RE -.B Description: -.RS 3 -Toggle lowercasing of filenames for the -.B get -and -.B mget -commands. - -When lowercasing is toggled ON, local filenames are converted to lowercase -when using the -.B get -and -.B mget -commands. This is often useful when copying (say) MSDOS files from a server, -because lowercase filenames are the norm on Unix systems. -.RE -.RE - -.B ls -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -See the -.B dir -command above. -.RE -.RE - -.B mask -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -This command allows the user to set up a mask which will be used during -recursive operation of the -.B mget -and -.B mput -commands. - -The masks specified to the -.B mget -and -.B mput -commands act as filters for directories -rather than files when recursion is toggled ON. - -The mask specified with the -.B mask -command is necessary to filter files within those directories. For example, -if the mask specified in an -.B mget -command is "source*" -.I and -the mask specified with the -.B mask -command is "*.c" -.I and -recursion is toggled ON, the -.B mget -command will retrieve all files matching "*.c" in all directories below -and including all directories matching "source*" in the current working -directory. - -Note that the value for -.I mask -defaults to blank (equivalent to "*") and remains so until the -.B mask -command is used to change it. It retains the most recently specified value -indefinitely. To avoid unexpected results it would be wise to change the -value of -.I mask -back to "*" after using the -.B mget -or -.B mput -commands. -.RE -.RE - -.B md -.RS 3 -.B Parameters: -.RS 3 -.I <directory name> - -.RE -.B Description: -.RS 3 -See the -.B mkdir -command. -.RE -.RE - -.B mget -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -Copy all files matching -.I mask -from the server to the machine running the client. - -Note that -.I mask -is interpreted differently during recursive operation and non-recursive -operation - refer to the -.B recurse -and -.B mask -commands for more information. Note that all transfers in smbclient are -binary. See also the -.B lowercase -command. -.RE -.RE - -.B mkdir -.RS 3 -.B Parameters: -.RS 3 -.I <directory name> - -.RE -.B Description: -.RS 3 -Create a new directory -.B on the server -(user access privileges permitting) with the specified name. -.RE -.RE - -.B mput -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -Copy all files matching -.I mask -in the current working directory -.B on the local machine -to the current working directory on the server. - -Note that -.I mask -is interpreted differently during recursive operation and non-recursive -operation - refer to the -.B recurse -and -.B mask -commands for more information. Note that all transfers in smbclient are -binary. -.RE -.RE - -.B print -.RS 3 -.B Parameters: -.RS 3 -.I <file name> - -.RE -.B Description: -.RS 3 -Print the specified file -.B from the local machine -through a printable service on the server. - -See also the -.B printmode -command. -.RE -.RE - -.B printmode -.RS 3 -.B Parameters: -.RS 3 -.I <graphics or text> - -.RE -.B Description: -.RS 3 -Set the print mode to suit either binary data (such as graphical information) -or text. Subsequent -.B print -commands will use the currently set print mode. -.RE -.RE - -.B prompt -.RS 3 -.B Parameters: -.RS 3 -None. - -.RE -.B Description: -.RS 3 -Toggle prompting for filenames during operation of the -.B mget -and -.B mput -commands. - -When toggled ON, the user will be prompted to confirm the transfer of each -file during these commands. When toggled OFF, all specified files will be -transferred without prompting. -.RE -.RE - -.B put -.RS 3 -.B Parameters: -.RS 3 -.I <local file name> [remote file name] - -.RE -.B Description: -.RS 3 -Copy the file called -.I local file name -from the machine running the client to the server. If specified, name the -remote copy -.I remote file name. -Note that all transfers in smbclient are binary. See also the -.B lowercase -command. -.RE -.RE - -.B queue -.RS 3 -.B Parameters: -.RS 3 -None. - -.RE -.B Description: -.RS 3 -Displays the print queue, showing the job id, name, size and current status. -.RE -.RE - -.B quit -.RS 3 -.B Parameters: -.RS 3 -None. - -.RE -.B Description: -.RS 3 -See the -.B exit -command. -.RE -.RE - -.B rd -.RS 3 -.B Parameters: -.RS 3 -.I <directory name> - -.RE -.B Description: -.RS 3 -See the -.B rmdir -command. -.RE -.RE - -.B recurse -.RS 3 -.B Parameters: -.RS 3 -None. - -.RE -.B Description: -.RS 3 -Toggle directory recursion for the commands -.B mget -and -.B mput -. - -When toggled ON, these commands will process all directories in the source -directory (ie., the directory they are copying -.I from -) and will recurse into any that match the mask specified to the command. Only -files that match the mask specified using the -.B mask -command will be retrieved. See also the -.mask -command. - -When recursion is toggled OFF, only files from the current working -directory on the source machine that match the mask specified to the -.B mget -or -.B mput -commands will be copied, and any mask specified using the -.B mask -command will be ignored. -.RE -.RE - -.B rm -.RS 3 -.B Parameters: -.RS 3 -.I <mask> - -.RE -.B Description: -.RS 3 -Remove all files matching -.I mask -from the current working directory -.B on the server. -.RE -.RE - -.B rmdir -.RS 3 -.B Parameters: -.RS 3 -.I <directory name> - -.RE -.B Description: -.RS 3 -Remove the specified directory (user access privileges permitting) -.B from the server. -.RE -.RE - -.B tar -.RS 3 -.B Parameters: -.RS 3 -.I <c|x>[IXbgNa] - -.RE -.B Description: -.RS 3 -Performs a tar operation - see -T command line option above. Behaviour -may be affected by the -.B tarmode -command (see below). Using the g (incremental) and N (newer) will affect -tarmode settings. Note that using the "-" option with tar x may not -work - use the command line option instead. -.RE -.RE - -.B blocksize -.RS 3 -.B Parameters -.RS 3 -.I <blocksize> - -.RE -.B Description -.RS 3 -Blocksize. Must be followed by a valid (greater than zero) blocksize. -Causes tar file to be written out in blocksize*TBLOCK (usually 512 byte) -blocks. -.RE -.RE - -.B tarmode -.RS 3 -.B Parameters -.RS 3 -.I <full|inc|reset|noreset> - -.RE -.B Description -.RS 3 -Changes tar's behaviour with regard to archive bits. In full mode, -tar will back up everything regardless of the archive bit setting (this -is the default mode). In incremental mode, tar will only back up files -with the archive bit set. In reset mode, tar will reset the archive bit -on all files it backs up (implies read/write share). -.RE -.RE - -.B setmode -.RS 3 -.B Parameters -.RS 3 -.I <filename> <perm=[+|-]rsha> - -.RE -.B Description -.RS 3 -A version of the DOS attrib command to set file permissions. For example, - -setmode myfile +r - -would make myfile read only. -.RE -.RE - -.SH NOTES -Some servers are fussy about the case of supplied usernames, passwords, share -names (aka service names) and machine names. If you fail to connect try -giving all parameters in uppercase. - -It is often necessary to use the -.B -n -option when connecting to some types -of servers. For example OS/2 LanManager insists on a valid netbios name -being used, so you need to supply a valid name that would be known to -the server. - -.B smbclient -supports long file names where the server supports the LANMAN2 -protocol. - -.SH FILES -Not applicable. - -.SH ENVIRONMENT VARIABLES -.B USER -.RS 3 -The variable USER may contain the username of the person using the client. -This information is used only if the protocol level is high enough to support +The base name is used to generate actual log file names. +For example, if the name specified was "log", the debug file +would be \fIlog.client\fR. + +The log file generated is never removed by the client. +.TP +\fB-h\fR +Print the usage message for the client. +.TP +\fB-I IP-address\fR +\fIIP address\fR is the address of the server to connect to. +It should be specified in standard "a.b.c.d" notation. + +Normally the client would attempt to locate a named +SMB/CIFS server by looking it up via the NetBIOS name resolution +mechanism described above in the \fIname resolve order\fR +parameter above. Using this parameter will force the client +to assume that the server is on the machine with the specified IP +address and the NetBIOS name component of the resource being +connected to will be ignored. + +There is no default for this parameter. If not supplied, +it will be determined automatically by the client as described +above. +.TP +\fB-E\fR +This parameter causes the client to write messages +to the standard error stream (stderr) rather than to the standard +output stream. + +By default, the client writes messages to standard output +- typically the user's tty. +.TP +\fB-U username[%pass]\fR +Sets the SMB username or username and password. +If %pass is not specified, The user will be prompted. The client +will first check the \fBUSER\fR environment variable, then the +\fBLOGNAME\fR variable and if either exists, the +string is uppercased. Anything in these variables following a '%' +sign will be treated as the password. If these environment +variables are not found, the username GUEST +is used. + +If the password is not included in these environment +variables (using the %pass syntax), \fBsmbclient\fR will look for +a \fBPASSWD\fR environment variable from which +to read the password. + +A third option is to use a credentials file which +contains the plaintext of the username and password. This +option is mainly provided for scripts where the admin doesn't +wish to pass the credentials on the command line or via environment +variables. If this method is used, make certain that the permissions +on the file restrict access from unwanted users. See the +\fI-A\fR for more details. + +Be cautious about including passwords in scripts or in +the \fBPASSWD\fR environment variable. Also, on +many systems the command line of a running process may be seen +via the \fBps\fR command to be safe always allow +\fBsmbclient\fR to prompt for a password and type +it in directly. +.TP +\fB-A filename\fR +This option allows +you to specify a file from which to read the username and +password used in the connection. The format of the file is + +.sp +.nf +username = <value> +password = <value> + +.sp +.fi + +Make certain that the permissions on the file restrict +access from unwanted users. +.TP +\fB-L\fR +This option allows you to look at what services +are available on a server. You use it as \fBsmbclient -L +host\fR and a list should appear. The \fI-I +\fRoption may be useful if your NetBIOS names don't +match your TCP/IP DNS host names or if you are trying to reach a +host on another network. +.TP +\fB-t terminal code\fR +This option tells \fBsmbclient\fR how to interpret +filenames coming from the remote server. Usually Asian language +multibyte UNIX implementations use different character sets than +SMB/CIFS servers (\fBEUC\fR instead of \fB SJIS\fR for example). Setting this parameter will let +\fBsmbclient\fR convert between the UNIX filenames and +the SMB filenames correctly. This option has not been seriously tested +and may have some problems. + +The terminal codes include CWsjis, CWeuc, CWjis7, CWjis8, +CWjunet, CWhex, CWcap. This is not a complete list, check the Samba +source code for the complete list. +.TP +\fB-b buffersize\fR +This option changes the transmit/send buffer +size when getting or putting a file from/to the server. The default +is 65520 bytes. Setting this value smaller (to 1200 bytes) has been +observed to speed up file transfers to and from a Win9x server. +.TP +\fB-W WORKGROUP\fR +Override the default workgroup specified in the +workgroup parameter of the \fIsmb.conf\fR file +for this connection. This may be needed to connect to some +servers. +.TP +\fB-T tar options\fR +smbclient may be used to create \fBtar(1) +\fRcompatible backups of all the files on an SMB/CIFS +share. The secondary tar flags that can be given to this option +are : +.RS +.TP 0.2i +\(bu +\fIc\fR - Create a tar file on UNIX. +Must be followed by the name of a tar file, tape device +or "-" for standard output. If using standard output you must +turn the log level to its lowest value -d0 to avoid corrupting +your tar file. This flag is mutually exclusive with the +\fIx\fR flag. +.TP 0.2i +\(bu +\fIx\fR - Extract (restore) a local +tar file back to a share. Unless the -D option is given, the tar +files will be restored from the top level of the share. Must be +followed by the name of the tar file, device or "-" for standard +input. Mutually exclusive with the \fIc\fR flag. +Restored files have their creation times (mtime) set to the +date saved in the tar file. Directories currently do not get +their creation dates restored properly. +.TP 0.2i +\(bu +\fII\fR - Include files and directories. +Is the default behavior when filenames are specified above. Causes +tar files to be included in an extract or create (and therefore +everything else to be excluded). See example below. Filename globbing +works in one of two ways. See r below. +.TP 0.2i +\(bu +\fIX\fR - Exclude files and directories. +Causes tar files to be excluded from an extract or create. See +example below. Filename globbing works in one of two ways now. +See \fIr\fR below. +.TP 0.2i +\(bu +\fIb\fR - Blocksize. Must be followed +by a valid (greater than zero) blocksize. Causes tar file to be +written out in blocksize*TBLOCK (usually 512 byte) blocks. +.TP 0.2i +\(bu +\fIg\fR - Incremental. Only back up +files that have the archive bit set. Useful only with the +\fIc\fR flag. +.TP 0.2i +\(bu +\fIq\fR - Quiet. Keeps tar from printing +diagnostics as it works. This is the same as tarmode quiet. +.TP 0.2i +\(bu +\fIr\fR - Regular expression include +or exclude. Uses regular expression matching for +excluding or excluding files if compiled with HAVE_REGEX_H. +However this mode can be very slow. If not compiled with +HAVE_REGEX_H, does a limited wildcard match on '*' and '?'. +.TP 0.2i +\(bu +\fIN\fR - Newer than. Must be followed +by the name of a file whose date is compared against files found +on the share during a create. Only files newer than the file +specified are backed up to the tar file. Useful only with the +\fIc\fR flag. +.TP 0.2i +\(bu +\fIa\fR - Set archive bit. Causes the +archive bit to be reset when a file is backed up. Useful with the +\fIg\fR and \fIc\fR flags. +.RE +.PP +\fBTar Long File Names\fR +.PP +.PP +\fBsmbclient\fR's tar option now supports long +file names both on backup and restore. However, the full path +name of the file must be less than 1024 bytes. Also, when +a tar archive is created, \fBsmbclient\fR's tar option places all +files in the archive with relative names, not absolute names. +.PP +.PP +\fBTar Filenames\fR +.PP +.PP +All file names can be given as DOS path names (with '\\' +as the component separator) or as UNIX path names (with '/' as +the component separator). +.PP +.PP +\fBExamples\fR +.PP +.PP +Restore from tar file \fIbackup.tar\fR into myshare on mypc +(no password on share). +.PP +.PP +\fBsmbclient //mypc/yshare "" -N -Tx backup.tar +\fR.PP +.PP +Restore everything except \fIusers/docs\fR +.PP +.PP +\fBsmbclient //mypc/myshare "" -N -TXx backup.tar +users/docs\fR +.PP +.PP +Create a tar file of the files beneath \fI users/docs\fR. +.PP +.PP +\fBsmbclient //mypc/myshare "" -N -Tc +backup.tar users/docs \fR +.PP +.PP +Create the same tar file as above, but now use +a DOS path name. +.PP +.PP +\fBsmbclient //mypc/myshare "" -N -tc backup.tar +users\\edocs \fR +.PP +.PP +Create a tar file of all the files and directories in +the share. +.PP +.PP +\fBsmbclient //mypc/myshare "" -N -Tc backup.tar * +\fR.PP +.TP +\fB-D initial directory\fR +Change to initial directory before starting. Probably +only of any use with the tar -T option. +.TP +\fB-c command string\fR +command string is a semicolon-separated list of +commands to be executed instead of prompting from stdin. \fI -N\fR is implied by \fI-c\fR. + +This is particularly useful in scripts and for printing stdin +to the server, e.g. \fB-c 'print -'\fR. +.SH "OPERATIONS" +.PP +Once the client is running, the user is presented with +a prompt : +.PP +smb:\\> +.PP +The backslash ("\\") indicates the current working directory +on the server, and will change if the current working directory +is changed. +.PP +The prompt indicates that the client is ready and waiting to +carry out a user command. Each command is a single word, optionally +followed by parameters specific to that command. Command and parameters +are space-delimited unless these notes specifically +state otherwise. All commands are case-insensitive. Parameters to +commands may or may not be case sensitive, depending on the command. +.PP +You can specify file names which have spaces in them by quoting +the name with double quotes, for example "a long file name". +.PP +Parameters shown in square brackets (e.g., "[parameter]") are +optional. If not given, the command will use suitable defaults. Parameters +shown in angle brackets (e.g., "<parameter>") are required. +.PP +Note that all commands operating on the server are actually +performed by issuing a request to the server. Thus the behavior may +vary from server to server, depending on how the server was implemented. +.PP +The commands available are given here in alphabetical order. +.TP +\fB? [command]\fR +If \fIcommand\fR is specified, the ? command will display +a brief informative message about the specified command. If no +command is specified, a list of available commands will +be displayed. +.TP +\fB! [shell command]\fR +If \fIshell command\fR is specified, the ! +command will execute a shell locally and run the specified shell +command. If no command is specified, a local shell will be run. +.TP +\fBcd [directory name]\fR +If "directory name" is specified, the current +working directory on the server will be changed to the directory +specified. This operation will fail if for any reason the specified +directory is inaccessible. + +If no directory name is specified, the current working +directory on the server will be reported. +.TP +\fBdel <mask>\fR +The client will request that the server attempt +to delete all files matching \fImask\fR from the current working +directory on the server. +.TP +\fBdir <mask>\fR +A list of the files matching \fImask\fR in the current +working directory on the server will be retrieved from the server +and displayed. +.TP +\fBexit\fR +Terminate the connection with the server and exit +from the program. +.TP +\fBget <remote file name> [local file name]\fR +Copy the file called \fIremote file name\fR from +the server to the machine running the client. If specified, name +the local copy \fIlocal file name\fR. Note that all transfers in +\fBsmbclient\fR are binary. See also the +lowercase command. +.TP +\fBhelp [command]\fR +See the ? command above. +.TP +\fBlcd [directory name]\fR +If \fIdirectory name\fR is specified, the current +working directory on the local machine will be changed to +the directory specified. This operation will fail if for any +reason the specified directory is inaccessible. + +If no directory name is specified, the name of the +current working directory on the local machine will be reported. +.TP +\fBlowercase\fR +Toggle lowercasing of filenames for the get and +mget commands. + +When lowercasing is toggled ON, local filenames are converted +to lowercase when using the get and mget commands. This is +often useful when copying (say) MSDOS files from a server, because +lowercase filenames are the norm on UNIX systems. +.TP +\fBls <mask>\fR +See the dir command above. +.TP +\fBmask <mask>\fR +This command allows the user to set up a mask +which will be used during recursive operation of the mget and +mput commands. + +The masks specified to the mget and mput commands act as +filters for directories rather than files when recursion is +toggled ON. + +The mask specified with the mask command is necessary +to filter files within those directories. For example, if the +mask specified in an mget command is "source*" and the mask +specified with the mask command is "*.c" and recursion is +toggled ON, the mget command will retrieve all files matching +"*.c" in all directories below and including all directories +matching "source*" in the current working directory. + +Note that the value for mask defaults to blank (equivalent +to "*") and remains so until the mask command is used to change it. +It retains the most recently specified value indefinitely. To +avoid unexpected results it would be wise to change the value of +mask back to "*" after using the mget or mput commands. +.TP +\fBmd <directory name>\fR +See the mkdir command. +.TP +\fBmget <mask>\fR +Copy all files matching \fImask\fR from the server to +the machine running the client. + +Note that \fImask\fR is interpreted differently during recursive +operation and non-recursive operation - refer to the recurse and +mask commands for more information. Note that all transfers in +\fBsmbclient\fR are binary. See also the lowercase command. +.TP +\fBmkdir <directory name>\fR +Create a new directory on the server (user access +privileges permitting) with the specified name. +.TP +\fBmput <mask>\fR +Copy all files matching \fImask\fR in the current working +directory on the local machine to the current working directory on +the server. + +Note that \fImask\fR is interpreted differently during recursive +operation and non-recursive operation - refer to the recurse and mask +commands for more information. Note that all transfers in \fBsmbclient\fR +are binary. +.TP +\fBprint <file name>\fR +Print the specified file from the local machine +through a printable service on the server. + +See also the printmode command. +.TP +\fBprintmode <graphics or text>\fR +Set the print mode to suit either binary data +(such as graphical information) or text. Subsequent print +commands will use the currently set print mode. +.TP +\fBprompt\fR +Toggle prompting for filenames during operation +of the mget and mput commands. + +When toggled ON, the user will be prompted to confirm +the transfer of each file during these commands. When toggled +OFF, all specified files will be transferred without prompting. +.TP +\fBput <local file name> [remote file name]\fR +Copy the file called \fIlocal file name\fR from the +machine running the client to the server. If specified, +name the remote copy \fIremote file name\fR. Note that all transfers +in \fBsmbclient\fR are binary. See also the lowercase command. +.TP +\fBqueue\fR +Displays the print queue, showing the job id, +name, size and current status. +.TP +\fBquit\fR +See the exit command. +.TP +\fBrd <directory name>\fR +See the rmdir command. +.TP +\fBrecurse\fR +Toggle directory recursion for the commands mget +and mput. + +When toggled ON, these commands will process all directories +in the source directory (i.e., the directory they are copying +from ) and will recurse into any that match the mask specified +to the command. Only files that match the mask specified using +the mask command will be retrieved. See also the mask command. + +When recursion is toggled OFF, only files from the current +working directory on the source machine that match the mask specified +to the mget or mput commands will be copied, and any mask specified +using the mask command will be ignored. +.TP +\fBrm <mask>\fR +Remove all files matching \fImask\fR from the current +working directory on the server. +.TP +\fBrmdir <directory name>\fR +Remove the specified directory (user access +privileges permitting) from the server. +.TP +\fBtar <c|x>[IXbgNa]\fR +Performs a tar operation - see the \fI-T +\fRcommand line option above. Behavior may be affected +by the tarmode command (see below). Using g (incremental) and N +(newer) will affect tarmode settings. Note that using the "-" option +with tar x may not work - use the command line option instead. +.TP +\fBblocksize <blocksize>\fR +Blocksize. Must be followed by a valid (greater +than zero) blocksize. Causes tar file to be written out in +\fIblocksize\fR*TBLOCK (usually 512 byte) blocks. +.TP +\fBtarmode <full|inc|reset|noreset>\fR +Changes tar's behavior with regard to archive +bits. In full mode, tar will back up everything regardless of the +archive bit setting (this is the default mode). In incremental mode, +tar will only back up files with the archive bit set. In reset mode, +tar will reset the archive bit on all files it backs up (implies +read/write share). +.TP +\fBsetmode <filename> <perm=[+|\\-]rsha>\fR +A version of the DOS attrib command to set +file permissions. For example: + +\fBsetmode myfile +r \fR + +would make myfile read only. +.SH "NOTES" +.PP +Some servers are fussy about the case of supplied usernames, +passwords, share names (AKA service names) and machine names. +If you fail to connect try giving all parameters in uppercase. +.PP +It is often necessary to use the -n option when connecting +to some types of servers. For example OS/2 LanManager insists +on a valid NetBIOS name being used, so you need to supply a valid +name that would be known to the server. +.PP +smbclient supports long file names where the server +supports the LANMAN2 protocol or above. +.SH "ENVIRONMENT VARIABLES" +.PP +The variable \fBUSER\fR may contain the +username of the person using the client. This information is +used only if the protocol level is high enough to support session-level passwords. -.RE - -.SH INSTALLATION -The location of the client program is a matter for individual system -administrators. The following are thus suggestions only. - -It is recommended that the client software be installed under the /usr/local -hierarchy, in a directory readable by all, writeable only by root. The client -program itself should be executable by all. The client should NOT be setuid -or setgid! - -The client log files should be put in a directory readable and writable only -by the user. - -To test the client, you will need to know the name of a running Lan manager -server. It is possible to run the smbd (see -.B smbd(8)) as an ordinary user - running that server as a daemon on a -user-accessible port (typically any port number over 1024) would -provide a suitable test server. -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the client software, so it is possible that your version of -the client has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B smbd(8) - -.SH DIAGNOSTICS -[This section under construction] - -Most diagnostics issued by the client are logged in a specified log file. The -log file name is specified at compile time, but may be overridden on the -command line. - -The number and nature of diagnostics available depends on the debug level used -by the client. If you have problems, set the debug level to 3 and peruse the -log files. - -Most messages are reasonably self-explanatory. Unfortunately, at time of -creation of this man page the source code is still too fluid to warrant -describing each and every diagnostic. At this stage your best bet is still -to grep the source code and inspect the conditions that gave rise to the -diagnostics you are seeing. - -.SH BUGS -None known. -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -This man page written by Karl Auer (Karl.Auer@anu.edu.au) - -See -.B smb.conf(5) for a full list of contributors and details on how to -submit bug reports, comments etc. +.PP +The variable \fBPASSWD\fR may contain +the password of the person using the client. This information is +used only if the protocol level is high enough to support +session-level passwords. +.PP +The variable \fBLIBSMB_PROG\fR may contain +the path, executed with system(), which the client should connect +to instead of connecting to a server. This functionality is primarily +intended as a development aid, and works best when using a LMHOSTS +file +.SH "INSTALLATION" +.PP +The location of the client program is a matter for +individual system administrators. The following are thus +suggestions only. +.PP +It is recommended that the smbclient software be installed +in the \fI/usr/local/samba/bin/\fR or \fI /usr/samba/bin/\fR directory, this directory readable +by all, writeable only by root. The client program itself should +be executable by all. The client should \fBNOT\fR be +setuid or setgid! +.PP +The client log files should be put in a directory readable +and writeable only by the user. +.PP +To test the client, you will need to know the name of a +running SMB/CIFS server. It is possible to run \fBsmbd(8) +\fRas an ordinary user - running that server as a daemon +on a user-accessible port (typically any port number over 1024) +would provide a suitable test server. +.SH "DIAGNOSTICS" +.PP +Most diagnostics issued by the client are logged in a +specified log file. The log file name is specified at compile time, +but may be overridden on the command line. +.PP +The number and nature of diagnostics available depends +on the debug level used by the client. If you have problems, +set the debug level to 3 and peruse the log files. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbcontrol.1 b/docs/manpages/smbcontrol.1 new file mode 100644 index 00000000000..4b27119673a --- /dev/null +++ b/docs/manpages/smbcontrol.1 @@ -0,0 +1,124 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBCONTROL" "1" "06 December 2001" "" "" +.SH NAME +smbcontrol \- send messages to smbd or nmbd processes +.SH SYNOPSIS +.sp +\fBsmbcontrol\fR [ \fB-i\fR ] +.sp +\fBsmbcontrol\fR [ \fBdestination\fR ] [ \fBmessage-type\fR ] [ \fBparameter\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBsmbcontrol\fR is a very small program, which +sends messages to an smbd(8)or +an nmbd(8)daemon running on the +system. +.SH "OPTIONS" +.TP +\fB-i\fR +Run interactively. Individual commands +of the form destination message-type parameters can be entered +on STDIN. An empty command line or a "q" will quit the +program. +.TP +\fBdestination\fR +One of \fInmbd\fR +\fIsmbd\fR or a process ID. + +The \fIsmbd\fR destination causes the +message to "broadcast" to all smbd daemons. + +The \fInmbd\fR destination causes the +message to be sent to the nmbd daemon specified in the +\fInmbd.pid\fR file. + +If a single process ID is given, the message is sent +to only that process. +.TP +\fBmessage-type\fR +One of: close-share, +debug, +force-election, ping +, profile, debuglevel, profilelevel, +or printer-notify. + +The close-share message-type sends a +message to smbd which will then close the client connections to +the named share. Note that this doesn't affect client connections +to any other shares. This message-type takes an argument of the +share name for which client connections will be close, or the +"*" character which will close all currently open shares. +This message can only be sent to smbd. + +The debug message-type allows +the debug level to be set to the value specified by the +parameter. This can be sent to any of the destinations. + +The force-election message-type can only be +sent to the nmbd destination. This message +causes the \fBnmbd\fR daemon to force a new browse +master election. + +The ping message-type sends the +number of "ping" messages specified by the parameter and waits +for the same number of reply "pong" messages. This can be sent to +any of the destinations. + +The profile message-type sends a +message to an smbd to change the profile settings based on the +parameter. The parameter can be "on" to turn on profile stats +collection, "off" to turn off profile stats collection, "count" +to enable only collection of count stats (time stats are +disabled), and "flush" to zero the current profile stats. This can +be sent to any of the destinations. + +The debuglevel message-type sends +a "request debug level" message. The current debug level setting +is returned by a "debuglevel" message. This can be +sent to any of the destinations. + +The profilelevel message-type sends +a "request profile level" message. The current profile level +setting is returned by a "profilelevel" message. This can be sent +to any of the destinations. + +The printer-notify message-type sends a +message to smbd which in turn sends a printer notify message to +any Windows NT clients connected to a printer. This message-type +takes an argument of the printer name to send notify messages to. +This message can only be sent to smbd. + +The close-share message-type sends a +message to smbd which forces smbd to close the share that was +specified as an argument. This may be useful if you made changes +to the access controls on the share. +.TP +\fBparameters\fR +any parameters required for the message-type +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBnmbd(8)\fR, +and \fBsmbd(8)\fR. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbd.8 b/docs/manpages/smbd.8 index bae41b2c479..42157c00b07 100644 --- a/docs/manpages/smbd.8 +++ b/docs/manpages/smbd.8 @@ -1,407 +1,487 @@ -.TH SMBD 8 17/1/1995 smbd smbd +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBD" "8" "06 December 2001" "" "" .SH NAME -smbd \- provide SMB (aka LanManager) services to clients +smbd \- server to provide SMB/CIFS services to clients .SH SYNOPSIS -.B smbd -[ -.B -D -] [ -.B -a -] [ -.B -d -.I debuglevel -] [ -.B -l -.I log file -] [ -.B -p -.I port number -] [ -.B -O -.I socket options -] [ -.B -s -.I configuration file -] -.SH DESCRIPTION +.sp +\fBsmbd\fR [ \fB-D\fR ] [ \fB-a\fR ] [ \fB-o\fR ] [ \fB-P\fR ] [ \fB-h\fR ] [ \fB-V\fR ] [ \fB-d <debug level>\fR ] [ \fB-l <log directory>\fR ] [ \fB-p <port number>\fR ] [ \fB-O <socket option>\fR ] [ \fB-s <configuration file>\fR ] +.SH "DESCRIPTION" +.PP This program is part of the Samba suite. - -.B smbd -is a server that can provide most SMB services. The -server provides filespace and printer services to clients using the SMB -protocol. This is compatible with the LanManager protocol, and can -service LanManager clients. - -An extensive description of the services that the server can provide is given -in the man page for the configuration file controlling the attributes of those -services (see -.B smb.conf(5)). This man page will not describe the services, but -will concentrate on the administrative aspects of running the server. - -Please note that there are significant security implications to running this -server, and -.B smb.conf(5) should be regarded as mandatory reading before proceeding with -installation. - -A session is created whenever a client requests one. Each client gets a copy -of the server for each session. This copy then services all connections made -by the client during that session. When all connections from its client are -are closed, the copy of the server for that client terminates. - -The configuration file is automatically reloaded if it changes. You -can force a reload by sending a SIGHUP to the server. - -.SH OPTIONS -.B -D - -.RS 3 -If specified, this parameter causes the server to operate as a daemon. That is, -it detaches itself and runs in the background, fielding requests on the -appropriate port. - -By default, the server will NOT operate as a daemon. -.RE - -.B -a - -.RS 3 -If this parameter is specified, the log files will be overwritten with each -new connection. By default, the log files will be appended to. -.RE - -.B -d -.I debuglevel -.RS 3 - -debuglevel is an integer from 0 to 5. - -The default value if this parameter is not specified is zero. - -The higher this value, the more detail will be logged to the log files about -the activities of the server. At level 0, only critical errors and serious -warnings will be logged. Level 1 is a reasonable level for day to day running -- it generates a small amount of information about operations carried out. - -Levels above 1 will generate considerable amounts of log data, and should -only be used when investigating a problem. Levels above 3 are designed for -use only by developers and generate HUGE amounts of log data, most of which -is extremely cryptic. -.RE - -.B -l -.I log file - -.RS 3 +.PP +\fBsmbd\fR is the server daemon that +provides filesharing and printing services to Windows clients. +The server provides filespace and printer services to +clients using the SMB (or CIFS) protocol. This is compatible +with the LanManager protocol, and can service LanManager +clients. These include MSCLIENT 3.0 for DOS, Windows for +Workgroups, Windows 95/98/ME, Windows NT, Windows 2000, +OS/2, DAVE for Macintosh, and smbfs for Linux. +.PP +An extensive description of the services that the +server can provide is given in the man page for the +configuration file controlling the attributes of those +services (see \fIsmb.conf(5) +\fR. This man page will not describe the +services, but will concentrate on the administrative aspects +of running the server. +.PP +Please note that there are significant security +implications to running this server, and the \fIsmb.conf(5)\fR +manpage should be regarded as mandatory reading before +proceeding with installation. +.PP +A session is created whenever a client requests one. +Each client gets a copy of the server for each session. This +copy then services all connections made by the client during +that session. When all connections from its client are closed, +the copy of the server for that client terminates. +.PP +The configuration file, and any files that it includes, +are automatically reloaded every minute, if they change. You +can force a reload by sending a SIGHUP to the server. Reloading +the configuration file will not affect connections to any service +that is already established. Either the user will have to +disconnect from the service, or \fBsmbd\fR killed and restarted. +.SH "OPTIONS" +.TP +\fB-D\fR +If specified, this parameter causes +the server to operate as a daemon. That is, it detaches +itself and runs in the background, fielding requests +on the appropriate port. Operating the server as a +daemon is the recommended way of running \fBsmbd\fR for +servers that provide more than casual use file and +print services. This switch is assumed if \fBsmbd +\fRis executed on the command line of a shell. +.TP +\fB-a\fR +If this parameter is specified, each new +connection will append log messages to the log file. +This is the default. +.TP +\fB-o\fR +If this parameter is specified, the +log files will be overwritten when opened. By default, +\fBsmbd\fR will append entries to the log +files. +.TP +\fB-P\fR +Passive option. Causes \fBsmbd\fR not to +send any network traffic out. Used for debugging by +the developers only. +.TP +\fB-h\fR +Prints the help information (usage) +for \fBsmbd\fR. +.TP +\fB-v\fR +Prints the version number for +\fBsmbd\fR. +.TP +\fB-d <debug level>\fR +\fIdebuglevel\fR is an integer +from 0 to 10. The default value if this parameter is +not specified is zero. + +The higher this value, the more detail will be +logged to the log files about the activities of the +server. At level 0, only critical errors and serious +warnings will be logged. Level 1 is a reasonable level for +day to day running - it generates a small amount of +information about operations carried out. + +Levels above 1 will generate considerable +amounts of log data, and should only be used when +investigating a problem. Levels above 3 are designed for +use only by developers and generate HUGE amounts of log +data, most of which is extremely cryptic. + +Note that specifying this parameter here will +override the log +levelfile. +.TP +\fB-l <log directory>\fR If specified, -.I logfile -specifies a base filename into which operational data from the running server -will be logged. - -The default base name is specified at compile time. - -The base name is used to generate actual log file names. For example, if the -name specified was "log", the following files would be used for log data: - -.RS 3 -log.debug (containing debugging information) - -log.in (containing inbound transaction data) - -log.out (containing outbound transaction data) -.RE - -The log files generated are never removed by the server. -.RE - -.B -O -.I socket options -.RS 3 - -See the socket options section of smb.conf(5) for details - -.RE -.B -p -.I port number -.RS 3 - -port number is a positive integer value. - -The default value if this parameter is not specified is 139. - -This number is the port number that will be used when making connections to -the server from client software. The standard (well-known) port number for the -server is 139, hence the default. If you wish to run the server as an ordinary -user rather than as root, most systems will require you to use a port number -greater than 1024 - ask your system administrator for help if you are in this -situation. - -This parameter is not normally specified except in the above situation. -.RE - -.B -s -.I configuration file - -.RS 3 -The default configuration file name is determined at compile time. - -The file specified contains the configuration details required by the server. -The information in this file includes server-specific information such as -what printcap file to use, as well as descriptions of all the services that the -server is to provide. See -.B smb.conf(5) for more information. -.RE - -.SH FILES - -.B /etc/inetd.conf - -.RS 3 -If the server is to be run by the inetd meta-daemon, this file must contain -suitable startup information for the meta-daemon. See the section -"INSTALLATION" below. -.RE - -.B /etc/rc - -.RS 3 -(or whatever initialisation script your system uses) - -If running the server as a daemon at startup, this file will need to contain -an appropriate startup sequence for the server. See the section "INSTALLATION" +\fIlog directory\fR +specifies a log directory into which the "log.smbd" log +file will be created for informational and debug +messages from the running server. The log +file generated is never removed by the server although +its size may be controlled by the max log size +option in the \fI smb.conf(5)\fRfile. + +The default log directory is specified at +compile time. +.TP +\fB-O <socket options>\fR +See the socket options +parameter in the \fIsmb.conf(5) +\fRfile for details. +.TP +\fB-p <port number>\fR +\fIport number\fR is a positive integer +value. The default value if this parameter is not +specified is 139. + +This number is the port number that will be +used when making connections to the server from client +software. The standard (well-known) port number for the +SMB over TCP is 139, hence the default. If you wish to +run the server as an ordinary user rather than +as root, most systems will require you to use a port +number greater than 1024 - ask your system administrator +for help if you are in this situation. + +In order for the server to be useful by most +clients, should you configure it on a port other +than 139, you will require port redirection services +on port 139, details of which are outlined in rfc1002.txt +section 4.3.5. + +This parameter is not normally specified except +in the above situation. +.TP +\fB-s <configuration file>\fR +The file specified contains the +configuration details required by the server. The +information in this file includes server-specific +information such as what printcap file to use, as well +as descriptions of all the services that the server is +to provide. See \fI smb.conf(5)\fRfor more information. +The default configuration file name is determined at +compile time. +.SH "FILES" +.TP +\fB\fI/etc/inetd.conf\fB\fR +If the server is to be run by the +\fBinetd\fR meta-daemon, this file +must contain suitable startup information for the +meta-daemon. See the section INSTALLATION below. +.TP +\fB\fI/etc/rc\fB\fR +or whatever initialization script your +system uses). + +If running the server as a daemon at startup, +this file will need to contain an appropriate startup +sequence for the server. See the section INSTALLATION below. -.RE - -.B /etc/services - -.RS 3 -If running the server via the meta-daemon inetd, this file must contain a -mapping of service name (eg., netbios-ssn) to service port (eg., 139) and -protocol type (eg., tcp). See the section "INSTALLATION" below. -.RE - -.B /usr/local/smb/smb.conf - -.RS 3 -This file describes all the services the server is to make available to -clients. See -.B smb.conf(5) for more information. -.RE -.RE - -.SH LIMITATIONS - -On some systems smbd cannot change uid back to root after a setuid() call. -Such systems are called "trapdoor" uid systems. If you have such a system, -you will be unable to connect from a client (such as a PC) as two different -users at once. Attempts to connect the second user will result in "access -denied" or similar. - -.SH ENVIRONMENT VARIABLES - -.B PRINTER - -.RS 3 -If no printer name is specified to printable services, most systems will -use the value of this variable (or "lp" if this variable is not defined) -as the name of the printer to use. This is not specific to the server, -however. -.RE - -.SH INSTALLATION -The location of the server and its support files is a matter for individual -system administrators. The following are thus suggestions only. - -It is recommended that the server software be installed under the -/usr/local hierarchy, in a directory readable by all, writeable only -by root. The server program itself should be executable by all, as -users may wish to run the server themselves (in which case it will of -course run with their privileges). The server should NOT be -setuid. On some systems it may be worthwhile to make smbd setgid to an -empty group. This is because some systems may have a security hole where -daemon processes that become a user can be attached to with a -debugger. Making the smbd file setgid to an empty group may prevent -this hole from being exploited. This secrity hole and the suggested -fix has only been confirmed on Linux at the time this was written. It -is possible that this hole only exists in Linux, as testing on other -systems has thus far shown them to be immune. - -The server log files should be put in a directory readable and writable only -by root, as the log files may contain sensitive information. - -The configuration file should be placed in a directory readable and writable -only by root, as the configuration file controls security for the services -offered by the server. The configuration file can be made readable by all if -desired, but this is not necessary for correct operation of the server and -is not recommended. A sample configuration file "smb.conf.sample" is supplied -with the source to the server - this may be renamed to "smb.conf" and -modified to suit your needs. - +.TP +\fB\fI/etc/services\fB\fR +If running the server via the +meta-daemon \fBinetd\fR, this file +must contain a mapping of service name (e.g., netbios-ssn) +to service port (e.g., 139) and protocol type (e.g., tcp). +See the section INSTALLATION below. +.TP +\fB\fI/usr/local/samba/lib/smb.conf\fB\fR +This is the default location of the +\fIsmb.conf\fR +server configuration file. Other common places that systems +install this file are \fI/usr/samba/lib/smb.conf\fR +and \fI/etc/smb.conf\fR. + +This file describes all the services the server +is to make available to clients. See \fIsmb.conf(5)\fRfor more information. +.SH "LIMITATIONS" +.PP +On some systems \fBsmbd\fR cannot change uid back +to root after a setuid() call. Such systems are called +trapdoor uid systems. If you have such a system, +you will be unable to connect from a client (such as a PC) as +two different users at once. Attempts to connect the +second user will result in access denied or +similar. +.SH "ENVIRONMENTVARIABLES" +.TP +\fBPRINTER\fR +If no printer name is specified to +printable services, most systems will use the value of +this variable (or lp if this variable is +not defined) as the name of the printer to use. This +is not specific to the server, however. +.SH "INSTALLATION" +.PP +The location of the server and its support files +is a matter for individual system administrators. The following +are thus suggestions only. +.PP +It is recommended that the server software be installed +under the \fI/usr/local/samba/\fR hierarchy, +in a directory readable by all, writeable only by root. The server +program itself should be executable by all, as users may wish to +run the server themselves (in which case it will of course run +with their privileges). The server should NOT be setuid. On some +systems it may be worthwhile to make \fBsmbd\fR setgid to an empty group. +This is because some systems may have a security hole where daemon +processes that become a user can be attached to with a debugger. +Making the \fBsmbd\fR file setgid to an empty group may prevent +this hole from being exploited. This security hole and the suggested +fix has only been confirmed on old versions (pre-kernel 2.0) of Linux +at the time this was written. It is possible that this hole only +exists in Linux, as testing on other systems has thus far shown them +to be immune. +.PP +The server log files should be put in a directory readable and +writeable only by root, as the log files may contain sensitive +information. +.PP +The configuration file should be placed in a directory +readable and writeable only by root, as the configuration file +controls security for the services offered by the server. The +configuration file can be made readable by all if desired, but +this is not necessary for correct operation of the server and is +not recommended. A sample configuration file \fIsmb.conf.sample +\fRis supplied with the source to the server - this may +be renamed to \fIsmb.conf\fR and modified to suit +your needs. +.PP The remaining notes will assume the following: - -.RS 3 -smbd (the server program) installed in /usr/local/smb - -smb.conf (the configuration file) installed in /usr/local/smb - -log files stored in /var/adm/smblogs -.RE - -The server may be run either as a daemon by users or at startup, or it may -be run from a meta-daemon such as inetd upon request. If run as a daemon, the -server will always be ready, so starting sessions will be faster. If run from -a meta-daemon some memory will be saved and utilities such as the tcpd -TCP-wrapper may be used for extra security. - -When you've decided, continue with either "RUNNING THE SERVER AS A DAEMON" or -"RUNNING THE SERVER ON REQUEST". -.SH RUNNING THE SERVER AS A DAEMON -To run the server as a daemon from the command line, simply put the "-D" option -on the command line. There is no need to place an ampersand at the end of the -command line - the "-D" option causes the server to detach itself from the -tty anyway. - -Any user can run the server as a daemon (execute permissions permitting, of -course). This is useful for testing purposes, and may even be useful as a -temporary substitute for something like ftp. When run this way, however, the -server will only have the privileges of the user who ran it. - -To ensure that the server is run as a daemon whenever the machine is started, -and to ensure that it runs as root so that it can serve multiple clients, you -will need to modify the system startup files. Wherever appropriate (for -example, in /etc/rc), insert the following line, substituting -port number, log file location, configuration file location and debug level as -desired: - -.RS 3 -/usr/local/smb/smbd -D -l /var/adm/smblogs/log -s /usr/local/smb/smb.conf -.RE - -(The above should appear in your initialisation script as a single line. -Depending on your terminal characteristics, it may not appear that way in -this man page. If the above appears as more than one line, please treat any -newlines or indentation as a single space or TAB character.) - -If the options used at compile time are appropriate for your system, all -parameters except the desired debug level and "-D" may be omitted. See the -section "OPTIONS" above. -.SH RUNNING THE SERVER ON REQUEST -If your system uses a meta-daemon such as inetd, you can arrange to have the -smbd server started whenever a process attempts to connect to it. This requires -several changes to the startup files on the host machine. If you are -experimenting as an ordinary user rather than as root, you will need the -assistance of your system administrator to modify the system files. - -You will probably want to set up the name server -.B nmbd -at the same time as -the smbd - refer to the man page -.B nmbd(8). - -First, ensure that a port is configured in the file /etc/services. The -well-known port 139 should be used if possible, though any port may be used. - -Ensure that a line similar to the following is in /etc/services: - -.RS 3 -netbios-ssn 139/tcp -.RE - -Note for NIS/YP users - you may need to rebuild the NIS service maps rather -than alter your local /etc/services file. - -Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event -that you are using a meta-daemon other than inetd, you are on your own). Note -that the first item in this line matches the service name in /etc/services. -Substitute appropriate values for your system in this line (see -.B inetd(8)): - -.RS 3 -netbios-ssn stream tcp nowait root /usr/local/smb/smbd -d1 --l/var/adm/smblogs/log -s/usr/local/smb/smb.conf -.RE - -(The above should appear in /etc/inetd.conf as a single line. Depending on -your terminal characteristics, it may not appear that way in this man page. -If the above appears as more than one line, please treat any newlines or -indentation as a single space or TAB character.) - -Note that there is no need to specify a port number here, even if you are -using a non-standard port number. - -Lastly, edit the configuration file to provide suitable services. To start -with, the following two services should be all you need: - -.RS 3 -[homes] -.RS 3 - writable = yes -.RE - -[printers] -.RS 3 - writable = no - printable = yes - path = /tmp - public = yes -.RE -.RE - -This will allow you to connect to your home directory and print to any printer -supported by the host (user privileges permitting). -.SH TESTING THE INSTALLATION -If running the server as a daemon, execute it before proceeding. If -using a meta-daemon, either restart the system or kill and restart the -meta-daemon. Some versions of inetd will reread their configuration tables if -they receive a HUP signal. - -If your machine's name is "fred" and your name is "mary", you should now be -able to connect to the service "\\\\fred\\mary". - -To properly test and experiment with the server, we recommend using the -smbclient program (see -.B smbclient(1)). -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the server has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B hosts_access(5), -.B inetd(8), -.B nmbd(8), -.B smb.conf(5), -.B smbclient(1), -.B testparm(1), -.B testprns(1) - -.SH DIAGNOSTICS -[This section under construction] - -Most diagnostics issued by the server are logged in a specified log file. The -log file name is specified at compile time, but may be overridden on the -command line. - -The number and nature of diagnostics available depends on the debug level used -by the server. If you have problems, set the debug level to 3 and peruse the -log files. - -Most messages are reasonably self-explanatory. Unfortunately, at time of -creation of this man page the source code is still too fluid to warrant -describing each and every diagnostic. At this stage your best bet is still -to grep the source code and inspect the conditions that gave rise to the +.TP 0.2i +\(bu +\fBsmbd\fR (the server program) +installed in \fI/usr/local/samba/bin\fR +.TP 0.2i +\(bu +\fIsmb.conf\fR (the configuration +file) installed in \fI/usr/local/samba/lib\fR +.TP 0.2i +\(bu +log files stored in \fI/var/adm/smblogs +\fR.PP +The server may be run either as a daemon by users +or at startup, or it may be run from a meta-daemon such as +\fBinetd\fR upon request. If run as a daemon, +the server will always be ready, so starting sessions will be +faster. If run from a meta-daemon some memory will be saved and +utilities such as the tcpd TCP-wrapper may be used for extra +security. For serious use as file server it is recommended +that \fBsmbd\fR be run as a daemon. +.PP +.PP +When you've decided, continue with either +.PP +.TP 0.2i +\(bu +RUNNING THE SERVER AS A DAEMON or +.TP 0.2i +\(bu +RUNNING THE SERVER ON REQUEST. +.SH "RUNNING THE SERVER AS A DAEMON" +.PP +To run the server as a daemon from the command +line, simply put the \fB-D\fR option on the +command line. There is no need to place an ampersand at +the end of the command line - the \fB-D\fR +option causes the server to detach itself from the tty +anyway. +.PP +Any user can run the server as a daemon (execute +permissions permitting, of course). This is useful for +testing purposes, and may even be useful as a temporary +substitute for something like ftp. When run this way, however, +the server will only have the privileges of the user who ran +it. +.PP +To ensure that the server is run as a daemon whenever +the machine is started, and to ensure that it runs as root +so that it can serve multiple clients, you will need to modify +the system startup files. Wherever appropriate (for example, in +\fI/etc/rc\fR), insert the following line, +substituting port number, log file location, configuration file +location and debug level as desired: +.PP +\fB/usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log +-s /usr/local/samba/lib/smb.conf\fR +.PP +(The above should appear in your initialization script +as a single line. Depending on your terminal characteristics, +it may not appear that way in this man page. If the above appears +as more than one line, please treat any newlines or indentation +as a single space or TAB character.) +.PP +If the options used at compile time are appropriate for +your system, all parameters except \fB-D\fR may +be omitted. See the section OPTIONS above. +.SH "RUNNING THE SERVER ON REQUEST" +.PP +If your system uses a meta-daemon such as \fBinetd +\fR, you can arrange to have the \fBsmbd\fR server started +whenever a process attempts to connect to it. This requires several +changes to the startup files on the host machine. If you are +experimenting as an ordinary user rather than as root, you will +need the assistance of your system administrator to modify the +system files. +.PP +You will probably want to set up the NetBIOS name server +\fBnmbd\fRat +the same time as \fBsmbd\fR. To do this refer to the +man page for \fBnmbd(8)\fR +. +.PP +First, ensure that a port is configured in the file +\fI/etc/services\fR. The well-known port 139 +should be used if possible, though any port may be used. +.PP +Ensure that a line similar to the following is in +\fI/etc/services\fR: +.PP +\fBnetbios-ssn 139/tcp\fR +.PP +Note for NIS/YP users - you may need to rebuild the +NIS service maps rather than alter your local \fI/etc/services +\fRfile. +.PP +Next, put a suitable line in the file \fI/etc/inetd.conf +\fR(in the unlikely event that you are using a meta-daemon +other than inetd, you are on your own). Note that the first item +in this line matches the service name in \fI/etc/services +\fR\&. Substitute appropriate values for your system +in this line (see \fBinetd(8)\fR): +.PP +\fBnetbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd +-d1 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf\fR +.PP +(The above should appear in \fI/etc/inetd.conf\fR +as a single line. Depending on your terminal characteristics, it may +not appear that way in this man page. If the above appears as more +than one line, please treat any newlines or indentation as a single +space or TAB character.) +.PP +Note that there is no need to specify a port number here, +even if you are using a non-standard port number. +.PP +Lastly, edit the configuration file to provide suitable +services. To start with, the following two services should be +all you need: +.sp +.nf + [homes] + writeable = yes + + [printers] + writeable = no + printable = yes + path = /tmp + public = yes + + +.sp +.fi +.PP +This will allow you to connect to your home directory +and print to any printer supported by the host (user privileges +permitting). +.SH "PAM INTERACTION" +.PP +Samba uses PAM for authentication (when presented with a plaintext +password), for account checking (is this account disabled?) and for +session management. The degree too which samba supports PAM is restricted +by the limitations of the SMB protocol and the +obey pam restricions +smb.conf paramater. When this is set, the following restrictions apply: +.TP 0.2i +\(bu +\fBAccount Validation\fR: All acccesses to a +samba server are checked +against PAM to see if the account is vaild, not disabled and is permitted to +login at this time. This also applies to encrypted logins. +.TP 0.2i +\(bu +\fBSession Management\fR: When not using share +level secuirty, users must pass PAM's session checks before access +is granted. Note however, that this is bypassed in share level secuirty. +Note also that some older pam configuration files may need a line +added for session support. +.SH "TESTING THE INSTALLATION" +.PP +If running the server as a daemon, execute it before +proceeding. If using a meta-daemon, either restart the system +or kill and restart the meta-daemon. Some versions of +\fBinetd\fR will reread their configuration +tables if they receive a HUP signal. +.PP +If your machine's name is \fIfred\fR and your +name is \fImary\fR, you should now be able to connect +to the service \fI\\\\fred\\mary\fR. +.PP +To properly test and experiment with the server, we +recommend using the \fBsmbclient\fR program (see +\fBsmbclient(1)\fR) +and also going through the steps outlined in the file +\fIDIAGNOSIS.txt\fR in the \fIdocs/\fR +directory of your Samba installation. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "DIAGNOSTICS" +.PP +Most diagnostics issued by the server are logged +in a specified log file. The log file name is specified +at compile time, but may be overridden on the command line. +.PP +The number and nature of diagnostics available depends +on the debug level used by the server. If you have problems, set +the debug level to 3 and peruse the log files. +.PP +Most messages are reasonably self-explanatory. Unfortunately, +at the time this man page was created, there are too many diagnostics +available in the source code to warrant describing each and every +diagnostic. At this stage your best bet is still to grep the +source code and inspect the conditions that gave rise to the diagnostics you are seeing. - -.SH BUGS -None known. -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -This man page written by Karl Auer (Karl.Auer@anu.edu.au) - -See -.B smb.conf(5) for a full list of contributors and details on how to -submit bug reports, comments etc. +.SH "SIGNALS" +.PP +Sending the \fBsmbd\fR a SIGHUP will cause it to +reload its \fIsmb.conf\fR configuration +file within a short period of time. +.PP +To shut down a user's \fBsmbd\fR process it is recommended +that \fBSIGKILL (-9)\fR \fBNOT\fR +be used, except as a last resort, as this may leave the shared +memory area in an inconsistent state. The safe way to terminate +an \fBsmbd\fR is to send it a SIGTERM (-15) signal and wait for +it to die on its own. +.PP +The debug log level of \fBsmbd\fR may be raised +or lowered using \fBsmbcontrol(1) +\fRprogram (SIGUSR[1|2] signals are no longer used in +Samba 2.2). This is to allow transient problems to be diagnosed, +whilst still running at a normally low log level. +.PP +Note that as the signal handlers send a debug write, +they are not re-entrant in \fBsmbd\fR. This you should wait until +\fBsmbd\fR is in a state of waiting for an incoming SMB before +issuing them. It is possible to make the signal handlers safe +by un-blocking the signals before the select call and re-blocking +them after, however this would affect performance. +.SH "SEE ALSO" +.PP +hosts_access(5), \fBinetd(8)\fR, +\fBnmbd(8)\fR, +\fIsmb.conf(5)\fR +, \fBsmbclient(1) +\fR, and the Internet RFC's +\fIrfc1001.txt\fR, \fIrfc1002.txt\fR. +In addition the CIFS (formerly SMB) specification is available +as a link from the Web page +http://samba.org/cifs/ <URL:http://samba.org/cifs/>. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbmnt.8 b/docs/manpages/smbmnt.8 new file mode 100644 index 00000000000..bab134ef54e --- /dev/null +++ b/docs/manpages/smbmnt.8 @@ -0,0 +1,63 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBMNT" "8" "06 December 2001" "" "" +.SH NAME +smbmnt \- helper utility for mounting SMB filesystems +.SH SYNOPSIS +.sp +\fBsmbmnt\fR \fBmount-point\fR [ \fB-s <share>\fR ] [ \fB-r\fR ] [ \fB-u <uid>\fR ] [ \fB-g <gid>\fR ] [ \fB-f <mask>\fR ] [ \fB-d <mask>\fR ] [ \fB-o <options>\fR ] +.SH "DESCRIPTION" +.PP +\fBsmbmnt\fR is a helper application used +by the smbmount program to do the actual mounting of SMB shares. +\fBsmbmnt\fR can be installed setuid root if you want +normal users to be able to mount their SMB shares. +.PP +A setuid smbmnt will only allow mounts on directories owned +by the user, and that the user has write permission on. +.PP +The \fBsmbmnt\fR program is normally invoked +by \fBsmbmount(8)\fR +. It should not be invoked directly by users. +.PP +smbmount searches the normal PATH for smbmnt. You must ensure +that the smbmnt version in your path matches the smbmount used. +.SH "OPTIONS" +.TP +\fB-r\fR +mount the filesystem read-only +.TP +\fB-u uid\fR +specify the uid that the files will +be owned by +.TP +\fB-g gid\fR +specify the gid that the files will be +owned by +.TP +\fB-f mask\fR +specify the octal file mask applied +.TP +\fB-d mask\fR +specify the octal directory mask +applied +.TP +\fB-o options\fR +list of options that are passed as-is to smbfs, if this +command is run on a 2.4 or higher Linux kernel. +.SH "AUTHOR" +.PP +Volker Lendecke, Andrew Tridgell, Michael H. Warfield +and others. +.PP +The current maintainer of smbfs and the userspace +tools \fBsmbmount\fR, \fBsmbumount\fR, +and \fBsmbmnt\fR is Urban Widmark <URL:mailto:urban@teststation.com>. +The SAMBA Mailing list <URL:mailto:samba@samba.org> +is the preferred place to ask questions regarding these programs. +.PP +The conversion of this manpage for Samba 2.2 was performed +by Gerald Carter diff --git a/docs/manpages/smbmount.8 b/docs/manpages/smbmount.8 new file mode 100644 index 00000000000..70a0911887a --- /dev/null +++ b/docs/manpages/smbmount.8 @@ -0,0 +1,216 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBMOUNT" "8" "06 December 2001" "" "" +.SH NAME +smbmount \- mount an smbfs filesystem +.SH SYNOPSIS +.sp +\fBsmbumount\fR \fBservice\fR \fBmount-point\fR [ \fB-o options\fR ] +.SH "DESCRIPTION" +.PP +\fBsmbmount\fR mounts a Linux SMB filesystem. It +is usually invoked as \fBmount.smbfs\fR by +the \fBmount(8)\fR command when using the +"-t smbfs" option. This command only works in Linux, and the kernel must +support the smbfs filesystem. +.PP +Options to \fBsmbmount\fR are specified as a comma-separated +list of key=value pairs. It is possible to send options other +than those listed here, assuming that smbfs supports them. If +you get mount failures, check your kernel log for errors on +unknown options. +.PP +\fBsmbmount\fR is a daemon. After mounting it keeps running until +the mounted smbfs is umounted. It will log things that happen +when in daemon mode using the "machine name" smbmount, so +typically this output will end up in \fIlog.smbmount\fR. The +\fBsmbmount\fR process may also be called mount.smbfs. +.PP +\fBNOTE:\fR \fBsmbmount\fR +calls \fBsmbmnt(8)\fR to do the actual mount. You +must make sure that \fBsmbmnt\fR is in the path so +that it can be found. +.SH "OPTIONS" +.TP +\fBusername=<arg>\fR +specifies the username to connect as. If +this is not given, then the environment variable \fB USER\fR is used. This option can also take the +form "user%password" or "user/workgroup" or +"user/workgroup%password" to allow the password and workgroup +to be specified as part of the username. +.TP +\fBpassword=<arg>\fR +specifies the SMB password. If this +option is not given then the environment variable +\fBPASSWD\fR is used. If it can find +no password \fBsmbmount\fR will prompt +for a passeword, unless the guest option is +given. + +Note that password which contain the arguement delimiter +character (i.e. a comma ',') will failed to be parsed correctly +on the command line. However, the same password defined +in the PASSWD environment variable or a credentials file (see +below) will be read correctly. +.TP +\fBcredentials=<filename>\fR +specifies a file that contains a username +and/or password. The format of the file is: + +.sp +.nf + username = <value> + password = <value> + +.sp +.fi + +This is preferred over having passwords in plaintext in a +shared file, such as \fI/etc/fstab\fR. Be sure to protect any +credentials file properly. +.TP +\fBnetbiosname=<arg>\fR +sets the source NetBIOS name. It defaults +to the local hostname. +.TP +\fBuid=<arg>\fR +sets the uid that will own all files on +the mounted filesystem. +It may be specified as either a username or a numeric uid. +.TP +\fBgid=<arg>\fR +sets the gid that will own all files on +the mounted filesystem. +It may be specified as either a groupname or a numeric +gid. +.TP +\fBport=<arg>\fR +sets the remote SMB port number. The default +is 139. +.TP +\fBfmask=<arg>\fR +sets the file mask. This determines the +permissions that remote files have in the local filesystem. +The default is based on the current umask. +.TP +\fBdmask=<arg>\fR +sets the directory mask. This determines the +permissions that remote directories have in the local filesystem. +The default is based on the current umask. +.TP +\fBdebug=<arg>\fR +sets the debug level. This is useful for +tracking down SMB connection problems. A suggested value to +start with is 4. If set too high there will be a lot of +output, possibly hiding the useful output. +.TP +\fBip=<arg>\fR +sets the destination host or IP address. +.TP +\fBworkgroup=<arg>\fR +sets the workgroup on the destination +.TP +\fBsockopt=<arg>\fR +sets the TCP socket options. See the \fIsmb.conf +\fR\fIsocket options\fR option. +.TP +\fBscope=<arg>\fR +sets the NetBIOS scope +.TP +\fBguest\fR +don't prompt for a password +.TP +\fBro\fR +mount read-only +.TP +\fBrw\fR +mount read-write +.TP +\fBiocharset=<arg>\fR +sets the charset used by the Linux side for codepage +to charset translations (NLS). Argument should be the +name of a charset, like iso8859-1. (Note: only kernel +2.4.0 or later) +.TP +\fBcodepage=<arg>\fR +sets the codepage the server uses. See the iocharset +option. Example value cp850. (Note: only kernel 2.4.0 +or later) +.TP +\fBttl=<arg>\fR +how long a directory listing is cached in milliseconds +(also affects visibility of file size and date +changes). A higher value means that changes on the +server take longer to be noticed but it can give +better performance on large directories, especially +over long distances. Default is 1000ms but something +like 10000ms (10 seconds) is probably more reasonable +in many cases. +(Note: only kernel 2.4.2 or later) +.SH "ENVIRONMENT VARIABLES" +.PP +The variable \fBUSER\fR may contain the username of the +person using the client. This information is used only if the +protocol level is high enough to support session-level +passwords. The variable can be used to set both username and +password by using the format username%password. +.PP +The variable \fBPASSWD\fR may contain the password of the +person using the client. This information is used only if the +protocol level is high enough to support session-level +passwords. +.PP +The variable \fBPASSWD_FILE\fR may contain the pathname +of a file to read the password from. A single line of input is +read and used as the password. +.SH "BUGS" +.PP +Passwords and other options containing , can not be handled. +For passwords an alternative way of passing them is in a credentials +file or in the PASSWD environment. +.PP +The credentials file does not handle usernames or passwords with +leading space. +.PP +One smbfs bug is important enough to mention here, even if it +is a bit misplaced: +.TP 0.2i +\(bu +Mounts sometimes stop working. This is usually +caused by smbmount terminating. Since smbfs needs smbmount to +reconnect when the server disconnects, the mount will eventually go +dead. An umount/mount normally fixes this. At least 2 ways to +trigger this bug are known. +.PP +Note that the typical response to a bug report is suggestion +to try the latest version first. So please try doing that first, +and always include which versions you use of relevant software +when reporting bugs (minimum: samba, kernel, distribution) +.PP +.SH "SEE ALSO" +.PP +Documentation/filesystems/smbfs.txt in the linux kernel +source tree may contain additional options and information. +.PP +FreeBSD also has a smbfs, but it is not related to smbmount +.PP +For Solaris, HP-UX and others you may want to look at +\fBsmbsh(1)\fRor at other +solutions, such as sharity or perhaps replacing the SMB server with +a NFS server. +.SH "AUTHOR" +.PP +Volker Lendecke, Andrew Tridgell, Michael H. Warfield +and others. +.PP +The current maintainer of smbfs and the userspace +tools \fBsmbmount\fR, \fBsmbumount\fR, +and \fBsmbmnt\fR is Urban Widmark <URL:mailto:urban@teststation.com>. +The SAMBA Mailing list <URL:mailto:samba@samba.org> +is the preferred place to ask questions regarding these programs. +.PP +The conversion of this manpage for Samba 2.2 was performed +by Gerald Carter diff --git a/docs/manpages/smbpasswd.5 b/docs/manpages/smbpasswd.5 new file mode 100644 index 00000000000..b1adf080e7e --- /dev/null +++ b/docs/manpages/smbpasswd.5 @@ -0,0 +1,159 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBPASSWD" "5" "06 December 2001" "" "" +.SH NAME +smbpasswd \- The Samba encrypted password file +.SH SYNOPSIS +.PP +\fIsmbpasswd\fR +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +smbpasswd is the Samba encrypted password file. It contains +the username, Unix user id and the SMB hashed passwords of the +user, as well as account flag information and the time the +password was last changed. This file format has been evolving with +Samba and has had several different formats in the past. +.SH "FILE FORMAT" +.PP +The format of the smbpasswd file used by Samba 2.2 +is very similar to the familiar Unix \fIpasswd(5)\fR +file. It is an ASCII file containing one line for each user. Each field +ithin each line is separated from the next by a colon. Any entry +beginning with '#' is ignored. The smbpasswd file contains the +following information for each user: +.TP +\fBname\fR +This is the user name. It must be a name that +already exists in the standard UNIX passwd file. +.TP +\fBuid\fR +This is the UNIX uid. It must match the uid +field for the same user entry in the standard UNIX passwd file. +If this does not match then Samba will refuse to recognize +this smbpasswd file entry as being valid for a user. +.TP +\fBLanman Password Hash\fR +This is the LANMAN hash of the user's password, +encoded as 32 hex digits. The LANMAN hash is created by DES +encrypting a well known string with the user's password as the +DES key. This is the same password used by Windows 95/98 machines. +Note that this password hash is regarded as weak as it is +vulnerable to dictionary attacks and if two users choose the +same password this entry will be identical (i.e. the password +is not "salted" as the UNIX password is). If the user has a +null password this field will contain the characters "NO PASSWORD" +as the start of the hex string. If the hex string is equal to +32 'X' characters then the user's account is marked as +disabled and the user will not be able to +log onto the Samba server. + +\fBWARNING !!\fR Note that, due to +the challenge-response nature of the SMB/CIFS authentication +protocol, anyone with a knowledge of this password hash will +be able to impersonate the user on the network. For this +reason these hashes are known as \fBplain text +equivalents\fR and must \fBNOT\fR be made +available to anyone but the root user. To protect these passwords +the smbpasswd file is placed in a directory with read and +traverse access only to the root user and the smbpasswd file +itself must be set to be read/write only by root, with no +other access. +.TP +\fBNT Password Hash\fR +This is the Windows NT hash of the user's +password, encoded as 32 hex digits. The Windows NT hash is +created by taking the user's password as represented in +16-bit, little-endian UNICODE and then applying the MD4 +(internet rfc1321) hashing algorithm to it. + +This password hash is considered more secure than +the LANMAN Password Hash as it preserves the case of the +password and uses a much higher quality hashing algorithm. +However, it is still the case that if two users choose the same +password this entry will be identical (i.e. the password is +not "salted" as the UNIX password is). + +\fBWARNING !!\fR. Note that, due to +the challenge-response nature of the SMB/CIFS authentication +protocol, anyone with a knowledge of this password hash will +be able to impersonate the user on the network. For this +reason these hashes are known as \fBplain text +equivalents\fR and must \fBNOT\fR be made +available to anyone but the root user. To protect these passwords +the smbpasswd file is placed in a directory with read and +traverse access only to the root user and the smbpasswd file +itself must be set to be read/write only by root, with no +other access. +.TP +\fBAccount Flags\fR +This section contains flags that describe +the attributes of the users account. In the Samba 2.2 release +this field is bracketed by '[' and ']' characters and is always +13 characters in length (including the '[' and ']' characters). +The contents of this field may be any of the characters. +.RS +.TP 0.2i +\(bu +\fBU\fR - This means +this is a "User" account, i.e. an ordinary user. Only User +and Workstation Trust accounts are currently supported +in the smbpasswd file. +.TP 0.2i +\(bu +\fBN\fR - This means the +account has no password (the passwords in the fields LANMAN +Password Hash and NT Password Hash are ignored). Note that this +will only allow users to log on with no password if the \fI null passwords\fR parameter is set in the \fIsmb.conf(5) +\fRconfig file. +.TP 0.2i +\(bu +\fBD\fR - This means the account +is disabled and no SMB/CIFS logins will be allowed for +this user. +.TP 0.2i +\(bu +\fBW\fR - This means this account +is a "Workstation Trust" account. This kind of account is used +in the Samba PDC code stream to allow Windows NT Workstations +and Servers to join a Domain hosted by a Samba PDC. +.RE +.PP +Other flags may be added as the code is extended in future. +The rest of this field space is filled in with spaces. +.PP +.TP +\fBLast Change Time\fR +This field consists of the time the account was +last modified. It consists of the characters 'LCT-' (standing for +"Last Change Time") followed by a numeric encoding of the UNIX time +in seconds since the epoch (1970) that the last change was made. +.PP +All other colon separated fields are ignored at this time. +.PP +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbpasswd(8)\fR, +samba(7), and +the Internet RFC1321 for details on the MD4 algorithm. +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbpasswd.8 b/docs/manpages/smbpasswd.8 new file mode 100644 index 00000000000..8e5be46e318 --- /dev/null +++ b/docs/manpages/smbpasswd.8 @@ -0,0 +1,313 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBPASSWD" "8" "06 December 2001" "" "" +.SH NAME +smbpasswd \- change a user's SMB password +.SH SYNOPSIS +.sp +\fBsmbpasswd\fR [ \fB-a\fR ] [ \fB-x\fR ] [ \fB-d\fR ] [ \fB-e\fR ] [ \fB-D debuglevel\fR ] [ \fB-n\fR ] [ \fB-r <remote machine>\fR ] [ \fB-R <name resolve order>\fR ] [ \fB-m\fR ] [ \fB-j DOMAIN\fR ] [ \fB-U username[%password]\fR ] [ \fB-h\fR ] [ \fB-s\fR ] [ \fB-w pass\fR ] [ \fBusername\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +The smbpasswd program has several different +functions, depending on whether it is run by the \fBroot\fR +user or not. When run as a normal user it allows the user to change +the password used for their SMB sessions on any machines that store +SMB passwords. +.PP +By default (when run with no arguments) it will attempt to +change the current user's SMB password on the local machine. This is +similar to the way the \fBpasswd(1)\fR program works. +\fBsmbpasswd\fR differs from how the passwd program works +however in that it is not \fBsetuid root\fR but works in +a client-server mode and communicates with a locally running +\fBsmbd(8)\fR. As a consequence in order for this to +succeed the smbd daemon must be running on the local machine. On a +UNIX machine the encrypted SMB passwords are usually stored in +the \fIsmbpasswd(5)\fR file. +.PP +When run by an ordinary user with no options. smbpasswd +will prompt them for their old SMB password and then ask them +for their new password twice, to ensure that the new password +was typed correctly. No passwords will be echoed on the screen +whilst being typed. If you have a blank SMB password (specified by +the string "NO PASSWORD" in the smbpasswd file) then just press +the <Enter> key when asked for your old password. +.PP +smbpasswd can also be used by a normal user to change their +SMB password on remote machines, such as Windows NT Primary Domain +Controllers. See the (-r) and -U options below. +.PP +When run by root, smbpasswd allows new users to be added +and deleted in the smbpasswd file, as well as allows changes to +the attributes of the user in this file to be made. When run by root, +\fBsmbpasswd\fR accesses the local smbpasswd file +directly, thus enabling changes to be made even if smbd is not +running. +.SH "OPTIONS" +.TP +\fB-a\fR +This option specifies that the username +following should be added to the local smbpasswd file, with the +new password typed (type <Enter> for the old password). This +option is ignored if the username following already exists in +the smbpasswd file and it is treated like a regular change +password command. Note that the user to be added must already exist +in the system password file (usually \fI/etc/passwd\fR) +else the request to add the user will fail. + +This option is only available when running smbpasswd +as root. +.TP +\fB-x\fR +This option specifies that the username +following should be deleted from the local smbpasswd file. + +This option is only available when running smbpasswd as +root. +.TP +\fB-d\fR +This option specifies that the username following +should be disabled in the local smbpasswd +file. This is done by writing a 'D' flag +into the account control space in the smbpasswd file. Once this +is done all attempts to authenticate via SMB using this username +will fail. + +If the smbpasswd file is in the 'old' format (pre-Samba 2.0 +format) there is no space in the user's password entry to write +this information and so the user is disabled by writing 'X' characters +into the password space in the smbpasswd file. See \fBsmbpasswd(5) +\fRfor details on the 'old' and new password file formats. + +This option is only available when running smbpasswd as +root. +.TP +\fB-e\fR +This option specifies that the username following +should be enabled in the local smbpasswd file, +if the account was previously disabled. If the account was not +disabled this option has no effect. Once the account is enabled then +the user will be able to authenticate via SMB once again. + +If the smbpasswd file is in the 'old' format, then \fB smbpasswd\fR will prompt for a new password for this user, +otherwise the account will be enabled by removing the 'D' +flag from account control space in the \fI smbpasswd\fR file. See \fBsmbpasswd (5)\fR for +details on the 'old' and new password file formats. + +This option is only available when running smbpasswd as root. +.TP +\fB-D debuglevel\fR +\fIdebuglevel\fR is an integer +from 0 to 10. The default value if this parameter is not specified +is zero. + +The higher this value, the more detail will be logged to the +log files about the activities of smbpasswd. At level 0, only +critical errors and serious warnings will be logged. + +Levels above 1 will generate considerable amounts of log +data, and should only be used when investigating a problem. Levels +above 3 are designed for use only by developers and generate +HUGE amounts of log data, most of which is extremely cryptic. +.TP +\fB-n\fR +This option specifies that the username following +should have their password set to null (i.e. a blank password) in +the local smbpasswd file. This is done by writing the string "NO +PASSWORD" as the first part of the first password stored in the +smbpasswd file. + +Note that to allow users to logon to a Samba server once +the password has been set to "NO PASSWORD" in the smbpasswd +file the administrator must set the following parameter in the [global] +section of the \fIsmb.conf\fR file : + +\fBnull passwords = yes\fR + +This option is only available when running smbpasswd as +root. +.TP +\fB-r remote machine name\fR +This option allows a user to specify what machine +they wish to change their password on. Without this parameter +smbpasswd defaults to the local host. The \fIremote +machine name\fR is the NetBIOS name of the SMB/CIFS +server to contact to attempt the password change. This name is +resolved into an IP address using the standard name resolution +mechanism in all programs of the Samba suite. See the \fI-R +name resolve order\fR parameter for details on changing +this resolving mechanism. + +The username whose password is changed is that of the +current UNIX logged on user. See the \fI-U username\fR +parameter for details on changing the password for a different +username. + +Note that if changing a Windows NT Domain password the +remote machine specified must be the Primary Domain Controller for +the domain (Backup Domain Controllers only have a read-only +copy of the user account database and will not allow the password +change). + +\fBNote\fR that Windows 95/98 do not have +a real password database so it is not possible to change passwords +specifying a Win95/98 machine as remote machine target. +.TP +\fB-R name resolve order\fR +This option allows the user of smbpasswd to determine +what name resolution services to use when looking up the NetBIOS +name of the host being connected to. + +The options are :"lmhosts", "host", "wins" and "bcast". They cause +names to be resolved as follows : +.RS +.TP 0.2i +\(bu +lmhosts : Lookup an IP +address in the Samba lmhosts file. If the line in lmhosts has +no name type attached to the NetBIOS name (see the lmhosts(5)for details) then +any name type matches for lookup. +.TP 0.2i +\(bu +host : Do a standard host +name to IP address resolution, using the system \fI/etc/hosts +\fR, NIS, or DNS lookups. This method of name resolution +is operating system depended for instance on IRIX or Solaris this +may be controlled by the \fI/etc/nsswitch.conf\fR +file). Note that this method is only used if the NetBIOS name +type being queried is the 0x20 (server) name type, otherwise +it is ignored. +.TP 0.2i +\(bu +wins : Query a name with +the IP address listed in the \fIwins server\fR +parameter. If no WINS server has been specified this method +will be ignored. +.TP 0.2i +\(bu +bcast : Do a broadcast on +each of the known local interfaces listed in the +\fIinterfaces\fR parameter. This is the least +reliable of the name resolution methods as it depends on the +target host being on a locally connected subnet. +.RE +.PP +The default order is \fBlmhosts, host, wins, bcast\fR +and without this parameter or any entry in the +\fIsmb.conf\fR file the name resolution methods will +be attempted in this order. +.PP +.TP +\fB-m\fR +This option tells smbpasswd that the account +being changed is a MACHINE account. Currently this is used +when Samba is being used as an NT Primary Domain Controller. + +This option is only available when running smbpasswd as root. +.TP +\fB-j DOMAIN\fR +This option is used to add a Samba server +into a Windows NT Domain, as a Domain member capable of authenticating +user accounts to any Domain Controller in the same way as a Windows +NT Server. See the \fBsecurity = domain\fR option in +the \fIsmb.conf(5)\fR man page. + +In order to be used in this way, the Administrator for +the Windows NT Domain must have used the program "Server Manager +for Domains" to add the primary NetBIOS name of the Samba server +as a member of the Domain. + +After this has been done, to join the Domain invoke \fB smbpasswd\fR with this parameter. smbpasswd will then +look up the Primary Domain Controller for the Domain (found in +the \fIsmb.conf\fR file in the parameter +\fIpassword server\fR and change the machine account +password used to create the secure Domain communication. This +password is then stored by smbpasswd in a TDB, writeable only by root, +called \fIsecrets.tdb\fR + +Once this operation has been performed the \fI smb.conf\fR file may be updated to set the \fB security = domain\fR option and all future logins +to the Samba server will be authenticated to the Windows NT +PDC. + +Note that even though the authentication is being +done to the PDC all users accessing the Samba server must still +have a valid UNIX account on that machine. + +This option is only available when running smbpasswd as root. +.TP +\fB-U username\fR +This option may only be used in conjunction +with the \fI-r\fR option. When changing +a password on a remote machine it allows the user to specify +the user name on that machine whose password will be changed. It +is present to allow users who have different user names on +different systems to change these passwords. +.TP +\fB-h\fR +This option prints the help string for \fB smbpasswd\fR, selecting the correct one for running as root +or as an ordinary user. +.TP +\fB-s\fR +This option causes smbpasswd to be silent (i.e. +not issue prompts) and to read its old and new passwords from +standard input, rather than from \fI/dev/tty\fR +(like the \fBpasswd(1)\fR program does). This option +is to aid people writing scripts to drive smbpasswd +.TP +\fB-w password\fR +This parameter is only available is Samba +has been configured to use the experiemental +\fB--with-ldapsam\fR option. The \fI-w\fR +switch is used to specify the password to be used with the +\fIldap admin +dn\fR. Note that the password is stored in +the \fIprivate/secrets.tdb\fR and is keyed off +of the admin's DN. This means that if the value of \fIldap +admin dn\fR ever changes, the password will beed to be +manually updated as well. +.TP +\fBusername\fR +This specifies the username for all of the +\fBroot only\fR options to operate on. Only root +can specify this parameter as only root has the permission needed +to modify attributes directly in the local smbpasswd file. +.SH "NOTES" +.PP +Since \fBsmbpasswd\fR works in client-server +mode communicating with a local smbd for a non-root user then +the smbd daemon must be running for this to work. A common problem +is to add a restriction to the hosts that may access the \fB smbd\fR running on the local machine by specifying a +\fIallow hosts\fR or \fIdeny hosts\fR +entry in the \fIsmb.conf\fR file and neglecting to +allow "localhost" access to the smbd. +.PP +In addition, the smbpasswd command is only useful if Samba +has been set up to use encrypted passwords. See the file +\fIENCRYPTION.txt\fR in the docs directory for details +on how to do this. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fIsmbpasswd(5)\fR, +samba(7) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbrun.1 b/docs/manpages/smbrun.1 deleted file mode 100644 index 1608d3bb345..00000000000 --- a/docs/manpages/smbrun.1 +++ /dev/null @@ -1,70 +0,0 @@ -.TH SMBRUN 1 17/1/1995 smbrun smbrun -.SH NAME -smbrun \- interface program between smbd and external programs -.SH SYNOPSIS -.B smbrun -.I shell-command -.SH DESCRIPTION -This program is part of the Samba suite. - -.B smbrun -is a very small 'glue' program, which runs shell commands for -the -.B smbd -daemon (see -.B smbd(8)). - -It first changes to the highest effective user and group ID that it can, -then runs the command line provided using the system() call. This program is -necessary to allow some operating systems to run external programs as non-root. -.SH OPTIONS -.I shell-command - -.RS 3 -The shell command to execute. - -The command should have a fully-qualified path. -.RE -.SH ENVIRONMENT VARIABLES -The PATH variable set for the environment in which -.B smbrun -is executed will affect what executables are located and executed if a -fully-qualified path is not given in the command. - -.SH INSTALLATION -The location of the server and its support files is a matter for individual -system administrators. The following are thus suggestions only. - -It is recommended that the -.B smbrun -program be installed under the /usr/local hierarchy, in a directory readable -by all, writeable only by root. The program should be executable by all. -The program should NOT be setuid or setgid! -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the program has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B smbd(8), -.B smb.conf(8) -.SH DIAGNOSTICS -If smbrun cannot be located or cannot be executed by -.B smbd -then appropriate messages will be found in the smbd logs. Other diagnostics are -dependent on the shell-command being run. It is advisable for your shell -commands to issue suitable diagnostics to aid trouble-shooting. -.SH BUGS -None known. -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -This man page was written by Karl Auer (Karl.Auer@anu.edu.au) - -See -.B smb.conf(5) for a full list of contributors and details of how to -submit bug reports, comments etc. diff --git a/docs/manpages/smbsh.1 b/docs/manpages/smbsh.1 new file mode 100644 index 00000000000..349853bbc7c --- /dev/null +++ b/docs/manpages/smbsh.1 @@ -0,0 +1,74 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBSH" "1" "06 December 2001" "" "" +.SH NAME +smbsh \- Allows access to Windows NT filesystem using UNIX commands +.SH SYNOPSIS +.sp +\fBsmbsh\fR +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBsmbsh\fR allows you to access an NT filesystem +using UNIX commands such as \fBls\fR, \fB egrep\fR, and \fBrcp\fR. You must use a +shell that is dynamically linked in order for \fBsmbsh\fR +to work correctly. +.PP +To use the \fBsmbsh\fR command, execute \fB smbsh\fR from the prompt and enter the username and password +that authenticates you to the machine running the Windows NT +operating system. +.PP +.sp +.nf + system% \fBsmbsh\fR + Username: \fBuser\fR + Password: \fBXXXXXXX\fR + +.sp +.fi +.PP +Any dynamically linked command you execute from +this shell will access the \fI/smb\fR directory +using the smb protocol. For example, the command \fBls /smb +\fRwill show a list of workgroups. The command +\fBls /smb/MYGROUP \fR will show all the machines in +the workgroup MYGROUP. The command +\fBls /smb/MYGROUP/<machine-name>\fR will show the share +names for that machine. You could then, for example, use the \fB cd\fR command to change directories, \fBvi\fR to +edit files, and \fBrcp\fR to copy files. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "BUGS" +.PP +\fBsmbsh\fR works by intercepting the standard +libc calls with the dynamically loaded versions in \fI smbwrapper.o\fR. Not all calls have been "wrapped", so +some programs may not function correctly under \fBsmbsh +\fR\&. +.PP +Programs which are not dynamically linked cannot make +use of \fBsmbsh\fR's functionality. Most versions +of UNIX have a \fBfile\fR command that will +describe how a program was linked. +.SH "SEE ALSO" +.PP +\fBsmbd(8)\fR, +smb.conf(5) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbspool.8 b/docs/manpages/smbspool.8 new file mode 100644 index 00000000000..864ea348f26 --- /dev/null +++ b/docs/manpages/smbspool.8 @@ -0,0 +1,102 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBSPOOL" "8" "06 December 2001" "" "" +.SH NAME +smbspool \- send print file to an SMB printer +.SH SYNOPSIS +.sp +\fBsmbspool\fR [ \fBjob\fR ] [ \fBuser\fR ] [ \fBtitle\fR ] [ \fBcopies\fR ] [ \fBoptions\fR ] [ \fBfilename\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +smbspool is a very small print spooling program that +sends a print file to an SMB printer. The command-line arguments +are position-dependent for compatibility with the Common UNIX +Printing System, but you can use smbspool with any printing system +or from a program or script. +.PP +\fBDEVICE URI\fR +.PP +smbspool specifies the destination using a Uniform Resource +Identifier ("URI") with a method of "smb". This string can take +a number of forms: +.TP 0.2i +\(bu +smb://server/printer +.TP 0.2i +\(bu +smb://workgroup/server/printer +.TP 0.2i +\(bu +smb://username:password@server/printer +.TP 0.2i +\(bu +smb://username:password@workgroup/server/printer +.PP +smbspool tries to get the URI from argv[0]. If argv[0] +contains the name of the program then it looks in the \fB DEVICE_URI\fR environment variable. +.PP +.PP +Programs using the \fBexec(2)\fR functions can +pass the URI in argv[0], while shell scripts must set the +\fBDEVICE_URI\fR environment variable prior to +running smbspool. +.PP +.SH "OPTIONS" +.TP 0.2i +\(bu +The job argument (argv[1]) contains the +job ID number and is presently not used by smbspool. +.TP 0.2i +\(bu +The user argument (argv[2]) contains the +print user's name and is presently not used by smbspool. +.TP 0.2i +\(bu +The title argument (argv[3]) contains the +job title string and is passed as the remote file name +when sending the print job. +.TP 0.2i +\(bu +The copies argument (argv[4]) contains +the number of copies to be printed of the named file. If +no filename is provided than this argument is not used by +smbspool. +.TP 0.2i +\(bu +The options argument (argv[5]) contains +the print options in a single string and is presently +not used by smbspool. +.TP 0.2i +\(bu +The filename argument (argv[6]) contains the +name of the file to print. If this argument is not specified +then the print file is read from the standard input. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbd(8)\fR, +and samba(7). +.SH "AUTHOR" +.PP +\fBsmbspool\fR was written by Michael Sweet +at Easy Software Products. +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbstatus.1 b/docs/manpages/smbstatus.1 index 76dc50cbb53..17c1df25e54 100644 --- a/docs/manpages/smbstatus.1 +++ b/docs/manpages/smbstatus.1 @@ -1,52 +1,70 @@ -.TH SMBSTATUS 1 17/1/1995 smbstatus smbstatus +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBSTATUS" "1" "06 December 2001" "" "" .SH NAME smbstatus \- report on current Samba connections .SH SYNOPSIS -.B smbstatus -[-d] -[-s -.I configuration file -] -.SH DESCRIPTION -This program is part of the Samba suite. - -.B smbstatus -is a very simple program to list the current Samba connections - -Just run the program and the output is self explanatory. You can offer -a configuration filename to override the default. The default is -CONFIGFILE from the Makefile. - -Option -.I -d +.sp +\fBsmbstatus\fR [ \fB-P\fR ] [ \fB-b\fR ] [ \fB-d\fR ] [ \fB-L\fR ] [ \fB-p\fR ] [ \fB-S\fR ] [ \fB-s <configuration file>\fR ] [ \fB-u <username>\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBsmbstatus\fR is a very simple program to +list the current Samba connections. +.SH "OPTIONS" +.TP +\fB-P\fR +If samba has been compiled with the +profiling option, print only the contents of the profiling +shared memory area. +.TP +\fB-b\fR +gives brief output. +.TP +\fB-d\fR gives verbose output. - -.I -p -print a list of smbd processes and exit. Useful for scripting. - -.SH ENVIRONMENT VARIABLES -Not applicable. - -.SH INSTALLATION -The location of the server and its support files is a matter for individual -system administrators. The following are thus suggestions only. - -It is recommended that the -.B smbstatus -program be installed under the /usr/local hierarchy, in a directory readable -by all, writeable only by root. The program itself should be executable by all. - -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the program has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B smb.conf(5), -.B smbd(8) - -See -.B smb.conf(5) for a full list of contributors and details on how to -submit bug reports, comments etc. +.TP +\fB-L\fR +causes smbstatus to only list locks. +.TP +\fB-p\fR +print a list of \fBsmbd(8)\fRprocesses and exit. +Useful for scripting. +.TP +\fB-S\fR +causes smbstatus to only list shares. +.TP +\fB-s <configuration file>\fR +The default configuration file name is +determined at compile time. The file specified contains the +configuration details required by the server. See \fIsmb.conf(5)\fR +for more information. +.TP +\fB-u <username>\fR +selects information relevant to +\fIusername\fR only. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbd(8)\fRand +smb.conf(5). +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/smbtar.1 b/docs/manpages/smbtar.1 index 0f1c38c271f..8e70d75fd81 100644 --- a/docs/manpages/smbtar.1 +++ b/docs/manpages/smbtar.1 @@ -1,167 +1,120 @@ -.TH SMBTAR 1 18/2/96 smbtar smbtar +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBTAR" "1" "06 December 2001" "" "" .SH NAME -smbtar \- shell script for backing up SMB shares directly to UNIX tape drive +smbtar \- shell script for backing up SMB/CIFS shares directly to UNIX tape drives .SH SYNOPSIS -.B smbtar -.B \-s -.I server -.B [ \-p -.I password -.B ] -.B [ \-x -.I service -.B ] -.B [ \-X ] -.B [ \-d -.I directory -.B ] -.B [ \-u -.I user -.B ] -.B [ \-t -.I tape -.B ] -.B [ \-b -.I blocksize -.B ] -.B [ \-N -.I filename -.B ] -.B [ \-i ] -.B [ \-r ] -.B [ \-l ] -.B [ \-v ] -.I filenames... - -.SH DESCRIPTION -This program is an extension to the Samba suite. - -.B smbtar -is a very small shell script on top of smbclient, which dumps SMB -shares directly to tape. - -.SH OPTIONS -.B \-s -.I server -.RS 3 -The PC that the share resides upon. -.RE - -.B \-x -.I service -.RS 3 -The share name on the PC to connect to. Default: -.I backup. -.RE - -.B \-X -.RS 3 -Exclude mode. Exclude -.I filenames... -from tar create or restore. -.RE - -.B \-d -.I directory -.RS 3 -Change to initial -.I directory -before restoring / backing up files. -.RE - -.B \-v -.RS 3 +.sp +\fBsmbtar\fR \fB-s server\fR [ \fB-p password\fR ] [ \fB-x services\fR ] [ \fB-X\fR ] [ \fB-d directory\fR ] [ \fB-u user\fR ] [ \fB-t tape\fR ] [ \fB-t tape\fR ] [ \fB-b blocksize\fR ] [ \fB-N filename\fR ] [ \fB-i\fR ] [ \fB-r\fR ] [ \fB-l loglevel\fR ] [ \fB-v\fR ] \fBfilenames\fR +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBsmbtar\fR is a very small shell script on top +of \fBsmbclient(1)\fR +which dumps SMB shares directly to tape. +.SH "OPTIONS" +.TP +\fB-s server\fR +The SMB/CIFS server that the share resides +upon. +.TP +\fB-x service\fR +The share name on the server to connect to. +The default is "backup". +.TP +\fB-X\fR +Exclude mode. Exclude filenames... from tar +create or restore. +.TP +\fB-d directory\fR +Change to initial \fIdirectory +\fRbefore restoring / backing up files. +.TP +\fB-v\fR Verbose mode. -.RE - -.B \-p -.I password - -.RS 3 -The password to use to access a share. Default: none -.RE - -.B \-u -.I user -.RS 3 -The user id to connect as. Default: UNIX login name. -.RE - -.B \-t -.I tape -.RS 3 -Tape device. May be regular file or tape device. Default: Tape environmental -variable; if not set, a file called -.I tar.out. -.RE - -.B \-b -.I blocksize -.RS 3 -Blocking factor. Defaults to 20. See tar(1) for a fuller explanation. -.RE - -.B \-N -.I filename -.RS 3 -Backup only files newer than filename. Could be used (for example) on a log -file to implement incremental backups. -.RE - -.B \-i -.RS 3 -Incremental mode; tar files are only backed up if they have the -archive bit set. The archive bit is reset after each file is read. -.RE - -.B \-r -.RS 3 -Restore. Files are restored to the share from the tar file. -.RE - -.B \-l -.RS 3 -Debug level. Corresponds to -d flag on smbclient(1). -.RE - -.SH ENVIRONMENT VARIABLES -The TAPE variable specifies the default tape device to write to. May -be overidden with the -t option. - -.SH BUGS -The smbtar script has different options from ordinary tar and tar -called from smbclient. - -.SH CAVEATS -Sites that are more careful about security may not like the way -the script handles PC passwords. Backup and restore work on entire shares, -should work on file lists. - -.SH VERSION -This man page is correct for version 1.9.15p8 of the Samba suite. - -.SH SEE ALSO -.B smbclient -(8), -.B smb.conf -(8) -.SH DIAGNOSTICS -See diagnostics for -.B smbclient +.TP +\fB-p password\fR +The password to use to access a share. +Default: none +.TP +\fB-u user\fR +The user id to connect as. Default: +UNIX login name. +.TP +\fB-t tape\fR +Tape device. May be regular file or tape +device. Default: \fI$TAPE\fR environmental +variable; if not set, a file called \fItar.out +\fR\&. +.TP +\fB-b blocksize\fR +Blocking factor. Defaults to 20. See +\fBtar(1)\fR for a fuller explanation. +.TP +\fB-N filename\fR +Backup only files newer than filename. Could +be used (for example) on a log file to implement incremental +backups. +.TP +\fB-i\fR +Incremental mode; tar files are only backed +up if they have the archive bit set. The archive bit is reset +after each file is read. +.TP +\fB-r\fR +Restore. Files are restored to the share +from the tar file. +.TP +\fB-l log level\fR +Log (debug) level. Corresponds to the +\fI-d\fR flag of \fBsmbclient(1) +\fR\&. +.SH "ENVIRONMENT VARIABLES" +.PP +The \fI$TAPE\fR variable specifies the +default tape device to write to. May be overridden +with the -t option. +.SH "BUGS" +.PP +The \fBsmbtar\fR script has different +options from ordinary tar and tar called from smbclient. +.SH "CAVEATS" +.PP +Sites that are more careful about security may not like +the way the script handles PC passwords. Backup and restore work +on entire shares, should work on file lists. smbtar works best +with GNU tar and may not work well with other versions. +.SH "DIAGNOSTICS" +.PP +See the \fBDIAGNOSTICS\fR section for the +\fBsmbclient(1)\fR command. - -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -Ricky Poulten (poultenr@logica.co.uk) wrote the tar extension and this -man page. The smbtar script was heavily rewritten and improved by -Martin Kraemer <Martin.Kraemer@mch.sni.de>. Many thanks to everyone -who suggested extensions, improvements, bug fixes, etc. - -See -.B smb.conf -(5) for a full list of contributors and details of how to submit bug reports, -comments etc. - +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBsmbd(8)\fR, +\fBsmbclient(1)\fR, +smb.conf(5), +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +Ricky Poulten <URL:mailto:poultenr@logica.co.uk> +wrote the tar extension and this man page. The \fBsmbtar\fR +script was heavily rewritten and improved by Martin Kraemer <URL:mailto:Martin.Kraemer@mch.sni.de>. Many +thanks to everyone who suggested extensions, improvements, bug +fixes, etc. The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter. diff --git a/docs/manpages/smbumount.8 b/docs/manpages/smbumount.8 new file mode 100644 index 00000000000..d20826950aa --- /dev/null +++ b/docs/manpages/smbumount.8 @@ -0,0 +1,42 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SMBUMOUNT" "8" "06 December 2001" "" "" +.SH NAME +smbumount \- smbfs umount for normal users +.SH SYNOPSIS +.sp +\fBsmbumount\fR \fBmount-point\fR +.SH "DESCRIPTION" +.PP +With this program, normal users can unmount smb-filesystems, +provided that it is suid root. \fBsmbumount\fR has +been written to give normal Linux users more control over their +resources. It is safe to install this program suid root, because only +the user who has mounted a filesystem is allowed to unmount it again. +For root it is not necessary to use smbumount. The normal umount +program works perfectly well, but it would certainly be problematic +to make umount setuid root. +.SH "OPTIONS" +.TP +\fBmount-point\fR +The directory to unmount. +.SH "SEE ALSO" +.PP +\fBsmbmount(8)\fR + +.SH "AUTHOR" +.PP +Volker Lendecke, Andrew Tridgell, Michael H. Warfield +and others. +.PP +The current maintainer of smbfs and the userspace +tools \fBsmbmount\fR, \fBsmbumount\fR, +and \fBsmbmnt\fR is Urban Widmark <URL:mailto:urban@teststation.com>. +The SAMBA Mailing list <URL:mailto:samba@samba.org> +is the preferred place to ask questions regarding these programs. +.PP +The conversion of this manpage for Samba 2.2 was performed +by Gerald Carter diff --git a/docs/manpages/swat.8 b/docs/manpages/swat.8 new file mode 100644 index 00000000000..5e19f8705ce --- /dev/null +++ b/docs/manpages/swat.8 @@ -0,0 +1,140 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "SWAT" "8" "06 December 2001" "" "" +.SH NAME +swat \- Samba Web Administration Tool +.SH SYNOPSIS +.sp +\fBswat\fR [ \fB-s <smb config file>\fR ] [ \fB-a\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBswat\fR allows a Samba administrator to +configure the complex \fI smb.conf(5)\fRfile via a Web browser. In addition, +a \fBswat\fR configuration page has help links +to all the configurable options in the \fIsmb.conf\fR file allowing an +administrator to easily look up the effects of any change. +.PP +\fBswat\fR is run from \fBinetd\fR +.SH "OPTIONS" +.TP +\fB-s smb configuration file\fR +The default configuration file path is +determined at compile time. The file specified contains +the configuration details required by the \fBsmbd +\fRserver. This is the file that \fBswat\fR will modify. +The information in this file includes server-specific +information such as what printcap file to use, as well as +descriptions of all the services that the server is to provide. +See \fIsmb.conf\fR for more information. +.TP +\fB-a\fR +This option disables authentication and puts +\fBswat\fR in demo mode. In that mode anyone will be able to modify +the \fIsmb.conf\fR file. + +\fBDo NOT enable this option on a production +server. \fR +.SH "INSTALLATION" +.PP +After you compile SWAT you need to run \fBmake install +\fRto install the \fBswat\fR binary +and the various help files and images. A default install would put +these in: +.TP 0.2i +\(bu +/usr/local/samba/bin/swat +.TP 0.2i +\(bu +/usr/local/samba/swat/images/* +.TP 0.2i +\(bu +/usr/local/samba/swat/help/* +.SS "INETD INSTALLATION" +.PP +You need to edit your \fI/etc/inetd.conf +\fRand \fI/etc/services\fR +to enable SWAT to be launched via \fBinetd\fR. +.PP +In \fI/etc/services\fR you need to +add a line like this: +.PP +\fBswat 901/tcp\fR +.PP +Note for NIS/YP users - you may need to rebuild the +NIS service maps rather than alter your local \fI /etc/services\fR file. +.PP +the choice of port number isn't really important +except that it should be less than 1024 and not currently +used (using a number above 1024 presents an obscure security +hole depending on the implementation details of your +\fBinetd\fR daemon). +.PP +In \fI/etc/inetd.conf\fR you should +add a line like this: +.PP +\fBswat stream tcp nowait.400 root +/usr/local/samba/bin/swat swat\fR +.PP +One you have edited \fI/etc/services\fR +and \fI/etc/inetd.conf\fR you need to send a +HUP signal to inetd. To do this use \fBkill -1 PID +\fRwhere PID is the process ID of the inetd daemon. +.SS "LAUNCHING" +.PP +To launch SWAT just run your favorite web browser and +point it at "http://localhost:901/". +.PP +Note that you can attach to SWAT from any IP connected +machine but connecting from a remote machine leaves your +connection open to password sniffing as passwords will be sent +in the clear over the wire. +.SH "FILES" +.TP +\fB\fI/etc/inetd.conf\fB\fR +This file must contain suitable startup +information for the meta-daemon. +.TP +\fB\fI/etc/services\fB\fR +This file must contain a mapping of service name +(e.g., swat) to service port (e.g., 901) and protocol type +(e.g., tcp). +.TP +\fB\fI/usr/local/samba/lib/smb.conf\fB\fR +This is the default location of the \fIsmb.conf(5) +\fRserver configuration file that swat edits. Other +common places that systems install this file are \fI /usr/samba/lib/smb.conf\fR and \fI/etc/smb.conf +\fR\&. This file describes all the services the server +is to make available to clients. +.SH "WARNINGS" +.PP +\fBswat\fR will rewrite your \fIsmb.conf +\fRfile. It will rearrange the entries and delete all +comments, \fIinclude=\fR and \fIcopy=" +\fRoptions. If you have a carefully crafted \fI smb.conf\fR then back it up or don't use swat! +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBinetd(5)\fR, +\fBsmbd(8)\fR, +smb.conf(5) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/testparm.1 b/docs/manpages/testparm.1 index 4a0ffcbc489..d9515eddf42 100644 --- a/docs/manpages/testparm.1 +++ b/docs/manpages/testparm.1 @@ -1,104 +1,100 @@ -.TH TESTPARM 1 17/1/1995 testparm testparm +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "TESTPARM" "1" "06 December 2001" "" "" .SH NAME -testparm \- check an smbd configuration file for internal correctness +testparm \- check an smb.conf configuration file for internal correctness .SH SYNOPSIS -.B testparm -[ -.I configfilename -[ -.I hostname -.I hostIP -] -] -.SH DESCRIPTION -This program is part of the Samba suite. - -.B testparm -is a very simple test program to check an -.B smbd -configuration -file for internal correctness. If this program reports no problems, you can use -the configuration file with confidence that smbd will successfully -load the configuration file. - -Note that this is NOT a guarantee that the services specified in the -configuration file will be available or will operate as expected. - -If the optional host name and host IP address are specified on the -command line, this test program will run through the service entries -reporting whether the specified host has access to each service. -.SH OPTIONS -.I configfilename - -.RS 3 -This is the name of the configuration file to check. -.RE - -.I hostname - -.RS 3 -This is the name of the host to check access on. - -If this parameter is supplied, the -.I hostIP -parameter must also be supplied, or strange things may happen. -.RE - -.I hostIP - -.RS 3 -This is the IP number of the host specified in the previous parameter. - -This number must be supplied if the -.I hostname -parameter is supplied, or strange things may happen. -.RE -.SH FILES -.B smb.conf -.RS 3 -This is usually the name of the configuration file used by smbd. -.RE -.SH ENVIRONMENT VARIABLES -Not applicable. - -.SH INSTALLATION -The location of the server and its support files is a matter for individual -system administrators. The following are thus suggestions only. - -It is recommended that the -.B testparm -program be installed under the /usr/local hierarchy, in a directory readable -by all, writeable only by root. The program itself should be executable by all. -The program should NOT be setuid or setgid! -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the program has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B smb.conf(5), -.B smbd(8) -.SH DIAGNOSTICS -The program will issue a message saying whether the configuration file loaded -OK or not. This message may be preceded by errors and warnings if the file -did not load. If the file was loaded OK, the program then dumps all known -service details to stdout. - -If a host name is specified but no host IP number, all bets are off. - -Other messages are self-explanatory. -.SH BUGS -None known. -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -The testparm program and this man page were written by Karl Auer -(Karl.Auer@anu.edu.au) - -See -.B samba(7) for a full list of contributors and details on how to -submit bug reports, comments etc. +.sp +\fBtestparm\fR [ \fB-s\fR ] [ \fB-h\fR ] [ \fB-L <servername>\fR ] \fBconfig filename\fR [ \fBhostname hostIP\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBtestparm\fR is a very simple test program +to check an \fBsmbd\fR configuration file for +internal correctness. If this program reports no problems, you +can use the configuration file with confidence that \fBsmbd +\fRwill successfully load the configuration file. +.PP +Note that this is \fBNOT\fR a guarantee that +the services specified in the configuration file will be +available or will operate as expected. +.PP +If the optional host name and host IP address are +specified on the command line, this test program will run through +the service entries reporting whether the specified host +has access to each service. +.PP +If \fBtestparm\fR finds an error in the \fI smb.conf\fR file it returns an exit code of 1 to the calling +program, else it returns an exit code of 0. This allows shell scripts +to test the output from \fBtestparm\fR. +.SH "OPTIONS" +.TP +\fB-s\fR +Without this option, \fBtestparm\fR +will prompt for a carriage return after printing the service +names and before dumping the service definitions. +.TP +\fB-h\fR +Print usage message +.TP +\fB-L servername\fR +Sets the value of the %L macro to \fIservername\fR. +This is useful for testing include files specified with the +%L macro. +.TP +\fBconfigfilename\fR +This is the name of the configuration file +to check. If this parameter is not present then the +default \fIsmb.conf\fR file will be checked. +.TP +\fBhostname\fR +If this parameter and the following are +specified, then \fBtestparm\fR will examine the \fIhosts +allow\fR and \fIhosts deny\fR +parameters in the \fIsmb.conf\fR file to +determine if the hostname with this IP address would be +allowed access to the \fBsmbd\fR server. If +this parameter is supplied, the hostIP parameter must also +be supplied. +.TP +\fBhostIP\fR +This is the IP address of the host specified +in the previous parameter. This address must be supplied +if the hostname parameter is supplied. +.SH "FILES" +.TP +\fB\fIsmb.conf\fB\fR +This is usually the name of the configuration +file used by \fBsmbd\fR. +.SH "DIAGNOSTICS" +.PP +The program will issue a message saying whether the +configuration file loaded OK or not. This message may be preceded by +errors and warnings if the file did not load. If the file was +loaded OK, the program then dumps all known service details +to stdout. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fIsmb.conf(5)\fR, +\fBsmbd(8)\fR +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/testprns.1 b/docs/manpages/testprns.1 index f1c3d3ef020..fd62ed83861 100644 --- a/docs/manpages/testprns.1 +++ b/docs/manpages/testprns.1 @@ -1,107 +1,90 @@ -.TH TESTPRNS 1 17/1/1995 testprns testprns +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "TESTPRNS" "1" "06 December 2001" "" "" .SH NAME testprns \- check printer name for validity with smbd .SH SYNOPSIS -.B testprns -.I printername -[ -.I printcapname -] -.SH DESCRIPTION -This program is part of the Samba suite. - -.B testprns -is a very simple test program to determine whether a given -printer name is valid for use in a service to be provided by -.B smbd. - -"Valid" in this context means "can be found in the printcap specified". This -program is very stupid - so stupid in fact that it would be wisest to always -specify the printcap file to use. -.SH OPTIONS -.I printername - -.RS 3 +.sp +\fBtestprns\fR \fBprintername\fR [ \fBprintcapname\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +\fBtestprns\fR is a very simple test program +to determine whether a given printer name is valid for use in +a service to be provided by \fB smbd(8)\fR. +.PP +"Valid" in this context means "can be found in the +printcap specified". This program is very stupid - so stupid in +fact that it would be wisest to always specify the printcap file +to use. +.SH "OPTIONS" +.TP +\fBprintername\fR The printer name to validate. -Printer names are taken from the first field in each record in the printcap -file, single printer names and sets of aliases separated by vertical bars -("|") are recognised. Note that no validation or checking of the printcap -syntax is done beyond that required to extract the printer name. It may -be that the print spooling system is more forgiving or less forgiving -than -.B testprns -however if -.B testprns -finds the printer then smbd should do as well. - -.RE - -.I printcapname - -.RS 3 -This is the name of the printcap file to search for the given printer name -in. - -If no printcap name is specified, -.B testprns -will attempt to scan the printcap file specified at compile time -(PRINTCAP_NAME). -.RE -.SH FILES -.B /etc/printcap -.RS 3 -This is usually the default printcap file to scan. See -.B printcap(5)). -.RE -.SH ENVIRONMENT VARIABLES -Not applicable. - -.SH INSTALLATION -The location of the server and its support files is a matter for individual -system administrators. The following are thus suggestions only. - -It is recommended that the -.B testprns -program be installed under the /usr/local hierarchy, in a directory readable -by all, writeable only by root. The program should be executable by all. -The program should NOT be setuid or setgid! -.SH VERSION -This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some -of the recent patches to it. These notes will necessarily lag behind -development of the software, so it is possible that your version of -the program has extensions or parameter semantics that differ from or are not -covered by this man page. Please notify these to the address below for -rectification. -.SH SEE ALSO -.B printcap(5), -.B smbd(8), -.B smbclient(1) -.SH DIAGNOSTICS -If a printer is found to be valid, the message "Printer name <printername> is -valid" will be displayed. - -If a printer is found to be invalid, the message "Printer name <printername> -is not valid" will be displayed. - -All messages that would normally be logged during operation of smbd are -logged by this program to the file -.I test.log -in the current directory. The program runs at debuglevel 3, so quite extensive -logging information is written. The log should be checked carefully for errors -and warnings. - -Other messages are self-explanatory. -.SH BUGS -None known. -.SH CREDITS -The original Samba software and related utilities were created by -Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper -of the Source for this project. - -The testprns program and this man page were written by Karl Auer -(Karl.Auer@anu.edu.au) +Printer names are taken from the first field in each +record in the printcap file, single printer names and sets +of aliases separated by vertical bars ("|") are recognized. +Note that no validation or checking of the printcap syntax is +done beyond that required to extract the printer name. It may +be that the print spooling system is more forgiving or less +forgiving than \fBtestprns\fR. However, if +\fBtestprns\fR finds the printer then +\fBsmbd\fR should do so as well. +.TP +\fBprintcapname\fR +This is the name of the printcap file within +which to search for the given printer name. -See -.B samba(7) for a full list of contributors and details of how to -submit bug reports, comments etc. +If no printcap name is specified \fBtestprns +\fRwill attempt to scan the printcap file name +specified at compile time. +.SH "FILES" +.TP +\fB\fI/etc/printcap\fB\fR +This is usually the default printcap +file to scan. See \fIprintcap (5)\fR. +.SH "DIAGNOSTICS" +.PP +If a printer is found to be valid, the message +"Printer name <printername> is valid" will be +displayed. +.PP +If a printer is found to be invalid, the message +"Printer name <printername> is not valid" will be +displayed. +.PP +All messages that would normally be logged during +operation of the Samba daemons are logged by this program to the +file \fItest.log\fR in the current directory. The +program runs at debuglevel 3, so quite extensive logging +information is written. The log should be checked carefully +for errors and warnings. +.PP +Other messages are self-explanatory. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fIprintcap(5)\fR, +\fBsmbd(8)\fR, +\fBsmbclient(1)\fR +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +The original Samba man pages were written by Karl Auer. +The man page sources were converted to YODL format (another +excellent piece of Open Source software, available at +ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0 +release by Jeremy Allison. The conversion to DocBook for +Samba 2.2 was done by Gerald Carter diff --git a/docs/manpages/wbinfo.1 b/docs/manpages/wbinfo.1 new file mode 100644 index 00000000000..63795899c82 --- /dev/null +++ b/docs/manpages/wbinfo.1 @@ -0,0 +1,110 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WBINFO" "1" "06 December 2001" "" "" +.SH NAME +wbinfo \- Query information from winbind daemon +.SH SYNOPSIS +.sp +\fBwbinfo\fR [ \fB-u\fR ] [ \fB-g\fR ] [ \fB-n name\fR ] [ \fB-s sid\fR ] [ \fB-U uid\fR ] [ \fB-G gid\fR ] [ \fB-S sid\fR ] [ \fB-Y sid\fR ] [ \fB-t\fR ] [ \fB-m\fR ] +.SH "DESCRIPTION" +.PP +This tool is part of the Sambasuite. +.PP +The \fBwbinfo\fR program queries and returns information +created and used by the \fB winbindd(8)\fRdaemon. +.PP +The \fBwinbindd(8)\fR daemon must be configured +and running for the \fBwbinfo\fR program to be able +to return information. +.SH "OPTIONS" +.TP +\fB-u\fR +This option will list all users available +in the Windows NT domain for which the \fBwinbindd(8) +\fRdaemon is operating in. Users in all trusted domains +will also be listed. Note that this operation does not assign +user ids to any users that have not already been seen by +\fBwinbindd(8)\fR. +.TP +\fB-g\fR +This option will list all groups available +in the Windows NT domain for which the \fBwinbindd(8) +\fRdaemon is operating in. Groups in all trusted domains +will also be listed. Note that this operation does not assign +group ids to any groups that have not already been seen by +\fBwinbindd(8)\fR. +.TP +\fB-n name\fR +The \fI-n\fR option +queries \fBwinbindd(8)\fR for the SID +associated with the name specified. Domain names can be specified +before the user name by using the winbind separator character. +For example CWDOM1/Administrator refers to the Administrator +user in the domain CWDOM1. If no domain is specified then the +domain used is the one specified in the \fIsmb.conf\fR +\fIworkgroup\fR parameter. +.TP +\fB-s sid\fR +Use \fI-s\fR to resolve +a SID to a name. This is the inverse of the \fI-n +\fRoption above. SIDs must be specified as ASCII strings +in the traditional Microsoft format. For example, +S-1-5-21-1455342024-3071081365-2475485837-500. +.TP +\fB-U uid\fR +Try to convert a UNIX user id to a Windows NT +SID. If the uid specified does not refer to one within +the winbind uid range then the operation will fail. +.TP +\fB-G gid\fR +Try to convert a UNIX group id to a Windows +NT SID. If the gid specified does not refer to one within +the winbind gid range then the operation will fail. +.TP +\fB-S sid\fR +Convert a SID to a UNIX user id. If the SID +does not correspond to a UNIX user mapped by \fB winbindd(8)\fR then the operation will fail. +.TP +\fB-Y sid\fR +Convert a SID to a UNIX group id. If the SID +does not correspond to a UNIX group mapped by \fB winbindd(8)\fR then the operation will fail. +.TP +\fB-t\fR +Verify that the workstation trust account +created when the Samba server is added to the Windows NT +domain is working. +.TP +\fB-m\fR +Produce a list of domains trusted by the +Windows NT server \fBwinbindd(8)\fR contacts +when resolving names. This list does not include the Windows +NT domain the server is a Primary Domain Controller for. +.SH "EXIT STATUS" +.PP +The wbinfo program returns 0 if the operation +succeeded, or 1 if the operation failed. If the \fBwinbindd(8) +\fRdaemon is not working \fBwbinfo\fR will always return +failure. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fBwinbindd(8)\fR + +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +\fBwbinfo\fR and \fBwinbindd\fR +were written by Tim Potter. +.PP +The conversion to DocBook for Samba 2.2 was done +by Gerald Carter diff --git a/docs/manpages/winbindd.8 b/docs/manpages/winbindd.8 new file mode 100644 index 00000000000..cfd4fa2fb27 --- /dev/null +++ b/docs/manpages/winbindd.8 @@ -0,0 +1,381 @@ +.\" This manpage has been automatically generated by docbook2man-spec +.\" from a DocBook document. docbook2man-spec can be found at: +.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng <steve@ggi-project.org>. +.TH "WINBINDD" "8" "06 December 2001" "" "" +.SH NAME +winbindd \- Name Service Switch daemon for resolving names from NT servers +.SH SYNOPSIS +.sp +\fBwinbindd\fR [ \fB-i\fR ] [ \fB-d <debug level>\fR ] [ \fB-s <smb config file>\fR ] +.SH "DESCRIPTION" +.PP +This program is part of the Sambasuite. +.PP +\fBwinbindd\fR is a daemon that provides +a service for the Name Service Switch capability that is present +in most modern C libraries. The Name Service Switch allows user +and system information to be obtained from different databases +services such as NIS or DNS. The exact behaviour can be configured +throught the \fI/etc/nsswitch.conf\fR file. +Users and groups are allocated as they are resolved to a range +of user and group ids specified by the administrator of the +Samba system. +.PP +The service provided by \fBwinbindd\fR is called `winbind' and +can be used to resolve user and group information from a +Windows NT server. The service can also provide authentication +services via an associated PAM module. +.PP +The \fIpam_winbind\fR module in the 2.2.2 release only +supports the \fIauth\fR and \fIaccount\fR +module-types. The latter is simply +performs a getpwnam() to verify that the system can obtain a uid for the +user. If the \fIlibnss_winbind\fR library has been correctly +installed, this should always suceed. +.PP +The following nsswitch databases are implemented by +the winbindd service: +.TP +\fBpasswd\fR +User information traditionally stored in +the \fIpasswd(5)\fR file and used by +\fBgetpwent(3)\fR functions. +.TP +\fBgroup\fR +Group information traditionally stored in +the \fIgroup(5)\fR file and used by +\fBgetgrent(3)\fR functions. +.PP +For example, the following simple configuration in the +\fI/etc/nsswitch.conf\fR file can be used to initially +resolve user and group information from \fI/etc/passwd +\fRand \fI/etc/group\fR and then from the +Windows NT server. +.PP +.PP +.sp +.nf +passwd: files winbind +group: files winbind + +.sp +.fi +.PP +.SH "OPTIONS" +.TP +\fB-d debuglevel\fR +Sets the debuglevel to an integer between +0 and 100. 0 is for no debugging and 100 is for reams and +reams. To submit a bug report to the Samba Team, use debug +level 100 (see BUGS.txt). +.TP +\fB-i\fR +Tells \fBwinbindd\fR to not +become a daemon and detach from the current terminal. This +option is used by developers when interactive debugging +of \fBwinbindd\fR is required. +.SH "NAME AND ID RESOLUTION" +.PP +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 \fB winbindd\fR performs. +.PP +As winbindd 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. +.PP +WARNING: The rid to unix id database is the only location +where the user and group mappings are stored by winbindd. If this +file is deleted or corrupted, there is no way for winbindd to +determine which user and group ids correspond to Windows NT user +and group rids. +.SH "CONFIGURATION" +.PP +Configuration of the \fBwinbindd\fR daemon +is done through configuration parameters in the \fIsmb.conf(5) +\fRfile. All parameters should be specified in the +[global] section of smb.conf. +.TP +\fBwinbind separator\fR +The winbind separator option allows you +to specify how NT domain names and user names are combined +into unix user names when presented to users. By default, +\fBwinbindd\fR will use the traditional '\\' +separator so that the unix user names look like +DOMAIN\\username. In some cases this separator character may +cause problems as the '\\' character has special meaning in +unix shells. In that case you can use the winbind separator +option to specify an alternative separator character. Good +alternatives may be '/' (although that conflicts +with the unix directory separator) or a '+ 'character. +The '+' character appears to be the best choice for 100% +compatibility with existing unix utilities, but may be an +aesthetically bad choice depending on your taste. + +Default: \fBwinbind separator = \\ \fR + +Example: \fBwinbind separator = + \fR +.TP +\fBwinbind uid\fR +The winbind uid parameter specifies the +range of user ids that are allocated by the winbindd daemon. +This range of ids should have no existing local or NIS users +within it as strange conflicts can occur otherwise. + +Default: \fBwinbind uid = <empty string> +\fR +Example: \fBwinbind uid = 10000-20000\fR +.TP +\fBwinbind gid\fR +The winbind gid parameter specifies the +range of group ids that are allocated by the winbindd daemon. +This range of group ids should have no existing local or NIS +groups within it as strange conflicts can occur otherwise. + +Default: \fBwinbind gid = <empty string> +\fR +Example: \fBwinbind gid = 10000-20000 +\fR.TP +\fBwinbind cache time\fR +This parameter specifies the number of +seconds the winbindd daemon will cache user and group information +before querying a Windows NT server again. When a item in the +cache is older than this time winbindd will ask the domain +controller for the sequence number of the server's account database. +If the sequence number has not changed then the cached item is +marked as valid for a further \fIwinbind cache time +\fRseconds. Otherwise the item is fetched from the +server. This means that as long as the account database is not +actively changing winbindd will only have to send one sequence +number query packet every \fIwinbind cache time +\fRseconds. + +Default: \fBwinbind cache time = 15\fR +.TP +\fBwinbind enum users\fR +On large installations it may be necessary +to suppress the enumeration of users through the \fB setpwent()\fR, \fBgetpwent()\fR and +\fBendpwent()\fR group of system calls. If +the \fIwinbind enum users\fR parameter is false, +calls to the \fBgetpwent\fR system call will not +return any data. + +\fBWarning:\fR Turning off user enumeration +may cause some programs to behave oddly. For example, the \fBfinger\fR +program relies on having access to the full user list when +searching for matching usernames. + +Default: \fBwinbind enum users = yes \fR +.TP +\fBwinbind enum groups\fR +On large installations it may be necessary +to suppress the enumeration of groups through the \fB setgrent()\fR, \fBgetgrent()\fR and +\fBendgrent()\fR group of system calls. If +the \fIwinbind enum groups\fR parameter is +false, calls to the \fBgetgrent()\fR system +call will not return any data. + +\fBWarning:\fR Turning off group +enumeration may cause some programs to behave oddly. + +Default: \fBwinbind enum groups = no \fR +.TP +\fBtemplate homedir\fR +When filling out the user information +for a Windows NT user, the \fBwinbindd\fR daemon +uses this parameter to fill in the home directory for that user. +If the string \fI%D\fR is present it is +substituted with the user's Windows NT domain name. If the +string \fI%U\fR is present it is substituted +with the user's Windows NT user name. + +Default: \fBtemplate homedir = /home/%D/%U \fR +.TP +\fBtemplate shell\fR +When filling out the user information for +a Windows NT user, the \fBwinbindd\fR daemon +uses this parameter to fill in the shell for that user. + +Default: \fBtemplate shell = /bin/false \fR +.SH "EXAMPLE SETUP" +.PP +To setup winbindd for user and group lookups plus +authentication from a domain controller use something like the +following setup. This was tested on a RedHat 6.2 Linux box. +.PP +In \fI/etc/nsswitch.conf\fR put the +following: +.PP +.sp +.nf +passwd: files winbind +group: files winbind + +.sp +.fi +.PP +In \fI/etc/pam.d/*\fR replace the +\fIauth\fR lines with something like this: +.PP +.sp +.nf +auth required /lib/security/pam_securetty.so +auth required /lib/security/pam_nologin.so +auth sufficient /lib/security/pam_winbind.so +auth required /lib/security/pam_pwdb.so use_first_pass shadow nullok + +.sp +.fi +.PP +Note in particular the use of the \fIsufficient\fR +keyword and the \fIuse_first_pass\fR keyword. +.PP +Now replace the account lines with this: +.PP +\fBaccount required /lib/security/pam_winbind.so +\fR.PP +The next step is to join the domain. To do that use the +\fBsmbpasswd\fR program like this: +.PP +\fBsmbpasswd -j DOMAIN -r PDC -U +Administrator\fR +.PP +The username after the \fI-U\fR can be any +Domain user that has administrator privileges on the machine. +Substitute your domain name for "DOMAIN" and the name of your PDC +for "PDC". +.PP +Next copy \fIlibnss_winbind.so\fR to +\fI/lib\fR and \fIpam_winbind.so\fR +to \fI/lib/security\fR. A symbolic link needs to be +made from \fI/lib/libnss_winbind.so\fR to +\fI/lib/libnss_winbind.so.2\fR. If you are using an +older version of glibc then the target of the link should be +\fI/lib/libnss_winbind.so.1\fR. +.PP +Finally, setup a \fIsmb.conf\fR containing directives like the +following: +.PP +.sp +.nf +[global] + winbind separator = + + winbind cache time = 10 + template shell = /bin/bash + template homedir = /home/%D/%U + winbind uid = 10000-20000 + winbind gid = 10000-20000 + workgroup = DOMAIN + security = domain + password server = * + +.sp +.fi +.PP +Now start winbindd and you should find that your user and +group database is expanded to include your NT users and groups, +and that you can login to your unix box as a domain user, using +the DOMAIN+user syntax for the username. You may wish to use the +commands \fBgetent passwd\fR and \fBgetent group +\fRto confirm the correct operation of winbindd. +.SH "NOTES" +.PP +The following notes are useful when configuring and +running \fBwinbindd\fR: +.PP +\fBnmbd\fR must be running on the local machine +for \fBwinbindd\fR to work. \fBwinbindd\fR +queries the list of trusted domains for the Windows NT server +on startup and when a SIGHUP is received. Thus, for a running \fB winbindd\fR to become aware of new trust relationships between +servers, it must be sent a SIGHUP signal. +.PP +Client processes resolving names through the \fBwinbindd\fR +nsswitch module read an environment variable named \fB $WINBINDD_DOMAIN\fR. If this variable contains a comma separated +list of Windows NT domain names, then winbindd will only resolve users +and groups within those Windows NT domains. +.PP +PAM is really easy to misconfigure. Make sure you know what +you are doing when modifying PAM configuration files. It is possible +to set up PAM such that you can no longer log into your system. +.PP +If more than one UNIX machine is running \fBwinbindd\fR, +then in general the user and groups ids allocated by winbindd will not +be the same. The user and group ids will only be valid for the local +machine. +.PP +If the the Windows NT RID to UNIX user and group id mapping +file is damaged or destroyed then the mappings will be lost. +.SH "SIGNALS" +.PP +The following signals can be used to manipulate the +\fBwinbindd\fR daemon. +.TP +\fBSIGHUP\fR +Reload the \fIsmb.conf(5)\fR +file and apply any parameter changes to the running +version of winbindd. This signal also clears any cached +user and group information. The list of other domains trusted +by winbindd is also reloaded. +.TP +\fBSIGUSR1\fR +The SIGUSR1 signal will cause \fB winbindd\fR to write status information to the winbind +log file including information about the number of user and +group ids allocated by \fBwinbindd\fR. + +Log files are stored in the filename specified by the +log file parameter. +.SH "FILES" +.TP +\fB\fI/etc/nsswitch.conf(5)\fB\fR +Name service switch configuration file. +.TP +\fB/tmp/.winbindd/pipe\fR +The UNIX pipe over which clients communicate with +the \fBwinbindd\fR program. For security reasons, the +winbind client will only attempt to connect to the winbindd daemon +if both the \fI/tmp/.winbindd\fR directory +and \fI/tmp/.winbindd/pipe\fR file are owned by +root. +.TP +\fB/lib/libnss_winbind.so.X\fR +Implementation of name service switch library. +.TP +\fB$LOCKDIR/winbindd_idmap.tdb\fR +Storage for the Windows NT rid to UNIX user/group +id mapping. The lock directory is specified when Samba is initially +compiled using the \fI--with-lockdir\fR option. +This directory is by default \fI/usr/local/samba/var/locks +\fR\&. +.TP +\fB$LOCKDIR/winbindd_cache.tdb\fR +Storage for cached user and group information. +.SH "VERSION" +.PP +This man page is correct for version 2.2 of +the Samba suite. +.SH "SEE ALSO" +.PP +\fInsswitch.conf(5)\fR, +samba(7), +wbinfo(1), +smb.conf(5) +.SH "AUTHOR" +.PP +The original Samba software and related utilities +were created by Andrew Tridgell. Samba is now developed +by the Samba Team as an Open Source project similar +to the way the Linux kernel is developed. +.PP +\fBwbinfo\fR and \fBwinbindd\fR +were written by Tim Potter. +.PP +The conversion to DocBook for Samba 2.2 was done +by Gerald Carter |