Initial version imported to CVS

(This used to be commit 291551d80711daab7b7581720bcd9a08d6096517)

1 files changed, 491 insertions, 0 deletions

diff --git a/docs/manpages/nmbd.8 b/docs/manpages/nmbd.8
new file mode 100644
index 00000000000..e42f194cdee
--- /dev/null
+++ b/docs/manpages/nmbd.8
@@ -0,0 +1,491 @@
+.TH NMBD 8 17/1/1995 nmbd nmbd
+.SH NAME
+nmbd \- provide netbios nameserver support to clients
+.SH SYNOPSIS
+.B nmbd
+[
+.B -B
+.I broadcast address
+] [
+.B -I
+.I IP address
+] [
+.B -D
+] [
+.B -C comment string
+] [
+.B -G
+.I group name
+] [
+.B -H
+.I netbios hosts file
+] [
+.B -N
+.I netmask
+] [
+.B -d
+.I debuglevel
+] [
+.B -l
+.I log basename
+] [
+.B -n
+.I netbios name
+] [
+.B -p
+.I port number
+] [
+.B -s
+.I config file name
+]
+
+.SH DESCRIPTION
+This program is part of the Samba suite.
+
+.B nmbd
+is a server that understands and can reply to netbios
+name service requests, like those produced by LanManager
+clients. It also controls browsing.
+
+LanManager clients, when they start up, may wish to locate a LanManager server.
+That is, they wish to know what IP number a specified host is using.
+
+This program simply listens for such requests, and if its own name is specified
+it will respond with the IP number of the host it is running on. "Its own name"
+is by default the name of the host it is running on, but this can be overriden
+with the
+.B -n
+option (see "OPTIONS" below). Using the
+.B -S
+option (see "OPTIONS" below), it can also be instructed to respond with IP 
+information about other hosts, provided they are locatable via the 
+gethostbyname() call, or they are in a netbios hosts file.
+
+Nmbd can also be used as a WINS (Windows Internet Name Server)
+server. It will do this automatically by default. What this basically
+means is that it will respond to all name requests that it receives
+that are not broadcasts, as long as it can resolve the name.
+.SH OPTIONS
+.B -B
+
+.RS 3
+On some systems, the server is unable to determine the broadcast address to
+use for name registration requests. If your system has this difficulty, this 
+parameter may be used to specify an appropriate broadcast address. The 
+address should be given in standard "a.b.c.d" notation.
+
+Only use this parameter if you are sure that the server cannot properly 
+determine the proper broadcast address.
+
+The default broadcast address is determined by the server at run time. If it
+encounters difficulty doing so, it makes a guess based on the local IP
+number.
+.RE
+.B -I
+
+.RS 3
+On some systems, the server is unable to determine the correct IP
+address to use. This allows you to override the default choice.
+.RE
+
+.B -D
+
+.RS 3
+If specified, this parameter causes the server to operate as a daemon. That is,
+it detaches itself and runs in the background, fielding requests on the 
+appropriate port.
+
+By default, the server will NOT operate as a daemon.
+.RE
+
+.B -C comment string
+
+.RS 3
+This allows you to set the "comment string" that is shown next to the
+machine name in browse listings. 
+
+A %v will be replaced with the Samba version number.
+
+A %h will be replaced with the hostname.
+
+It defaults to "Samba %v".
+.RE
+
+.B -G
+
+.RS 3
+This option allows you to specify a netbios group (also known as
+lanmanager domain) that the server should be part of. You may include
+several of these on the command line if you like. Alternatively you
+can use the -H option to load a netbios hosts file containing domain names.
+
+At startup, unless the -R switch has been used, the server will
+attempt to register all group names in the hosts file and on the
+command line (from the -G option).
+
+The server will also respond to queries on this name.
+.RE
+
+.B -H
+
+.RS 3
+It may be useful in some situations to be able to specify a list of
+netbios names for which the server should send a reply if
+queried. This option allows that. The syntax is similar to the
+standard /etc/hosts file format, but has some extensions.
+
+The file contains three columns. Lines beginning with a # are ignored
+as comments. The first column is an IP address, or a hostname. If it
+is a hostname then it is interpreted as the IP address returned by
+gethostbyname() when read. Any IP address of 0.0.0.0 will be
+interpreted as the servers own IP address.
+
+The second column is a netbios name. This is the name that the server
+will respond to. It must be less than 20 characters long.
+
+The third column is optional, and is intended for flags. Currently the
+only flags supported are G, S and M. A G indicates that the name is a
+group (also known as domain) name.
+
+At startup all groups known to the server (either from this file or
+from the -G option) are registered on the network (unless the -R
+option has been selected).
+
+A S or G means that the specified address is a broadcast address of a
+network that you want people to be able to browse you from. Nmbd will
+search for a master browser in that domain and will send host
+announcements to that machine, informing it that the specifed somain
+is available.
+
+A M means that this name is the default netbios name for this
+machine. This has the same affect as specifying the -n option to nmbd.
+
+After startup the server waits for queries, and will answer queries to
+any name known to it. This includes all names in the netbios hosts
+file (if any), it's own name, and any names given with the -G option.
+
+The primary intention of the -H option is to allow a mapping from
+netbios names to internet domain names, and to allow the specification
+of groups that the server should be part of.
+
+.B Example:
+
+        # This is a sample netbios hosts file
+
+        # DO NOT USE THIS FILE AS-IS
+        # YOU MAY INCONVENIENCE THE OWNERS OF THESE IPs
+        # if you want to include a name with a space in it then 
+        # use double quotes.
+
+        # first put ourselves in the group LANGROUP
+        0.0.0.0 LANGROUP G
+
+        # next add a netbios alias for a faraway host
+        arvidsjaur.anu.edu.au ARVIDSJAUR
+
+        # finally put in an IP for a hard to find host
+        130.45.3.213 FREDDY
+
+        # now we want another subnet to be able to browse
+        # us in the workgroup UNIXSERV
+        192.0.2.255  UNIXSERV G
+
+.RE
+
+.B -M
+.I workgroup name
+
+.RS 3
+If this parameter is given, the server will look for a master browser
+for the specified workgroup name, report success or failure, then
+exit. If successful, the IP address of the name located will be
+reported. 
+
+If you use the workgroup name "-" then nmbd will search for a master
+browser for any workgroup by using the name __MSBROWSE__.
+
+This option is meant to be used interactively on the command line, not
+as a daemon or in inetd.
+
+.RE
+.B -N
+
+.RS 3
+On some systems, the server is unable to determine the netmask. If
+your system has this difficulty, this parameter may be used to specify
+an appropriate netmask. The mask should be given in standard
+"a.b.c.d" notation.
+
+Only use this parameter if you are sure that the server cannot properly 
+determine the proper netmask.
+
+The default netmask is determined by the server at run time. If it
+encounters difficulty doing so, it makes a guess based on the local IP
+number.
+.RE
+
+.B -d
+.I debuglevel
+.RS 3
+
+debuglevel is an integer from 0 to 5.
+
+The default value if this parameter is not specified is zero.
+
+The higher this value, the more detail will be logged to the log files about
+the activities of the server. At level 0, only critical errors and serious 
+warnings will be logged. Level 1 is a reasonable level for day to day running
+- it generates a small amount of information about operations carried out.
+
+Levels above 1 will generate considerable amounts of log data, and should 
+only be used when investigating a problem. Levels above 3 are designed for 
+use only by developers and generate HUGE amounts of log data, most of which 
+is extremely cryptic.
+.RE
+
+.B -l
+.I log file
+
+.RS 3
+If specified,
+.I logfile
+specifies a base filename into which operational data from the running server
+will be logged.
+
+The default base name is specified at compile time.
+
+The base name is used to generate actual log file names. For example, if the
+name specified was "log", the following files would be used for log data:
+
+.RS 3
+log.nmb (containing debugging information)
+
+log.nmb.in (containing inbound transaction data)
+
+log.nmb.out (containing outbound transaction data)
+.RE
+
+The log files generated are never removed by the server.
+.RE
+.RE
+
+.B -n
+.I netbios name
+
+.RS 3
+This parameter tells the server what netbios name to respond with when 
+queried. The same name is also registered on startup unless the -R 
+parameter was specified.
+
+The default netbios name used if this parameter is not specified is the 
+name of the host on which the server is running.
+.RE
+
+.B -p
+.I port number
+.RS 3
+
+port number is a positive integer value.
+
+The default value if this parameter is not specified is 137.
+
+This number is the port number that will be used when making connections to
+the server from client software. The standard (well-known) port number for the
+server is 137, hence the default. If you wish to run the server as an ordinary
+user rather than as root, most systems will require you to use a port number
+greater than 1024 - ask your system administrator for help if you are in this
+situation.
+
+Note that the name server uses UDP, not TCP!
+
+This parameter is not normally specified except in the above situation.
+.RE
+.SH FILES
+
+.B /etc/inetd.conf
+
+.RS 3
+If the server is to be run by the inetd meta-daemon, this file must contain
+suitable startup information for the meta-daemon. See the section 
+"INSTALLATION" below.
+.RE
+
+.B /etc/rc.d/rc.inet2
+
+.RS 3
+(or whatever initialisation script your system uses)
+
+If running the server as a daemon at startup, this file will need to contain
+an appropriate startup sequence for the server. See the section "Installation"
+below.
+.RE
+
+.B /etc/services
+
+.RS 3
+If running the server via the meta-daemon inetd, this file must contain a
+mapping of service name (eg., netbios-ns)  to service port (eg., 137) and
+protocol type (eg., udp). See the section "INSTALLATION" below.
+.RE
+.RE
+
+.SH ENVIRONMENT VARIABLES
+Not applicable.
+
+.SH INSTALLATION
+The location of the server and its support files is a matter for individual
+system administrators. The following are thus suggestions only.
+
+It is recommended that the server software be installed under the /usr/local
+hierarchy, in a directory readable by all, writeable only by root. The server
+program itself should be executable by all, as users may wish to run the 
+server themselves (in which case it will of course run with their privileges).
+The server should NOT be setuid or setgid!
+
+The server log files should be put in a directory readable and writable only
+by root, as the log files may contain sensitive information.
+
+The remaining notes will assume the following:
+
+.RS 3
+nmbd (the server program) installed in /usr/local/smb
+
+log files stored in /var/adm/smblogs
+.RE
+
+The server may be run either as a daemon by users or at startup, or it may
+be run from a meta-daemon such as inetd upon request. If run as a daemon, the
+server will always be ready, so starting sessions will be faster. If run from 
+a meta-daemon some memory will be saved and utilities such as the tcpd 
+TCP-wrapper may be used for extra security.
+
+When you've decided, continue with either "Running the server as a daemon" or
+"Running the server on request".
+.SH RUNNING THE SERVER AS A DAEMON
+To run the server as a daemon from the command line, simply put the "-D" option
+on the command line. There is no need to place an ampersand at the end of the
+command line - the "-D" option causes the server to detach itself from the
+tty anyway.
+
+Any user can run the server as a daemon (execute permissions permitting, of 
+course). This is useful for testing purposes.
+
+To ensure that the server is run as a daemon whenever the machine is started,
+you will need to modify the system startup files. Wherever appropriate (for
+example, in /etc/rc.d/rc.inet2), insert the following line, substituting 
+values appropriate to your system:
+
+.RS 3
+/usr/local/smb/nmbd -D -l/var/adm/smblogs/log
+.RE
+
+(The above should appear in your initialisation script as a single line. 
+Depending on your terminal characteristics, it may not appear that way in
+this man page. If the above appears as more than one line, please treat any 
+newlines or indentation as a single space or TAB character.)
+
+If the options used at compile time are appropriate for your system, all
+parameters except the desired debug level and "-D" may be omitted. See the
+section on "Options" above.
+.SH RUNNING THE SERVER ON REQUEST
+If your system uses a meta-daemon such as inetd, you can arrange to have the
+SMB name server started whenever a process attempts to connect to it. This 
+requires several changes to the startup files on the host machine. If you are
+experimenting as an ordinary user rather than as root, you will need the 
+assistance of your system administrator to modify the system files.
+
+First, ensure that a port is configured in the file /etc/services. The 
+well-known port 137 should be used if possible, though any port may be used.
+
+Ensure that a line similar to the following is in /etc/services:
+
+.RS 3
+netbios-ns	137/udp
+.RE
+
+Note for NIS/YP users: You may need to rebuild the NIS service maps rather
+than alter your local /etc/services file.
+
+Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event
+that you are using a meta-daemon other than inetd, you are on your own). Note
+that the first item in this line matches the service name in /etc/services.
+Substitute appropriate values for your system in this line (see
+.B inetd(8)):
+
+.RS 3
+netbios-ns dgram udp wait root /usr/local/smb/nmbd -l/var/adm/smblogs/log
+.RE
+
+(The above should appear in /etc/inetd.conf as a single line. Depending on 
+your terminal characteristics, it may not appear that way in this man page.
+If the above appears as more than one line, please treat any newlines or 
+indentation as a single space or TAB character.)
+
+Note that there is no need to specify a port number here, even if you are 
+using a non-standard port number.
+.SH TESTING THE INSTALLATION
+If running the server as a daemon, execute it before proceeding. If
+using a meta-daemon, either restart the system or kill and restart the 
+meta-daemon. Some versions of inetd will reread their configuration tables if
+they receive a HUP signal.
+
+To test whether the name server is running, start up a client
+.I on a different machine
+and see whether the desired name is now present. Alternatively, run 
+the nameserver
+.I on a different machine
+specifying "-L netbiosname", where "netbiosname" is the name you have 
+configured the test server to respond with. The command should respond 
+with success, and the IP number of the machine using the specified netbios 
+name. You may need the -B parameter on some systems. See the README
+file for more information on testing nmbd.
+
+.SH VERSION
+This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some
+of the recent patches to it. These notes will necessarily lag behind 
+development of the software, so it is possible that your version of 
+the server has extensions or parameter semantics that differ from or are not 
+covered by this man page. Please notify these to the address below for 
+rectification.
+.SH SEE ALSO
+.B inetd(8),
+.B smbd(8), 
+.B smb.conf(5),
+.B smbclient(1),
+.B testparm(1), 
+.B testprns(1)
+
+.SH DIAGNOSTICS
+[This section under construction]
+
+Most diagnostics issued by the server are logged in the specified log file. The
+log file name is specified at compile time, but may be overridden on the
+command line.
+
+The number and nature of diagnostics available depends on the debug level used
+by the server. If you have problems, set the debug level to 3 and peruse the
+log files.
+
+Most messages are reasonably self-explanatory. Unfortunately, at time of
+creation of this man page the source code is still too fluid to warrant
+describing each and every diagnostic. At this stage your best bet is still
+to grep the source code and inspect the conditions that gave rise to the 
+diagnostics you are seeing.
+
+.SH BUGS
+None known.
+.SH CREDITS
+The original Samba software and related utilities were created by 
+Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper
+of the Source for this project.
+
+This man page written by Karl Auer (Karl.Auer@anu.edu.au)
+
+See
+.B smb.conf(5) for a full list of contributors and details on how to 
+submit bug reports, comments etc.
+
+
+
+
+