more SGML/DocBook sources

(This used to be commit d98b6f42f562d7dd9fd48d540f9484562be607e6)

2 files changed, 916 insertions, 0 deletions

diff --git a/docs/docbook/nmbd.8.sgml b/docs/docbook/nmbd.8.sgml
new file mode 100644
index 0000000000..0188bca748
--- /dev/null
+++ b/docs/docbook/nmbd.8.sgml
@@ -0,0 +1,343 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<refentry id="nmbd">
+
+<refmeta>
+	<refentrytitle>nmbd</refentrytitle>
+	<manvolnum>8</manvolnum>
+</refmeta>
+
+
+<refnamediv>
+	<refname>nmbd</refname>
+	<refpurpose>NetBIOS name server to provide NetBIOS 
+	over IP naming 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">-d &lt;debug level&gt;</arg>
+		<arg choice="opt">-H &lt;lmhosts file&gt;</arg>
+		<arg choice="opt">-l &lt;log file&gt;</arg>
+		<arg choice="opt">-n &lt;primary netbios name&gt;</arg>
+		<arg choice="opt">-p &lt;port number&gt;</arg>
+		<arg choice="opt">-s &lt;configuration file&gt;</arg>
+	</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+	<title>DESCRIPTION</title>
+	<para>This program is part of the Samba suite.</para>
+
+	<para><command>nmbd</command> is a server that understands 
+	and can reply to NetBIOS over IP name service requests, like 
+	those produced by SMBD/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 &quot;Network Neighborhood&quot; view.</para>
+
+	<para>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.</para>
+
+	<para>Amongst other services, <command>nmbd</command> 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 &quot;own NetBIOS name&quot; is by
+	default the primary DNS name of the host it is running on, 
+	but this can be overridden with the <emphasis>-n</emphasis> 
+	option (see OPTIONS below). Thus <command>nmbd</command> will 
+	reply to broadcast queries for its own name(s). Additional
+	names for <command>nmbd</command> to respond on can be set 
+	via parameters in the <ulink url="smb.conf.5.html"><filename>
+	smb.conf(5)</filename></ulink> configuration file.</para>
+
+	<para><command>nmbd</command> 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.</para>
+
+	<para>In addition, <command>nmbd</command> 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.</para>
+</refsect1>
+
+<refsect1>
+	<title>OPTIONS</title>
+
+	<variablelist>
+		<varlistentry>
+		<term>-D</term>
+		<listitem><para>If specified, this parameter causes 
+		<command>nmbd</command> to operate as a daemon. That is, 
+		it detaches itself and runs in the background, fielding 
+		requests on the appropriate port. By default, <command>nmbd</command> 
+		will operate as a daemon if launched from a command shell. 
+		nmbd can also be operated from the <command>inetd</command> 
+		meta-daemon, although this is not recommended.
+		</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>-h</term>
+		<listitem><para>Prints the help information (usage) 
+		for <command>nmbd</command>.</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>-H &lt;filename&gt;</term>
+		<listitem><para>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 <ulink url="smb.conf.5.html#nameresolveorder">
+		name resolve order</ulink> described in <ulink 
+		url="smb.conf.5.html"> <filename>smb.conf(5)</filename></ulink>
+		to resolve any NetBIOS name queries needed by the server. Note 
+		that the contents of this file are <emphasis>NOT</emphasis> 
+		used by <command>nmbd</command> to answer any name queries. 
+		Adding a line to this file affects name NetBIOS resolution 
+		from this host <emphasis>ONLY</emphasis>.</para>
+
+		<para>The default path to this file is compiled into 
+		Samba as part of the build process. Common defaults 
+		are <filename>/usr/local/samba/lib/lmhosts</filename>,
+		<filename>/usr/samba/lib/lmhosts</filename> or
+		<filename>/etc/lmhosts</filename>. See the <ulink url="lmhosts.5.html">
+		<filename>lmhosts(5)</filename></ulink> man page for details on the 
+		contents of this file.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-V</term>
+		<listitem><para>Prints the version number for 
+		<command>nmbd</command>.</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>-d &lt;debug level&gt;</term>
+		<listitem><para>debuglevel 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</filename></ulink> file.</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>-l &lt;log file&gt;</term>
+		<listitem><para>The -l parameter specifies a path 
+		and base filename into which operational data from 
+		the running <command>nmbd</command> server will
+		be logged.  The actual log file name is generated by 
+		appending the extension &quot;.nmb&quot; to the specified base 
+		name.  For example, if the name specified was &quot;log&quot; 
+		then the file log.nmb would contain the debugging data.</para>
+
+		<para>The default log file path is compiled into Samba as 
+		part of the build process. Common defaults are <filename>
+		/usr/local/samba/var/log.nmb</filename>, <filename>
+		/usr/samba/var/log.nmb</filename> or
+		<filename>/var/log/log.nmb</filename>.</para></listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-n &lt;primary NetBIOS name&gt;</term>
+		<listitem><para>This option allows you to override
+		the NetBIOS name that Samba uses for itself. This is identical 
+		to setting the <ulink url="smb.conf.5.html#netbiosname">
+		NetBIOS name</ulink> parameter in the <ulink url="smb.conf.5.html">	
+		<filename>smb.conf</filename></ulink> file.  However, a command
+		line setting will take precedence over settings in 
+		<filename>smb.conf</filename>.</para></listitem>
+		</varlistentry>
+
+		
+		<varlistentry>
+		<term>-p &lt;UDP port number&gt;</term>
+		<listitem><para>UDP port number is a positive integer value.
+		This option changes the default UDP port number (normally 137) 
+		that <command>nmbd</command> responds to name queries on. Don't 
+		use this option unless you are an expert, in which case you 
+		won't need help!</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>-s &lt;configuration file&gt;</term>
+		<listitem><para>The default configuration file name 
+		is set at build time, typically as <filename>
+		/usr/local/samba/lib/smb.conf</filename>, but
+		this may be changed when Samba is autoconfigured.</para>
+
+		<para>The file specified contains the configuration details 
+		required by the server. See <ulink url="smb.conf.5.html"> 
+		<filename>smb.conf(5)</filename></ulink> for more information.
+		</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>When run as a WINS server (see the 
+		<ulink url="smb.conf.5.html#winssupport">wins support</ulink>
+		parameter in the <ulink url="smb.conf.5.html"><filename>
+		smb.conf(5)</filename></ulink> man page), <command>nmbd</command> 
+		will store the WINS database in the file <filename>wins.dat</filename> 
+		in the <filename>var/locks</filename> directory configured under 
+		wherever Samba was configured to install itself.</para>
+
+		<para>If <command>nmbd</command> is acting as a <emphasis>
+		browse master</emphasis> (see the <ulink 
+		url="smb.conf.5.html#localmaster">local master</ulink>
+		parameter in the <ulink url="smb.conf.5.html"><filename>
+		smb.conf(5)</filename></ulink> man page), <command>nmbd</command> 
+		will store the browsing database in the file <filename>browse.dat
+		</filename> in the <filename>var/locks</filename> directory
+		configured under wherever Samba was configured to install itself.
+		</para></listitem>
+		</varlistentry>
+	</variablelist>
+</refsect1>
+
+<refsect1>
+	<title>SIGNALS</title>
+
+	<para>To shut down an <command>nmbd</command> process it is recommended 
+	that SIGKILL (-9) <emphasis>NOT</emphasis> be used, except as a last 
+	resort, as this may leave the name database in an inconsistent state. 
+	The correct way to terminate <command>nmbd</command> is to send it 
+	a SIGTERM (-15) signal and wait for it to die on its own.</para>
+
+	<para><command>nmbd</command> will accept SIGHUP, which will cause 
+	it to dump out it's namelists into the file <filename>namelist.debug
+	</filename> in the <filename>/usr/local/samba/var/locks</filename> 
+	directory (or the <filename>var/locks</filename> directory configured 
+	under wherever Samba was configured to install itself). This will also 
+	cause <command>nmbd</command> to dump out it's server database in
+	the <filename>log.nmb</filename> file. In addition, the debug log level 
+	of nmbd may be raised by sending it a SIGUSR1 (<command>kill -USR1
+	&lt;nmbd-pid&gt;</command>) and lowered by sending it a
+	SIGUSR2 (<command>kill -USR2 &lt;nmbd-pid&gt;</command>). This is to 
+	allow transient problems to be diagnosed, whilst still running at a 
+	normally low log level.</para>
+</refsect1>
+
+
+<refsect1>
+	<title>VERSION</title>
+
+	<para>This man page is correct for version 2.2 of 
+	the Samba suite.</para>
+</refsect1>
+
+<refsect1>
+	<title>SEE ALSO</title>
+	<para><command>inetd(8)</command>, <ulink
+	url="smbd.8.html"><command>smbd(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>
diff --git a/docs/docbook/smbd.8.sgml b/docs/docbook/smbd.8.sgml
new file mode 100644
index 0000000000..2ee7b46e19
--- /dev/null
+++ b/docs/docbook/smbd.8.sgml
@@ -0,0 +1,573 @@
+<!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">-d &lt;debug level&gt;</arg>
+		<arg choice="opt">-l &lt;log file&gt;</arg>
+		<arg choice="opt">-p &lt;port number&gt;</arg>
+		<arg choice="opt">-O &lt;socket option&gt;</arg>
+		<arg choice="opt">-s &lt;configuration file&gt;</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 smbd 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 smbd for 
+		servers that provide more than casual use file and 
+		print services.  This switch is assumed is <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 smbd 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>-d &lt;debug level&gt;</term>
+		<listitem><para>debuglevel 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 &lt;log file&gt;</term>
+		<listitem><para>If specified, <emphasis>log file</emphasis> 
+		specifies a log filename into which informational and debug 
+		messages from the running server will be logged. 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.  The default log 
+		file name is specified at compile time.</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>-O &lt;socket options&gt;</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 &lt;port number&gt;</term>
+		<listitem><para>port number 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 &lt;configuration file&gt;</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 
+	&quot;trapdoor&quot; 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 &quot;access denied&quot; or 
+	similar.</para>
+</refsect1>
+
+<refsect1>
+	<title>ENVIRONMENTVARIABLES</title>
+
+	<variablelist>
+		<varlistentry>
+		<term>PRINTER</term>
+		<listitem><para>If no printer name is specified to 
+		printable services, most systems will use the value of 
+		this variable (or &quot;lp&quot; 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 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 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 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.</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>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 &quot;fred&quot; and your 
+	name is &quot;mary&quot;, you should now be able to connect 
+	to the service <filename>&bsol;&bsol;fred&bsol;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 smbd a SIGHUP will cause it to 
+	re-load its <filename>smb.conf</filename> configuration 
+	file within a short period of time.</para>
+
+	<para>To shut down a users smbd 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 smbd is to send it a SIGTERM (-15) signal and wait for 
+	it to die on its own.</para>
+
+	<para>The debug log level of smbd may be raised by sending 
+	it a SIGUSR1 (<command>kill -USR1 &lt;smbd-pid&gt;</command>)
+	and lowered by sending it a SIGUSR2 (<command>kill -USR2 &lt;smbd-pid&gt;
+	</command>). 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 smbd. This you should wait until 
+	smbd 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>