Fixed a few doc bugs in make_smbcodepage.1.yo samba.7.yo

Added smbd.8.yo.
Jeremy.
(This used to be commit 695b31d0664f2c52704c49b49e56223b793dfc00)

3 files changed, 410 insertions, 5 deletions

diff --git a/docs/yodldocs/make_smbcodepage.1.yo b/docs/yodldocs/make_smbcodepage.1.yo
index 1194a2909b..9b8df60d08 100644
--- a/docs/yodldocs/make_smbcodepage.1.yo
+++ b/docs/yodldocs/make_smbcodepage.1.yo
@@ -120,7 +120,7 @@ these to the address below for rectification.
 
 manpageseealso()
 
-bf(smb.conf)(5), bf(smbd) (8)
+bf(smb.conf(5)), bf(smbd (8))
 
 manpageauthor() 
 
diff --git a/docs/yodldocs/samba.7.yo b/docs/yodldocs/samba.7.yo
index e13caff044..de77264294 100644
--- a/docs/yodldocs/samba.7.yo
+++ b/docs/yodldocs/samba.7.yo
@@ -1,5 +1,5 @@
 mailto(samba-bugs@samba.anu.edu.au)
-manpage(samba)(7)(23 Oct 1998)()()
+manpage(samba)(7)(23 Oct 1998)(Samba)()
 manpagename(Samba)(A Windows fileserver for UNIX)
 manpagesynopsis()
 bf(Samba)
@@ -25,11 +25,11 @@ startdit()
 dit(bf(smbd)) nl() The bf(smbd) (8) 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 bf(smb.conf) (5).
+is described in bf(smb.conf (5)).
 
 dit(bf(nmbd)) nl() The bf(nmbd) (8) daemon provides NetBIOS
 nameserving and browsing support. The configuration file for this
-daemon is described in bf(smb.conf) (5).
+daemon is described in bf(smb.conf (5)).
 
 dit(bf(smbclient)) nl() The bf(smbclient) (1) program implements a simple
 ftp-like client. This is useful for accessing SMB shares on other
@@ -38,7 +38,7 @@ a UNIX box to print to a printer attached to any SMB server (such as a
 PC running Windows NT).
 
 dit(bf(testparm)) nl() The bf(testparm) (1) utility allows you to test your
-bf(smb.conf) (5) configuration file.
+bf(smb.conf (5)) configuration file.
 
 dit(bf(smbstatus)) nl() The bf(smbstatus) (1) utility allows you to tell
 who is currently using the bf(smbd) (8) server.
