diff options
Diffstat (limited to 'docs/manpages/smbd.8')
| -rw-r--r-- | docs/manpages/smbd.8 | 707 |
1 files changed, 305 insertions, 402 deletions
diff --git a/docs/manpages/smbd.8 b/docs/manpages/smbd.8 index bae41b2c47..f534a59bf3 100644 --- a/docs/manpages/smbd.8 +++ b/docs/manpages/smbd.8 @@ -1,407 +1,310 @@ -.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" "28 January 2002" "" "" .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-i\fR ] [ \fB-o\fR ] [ \fB-P\fR ] [ \fB-h\fR ] [ \fB-V\fR ] [ \fB-b\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 -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" -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. - -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 +.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-i\fR +If this parameter is specified it causes the +server to run "interactively", not as a daemon, even if the +server is executed on the command line of a shell. Setting this +parameter negates the implicit deamon mode when run from 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 +\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-b\fR +Prints information about how +Samba was built. +.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, +\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 UNIX_INSTALL.html +document for details. +.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 UNIX_INSTALL.html +document for details. +.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 UNIX_INSTALL.html +document for details. +.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 "ENVIRONMENT VARIABLES" +.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 "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 "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 |