diff options
Diffstat (limited to 'docs/manpages/nmbd.8')
| -rw-r--r-- | docs/manpages/nmbd.8 | 491 |
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. + + + + + |