diff --git a/docs/yodldocs/smbd.8.yo b/docs/yodldocs/smbd.8.yo
new file mode 100644
index 0000000000..96a2061807
--- /dev/null
+++ b/docs/yodldocs/smbd.8.yo
@@ -0,0 +1,405 @@
+mailto(samba-bugs@samba.anu.edu.au) 
+
+manpage(smbd)(1)(23 Oct 1998)(Samba)(SAMBA)
+
+manpagename(smbd)(server to provide SMB/CIFS services to clients)
+
+manpagesynopsis()
+
+bf(smbd) [-D] [-a] [-o] [-d debuglevel] [-l log file] [-p port number]
+[-O socket options] [-s configuration file] [-i scope] [-P] [-h]
+
+manpagedescription()
+
+This program is part of the bf(Samba) suite.
+
+bf(smbd) is the server daemon that provides filesharing 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,
+Windows NT, OS/2, DAVE for Macintosh, and smbfs for Linux.
+
+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 bf(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 the bf(smb.conf (5)) manpage 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, 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.
+
+manpageoptions()
+
+startdit()
+
+dit(bf(-D)) 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.
+
+By default, the server will NOT operate as a daemon. 
+
+dit(bf(-a)) If this parameter is specified, each new connection will
+append log messages to the log file.  This is the default.
+
+dit(bf(-o)) If this parameter is specified, the log files will be
+overwritten when opened.  By default, the log files will be appended
+to.
+
+dit(bf(-d debuglevel)) 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.
+
+dit(bf(-l log file)) If specified, em(logfile) 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 an bf(smb.conf (5)) option.
+The default log file name is specified at compile time.
+
+dit(bf(-O socket options)) See the socket options section of bf(smb.conf
+(5)) for details.
+
+dit(bf(-p port number)) 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 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.
+
+dit(bf(-s configuration file)) 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 bf(smb.conf
+(5)) for more information.
+
+dit(bf(-i scope)) This specifies a NetBIOS scope that the server 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 em(very) rarely used, only set this parameter if you are the
+system administrator in charge of all the NetBIOS systems you
+communicate with.
+
+dit(bf(-h)) Prints the help information (usage) for smbd.
+
+dit(bf(-P)) Passive option. Causes smbd not to send any network traffic
+out. Used for debugging by the developers only.
+
+endit()
+
+manpagefiles()
+
+bf(/etc/inetd.conf)
+
+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 em(INSTALLATION) below.
+
+bf(/etc/rc)
+
+(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 em(INSTALLATION) below.
+
+bf(/etc/services)
+
+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
+em(INSTALLATION) below.
+
+bf(/usr/local/samba/lib/smb.conf)
+
+This is the default location of the em(smb.conf) server configuration
+file. Other common places that systems install this file are
+em(/usr/samba/lib/smb.conf) and em(/etc/smb.conf).
+
+This file describes all the services the server is to make available
+to clients. See bf(smb.conf (5)) for more information.
+
+manpagesection(LIMITATIONS)
+
+On some systems bf(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.
+
+manpagesection(ENVIRONMENT VARIABLES)
+
+bf(PRINTER)
+
+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.
+
+
+manpagesection(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/samba 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.
+
+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:
+
+startit()
+
+it() bf(smbd) (the server program) installed in /usr/local/samba/bin
+
+it() bf(smb.conf) (the configuration file) installed in /usr/local/samba/lib
+
+it() log files stored in /var/adm/smblogs
+
+endit()
+
+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.
+For serious use as file server it is recommended that bf(smbd) be run
+as a daemon.
+
+When you've decided, continue with either em(RUNNING THE SERVER AS A
+DAEMON) or em(RUNNING THE SERVER ON REQUEST).
+
+manpagesection(RUNNING THE SERVER AS A DAEMON)
+
+To run the server as a daemon from the command line, simply put the
+bf(-D) option on the command line. There is no need to place an
+ampersand at the end of the command line - the bf(-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:
+
+tt(/usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log -s /usr/local/samba/lib/smb.conf)
+
+(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 bf(-D) may be
+omitted. See the section em(OPTIONS) above.
+
+manpagesection(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 NetBIOS name server bf(nmbd) at
+the same time as bf(smbd). To do this refer to the man page for
+bf(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:
+
+tt(netbios-ssn	139/tcp)
+
+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 bf(inetd (8))):
+
+tt(netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd -d1 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf)
+
+(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:
+
+tt([homes])
+  writable = yes
+
+tt([printers])
+ writable = no
+ printable = yes
+ path = /tmp
+ public = yes
+
+This will allow you to connect to your home directory and print to any
+printer supported by the host (user privileges permitting).
+
+manpagesection(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 tt(\\fred\mary).
+
+To properly test and experiment with the server, we recommend using
+the smbclient program (see bf(smbclient (1))) and also going through
+the steps outlined in the file em(DIAGNOSIS.txt) in the em(docs/)
+directory of your Samba installation.
+
+manpagesection(VERSION)
+
+This man page is (mostly) correct for version 2.0 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.
+
+manpageseealso()
+
+bf(hosts_access (5)), bf(inetd (8)), bf(nmbd (8)), bf(smb.conf (5)),
+bf(smbclient (1)), bf(testparm (1)), bf(testprns (1)), and the
+Internet RFC's bf(rfc1001.txt), bf(rfc1002.txt). In addition the
+CIFS (formerly SMB) specification is available as a link from the
+Web page :
+url(http://samba.anu.edu.au/cifs/)(http://samba.anu.edu.au/cifs/).
+
+manpagesection(DIAGNOSTICS)
+
+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 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.
+
+manpagesection(SIGNALS)
+
+Sending the smbd a SIGHUP will cause it to re-load its smb.conf
+configuration file within a short period of time.
+
+To shut down a users smbd process it is recommended that SIGKILL (-9)
+em(NOT) be used, except as a last resort, as this may leave the shared
+memory area in an inconsistant 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.
+
+In version 1.9.18 and above the debug log level of smbd may be raised
+by sending it a SIGUSR1 tt((kill -USR1 <smbd-pid>)) and lowered by
+sending it a SIGUSR2 tt((kill -USR2 <smbd-pid>)). This is to allow
+transient problems to be diagnosed, whilst still running at a normally
+low log level.
+
+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.
+
+manpageauthor()
+
+The original Samba software and related utilities were created by
+Andrew Tridgell (samba-bugs@samba.anu.edu.au). Samba is now developed
+by the Samba Team as an Open Source project similar to the way the
+Linux kernel is developed.
+
+See bf(samba (8)) to find out how to get a full list of contributors
+and details on how to submit bug reports, comments etc.