diff options
Diffstat (limited to 'docs/docbook/manpages/smbd.8.sgml')
| -rw-r--r-- | docs/docbook/manpages/smbd.8.sgml | 611 |
1 files changed, 611 insertions, 0 deletions
diff --git a/docs/docbook/manpages/smbd.8.sgml b/docs/docbook/manpages/smbd.8.sgml new file mode 100644 index 00000000000..e01e5477079 --- /dev/null +++ b/docs/docbook/manpages/smbd.8.sgml @@ -0,0 +1,611 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<refentry id="smbd"> + +<refmeta> + <refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum> +</refmeta> + + +<refnamediv> + <refname>smbd</refname> + <refpurpose>server to provide SMB/CIFS services to clients</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>smbd</command> + <arg choice="opt">-D</arg> + <arg choice="opt">-a</arg> + <arg choice="opt">-o</arg> + <arg choice="opt">-P</arg> + <arg choice="opt">-h</arg> + <arg choice="opt">-V</arg> + <arg choice="opt">-b</arg> + <arg choice="opt">-d <debug level></arg> + <arg choice="opt">-l <log directory></arg> + <arg choice="opt">-p <port number></arg> + <arg choice="opt">-O <socket option></arg> + <arg choice="opt">-s <configuration file></arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + <para>This program is part of the Samba suite.</para> + + <para><command>smbd</command> 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.</para> + + <para>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 <ulink url="smb.conf.5.html"><filename>smb.conf(5) + </filename></ulink>. This man page will not describe the + services, but will concentrate on the administrative aspects + of running the server.</para> + + <para>Please note that there are significant security + implications to running this server, and the <ulink + url="smb.conf.5.html"><filename>smb.conf(5)</filename></ulink> + manpage should be regarded as mandatory reading before + proceeding with installation.</para> + + <para>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.</para> + + <para>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 <command>smbd</command> killed and restarted.</para> +</refsect1> + +<refsect1> + <title>OPTIONS</title> + + <variablelist> + <varlistentry> + <term>-D</term> + <listitem><para>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 <command>smbd</command> for + servers that provide more than casual use file and + print services. This switch is assumed if <command>smbd + </command> is executed on the command line of a shell. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-a</term> + <listitem><para>If this parameter is specified, each new + connection will append log messages to the log file. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-o</term> + <listitem><para>If this parameter is specified, the + log files will be overwritten when opened. By default, + <command>smbd</command> will append entries to the log + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-P</term> + <listitem><para>Passive option. Causes <command>smbd</command> not to + send any network traffic out. Used for debugging by + the developers only.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-h</term> + <listitem><para>Prints the help information (usage) + for <command>smbd</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-v</term> + <listitem><para>Prints the version number for + <command>smbd</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-b</term> + <listitem><para>Prints information about how + Samba was built.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-d <debug level></term> + <listitem><para><replaceable>debuglevel</replaceable> is an integer + from 0 to 10. The default value if this parameter is + not specified is zero.</para> + + <para>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.</para> + + <para>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.</para> + + <para>Note that specifying this parameter here will + override the <ulink url="smb.conf.5.html#loglevel">log + level</ulink> parameter in the <ulink url="smb.conf.5.html"> + <filename>smb.conf(5)</filename></ulink> file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-l <log directory></term> + <listitem><para>If specified, + <replaceable>log directory</replaceable> + 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 <ulink + url="smb.conf.5.html#maxlogsize">max log size</ulink> + option in the <ulink url="smb.conf.5.html"><filename> + smb.conf(5)</filename></ulink> file. + </para> + + <para>The default log directory is specified at + compile time.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-O <socket options></term> + <listitem><para>See the <ulink + url="smb.conf.5.html#socketoptions">socket options</ulink> + parameter in the <ulink url="smb.conf.5.html"><filename>smb.conf(5) + </filename></ulink> file for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-p <port number></term> + <listitem><para><replaceable>port number</replaceable> is a positive integer + value. The default value if this parameter is not + specified is 139.</para> + + <para>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.</para> + + <para>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.</para> + + <para>This parameter is not normally specified except + in the above situation.</para></listitem> + </varlistentry> + + <varlistentry> + <term>-s <configuration file></term> + <listitem><para>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 <ulink url="smb.conf.5.html"><filename> + smb.conf(5)</filename></ulink> for more information. + The default configuration file name is determined at + compile time.</para></listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>FILES</title> + + <variablelist> + <varlistentry> + <term><filename>/etc/inetd.conf</filename></term> + <listitem><para>If the server is to be run by the + <command>inetd</command> meta-daemon, this file + must contain suitable startup information for the + meta-daemon. See the section INSTALLATION below. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/etc/rc</filename></term> + <listitem><para>or whatever initialization script your + system uses).</para> + + <para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/etc/services</filename></term> + <listitem><para>If running the server via the + meta-daemon <command>inetd</command>, 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/local/samba/lib/smb.conf</filename></term> + <listitem><para>This is the default location of the + <ulink url="smb.conf.5.html"><filename>smb.conf</filename></ulink> + server configuration file. Other common places that systems + install this file are <filename>/usr/samba/lib/smb.conf</filename> + and <filename>/etc/smb.conf</filename>.</para> + + <para>This file describes all the services the server + is to make available to clients. See <ulink url="smb.conf.5.html"> + <filename>smb.conf(5)</filename></ulink> for more information.</para> + </listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>LIMITATIONS</title> + <para>On some systems <command>smbd</command> 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.</para> +</refsect1> + +<refsect1> + <title>ENVIRONMENT VARIABLES</title> + + <variablelist> + <varlistentry> + <term><envar>PRINTER</envar></term> + <listitem><para>If no printer name is specified to + printable services, most systems will use the value of + this variable (or <constant>lp</constant> if this variable is + not defined) as the name of the printer to use. This + is not specific to the server, however.</para></listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>INSTALLATION</title> + + <para>The location of the server and its support files + is a matter for individual system administrators. The following + are thus suggestions only.</para> + + <para>It is recommended that the server software be installed + under the <filename>/usr/local/samba/</filename> 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 <command>smbd</command> 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 <command>smbd</command> 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.</para> + + <para>The server log files should be put in a directory readable and + writeable only by root, as the log files may contain sensitive + information.</para> + + <para>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 <filename>smb.conf.sample + </filename> is supplied with the source to the server - this may + be renamed to <filename>smb.conf</filename> and modified to suit + your needs.</para> + + <para>The remaining notes will assume the following:</para> + + <itemizedlist> + <listitem><para><command>smbd</command> (the server program) + installed in <filename>/usr/local/samba/bin</filename></para> + </listitem> + + <listitem><para><filename>smb.conf</filename> (the configuration + file) installed in <filename>/usr/local/samba/lib</filename></para> + </listitem> + + <listitem><para>log files stored in <filename>/var/adm/smblogs + </filename></para></listitem> + </itemizedlist> + + <para>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 + <command>inetd</command> 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 <command>smbd</command> be run as a daemon.</para> + + <para>When you've decided, continue with either</para> + + <itemizedlist> + <listitem><para>RUNNING THE SERVER AS A DAEMON or</para></listitem> + <listitem><para>RUNNING THE SERVER ON REQUEST.</para></listitem> + </itemizedlist> +</refsect1> + +<refsect1> + <title>RUNNING THE SERVER AS A DAEMON</title> + + <para>To run the server as a daemon from the command + line, simply put the <emphasis>-D</emphasis> option on the + command line. There is no need to place an ampersand at + the end of the command line - the <emphasis>-D</emphasis> + option causes the server to detach itself from the tty + anyway.</para> + + <para>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.</para> + + <para>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 + <filename>/etc/rc</filename>), insert the following line, + substituting port number, log file location, configuration file + location and debug level as desired:</para> + + <para><command>/usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log + -s /usr/local/samba/lib/smb.conf</command></para> + + <para>(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.)</para> + + <para>If the options used at compile time are appropriate for + your system, all parameters except <emphasis>-D</emphasis> may + be omitted. See the section OPTIONS above.</para> +</refsect1> + +<refsect1> + <title>RUNNING THE SERVER ON REQUEST</title> + + <para>If your system uses a meta-daemon such as <command>inetd + </command>, you can arrange to have the <command>smbd</command> 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.</para> + + <para>You will probably want to set up the NetBIOS name server + <ulink url="nmbd.8.html"><command>nmbd</command></ulink> at + the same time as <command>smbd</command>. To do this refer to the + man page for <ulink url="nmbd.8.html"><command>nmbd(8)</command> + </ulink>.</para> + + <para>First, ensure that a port is configured in the file + <filename>/etc/services</filename>. The well-known port 139 + should be used if possible, though any port may be used.</para> + + <para>Ensure that a line similar to the following is in + <filename>/etc/services</filename>:</para> + + <para><command>netbios-ssn 139/tcp</command></para> + + <para>Note for NIS/YP users - you may need to rebuild the + NIS service maps rather than alter your local <filename>/etc/services + </filename> file.</para> + + <para>Next, put a suitable line in the file <filename>/etc/inetd.conf + </filename> (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 <filename>/etc/services + </filename>. Substitute appropriate values for your system + in this line (see <command>inetd(8)</command>):</para> + + <para><command>netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd + -d1 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf</command></para> + + <para>(The above should appear in <filename>/etc/inetd.conf</filename> + 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.)</para> + + <para>Note that there is no need to specify a port number here, + even if you are using a non-standard port number.</para> + + <para>Lastly, edit the configuration file to provide suitable + services. To start with, the following two services should be + all you need:</para> + + <screen> + <computeroutput> + [homes] + writeable = yes + + [printers] + writeable = no + printable = yes + path = /tmp + public = yes + </computeroutput> + </screen> + + <para>This will allow you to connect to your home directory + and print to any printer supported by the host (user privileges + permitting).</para> +</refsect1> + +<refsect1> + <title>PAM INTERACTION</title> + <para>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 + <ulink url="smb.conf.5.html#OBEYPAMRESRICTIONS">obey pam restricions</ulink> + smb.conf paramater. When this is set, the following restrictions apply: + </para> + + <itemizedlist> + <listitem><para><emphasis>Account Validation</emphasis>: 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. + </para></listitem> + + <listitem><para><emphasis>Session Management</emphasis>: 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. + </para></listitem> + </itemizedlist> +</refsect1> + +<refsect1> + <title>TESTING THE INSTALLATION</title> + + <para>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 + <command>inetd</command> will reread their configuration + tables if they receive a HUP signal.</para> + + <para>If your machine's name is <replaceable>fred</replaceable> and your + name is <replaceable>mary</replaceable>, you should now be able to connect + to the service <filename>\\fred\mary</filename>. + </para> + + <para>To properly test and experiment with the server, we + recommend using the <command>smbclient</command> program (see + <ulink url="smbclient.1.html"><command>smbclient(1)</command></ulink>) + and also going through the steps outlined in the file + <filename>DIAGNOSIS.txt</filename> in the <filename>docs/</filename> + directory of your Samba installation.</para> +</refsect1> + +<refsect1> + <title>VERSION</title> + + <para>This man page is correct for version 2.2 of + the Samba suite.</para> +</refsect1> + +<refsect1> + <title>DIAGNOSTICS</title> + + <para>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.</para> + + <para>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.</para> + + <para>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.</para> +</refsect1> + +<refsect1> + <title>SIGNALS</title> + + <para>Sending the <command>smbd</command> a SIGHUP will cause it to + reload its <filename>smb.conf</filename> configuration + file within a short period of time.</para> + + <para>To shut down a user's <command>smbd</command> process it is recommended + that <command>SIGKILL (-9)</command> <emphasis>NOT</emphasis> + 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 <command>smbd</command> is to send it a SIGTERM (-15) signal and wait for + it to die on its own.</para> + + <para>The debug log level of <command>smbd</command> may be raised + or lowered using <ulink url="smbcontrol.1.html"><command>smbcontrol(1) + </command></ulink> program (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.</para> + + <para>Note that as the signal handlers send a debug write, + they are not re-entrant in <command>smbd</command>. This you should wait until + <command>smbd</command> 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.</para> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + <para>hosts_access(5), <command>inetd(8)</command>, + <ulink url="nmbd.8.html"><command>nmbd(8)</command></ulink>, + <ulink url="smb.conf.5.html"><filename>smb.conf(5)</filename> + </ulink>, <ulink url="smbclient.1.html"><command>smbclient(1) + </command></ulink>, <ulink url="testparm.1.html"><command> + testparm(1)</command></ulink>, <ulink url="testprns.1.html"> + <command>testprns(1)</command></ulink>, and the Internet RFC's + <filename>rfc1001.txt</filename>, <filename>rfc1002.txt</filename>. + In addition the CIFS (formerly SMB) specification is available + as a link from the Web page <ulink url="http://samba.org/cifs/"> + http://samba.org/cifs/</ulink>.</para> +</refsect1> + +<refsect1> + <title>AUTHOR</title> + + <para>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.</para> + + <para>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 + <ulink url="ftp://ftp.icce.rug.nl/pub/unix/"> + ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 + release by Jeremy Allison. The conversion to DocBook for + Samba 2.2 was done by Gerald Carter</para> +</refsect1> + +</refentry> |