Note! The following document is now a bit out of date. Anyone feel like doing an updated version? Samba Suite. Document version 1.7.00. Copyright Karl Auer 1994 Samba A LanManager(R)-compatible server suite for Unix created by Andrew Tridgell (Andrew.Tridgell@anu.edu.au) with help from the 'Net! General Notes and Installation Guidelines by Karl Auer (Karl.Auer@anu.edu.au) Contents Introduction 3 Credits Legal stuff Contributors 4 Some terminology 5 How it all works 6 The programs 7 smbd nmbd smbclient testprns testparm smbprint The manual pages 8 smb.conf(5) smbd(8) nmbd(8) smbclient(1) testprns(1) testparm(1) Building the suite 9 First, obtain the source code... ...unpack the source code... ...modify the configuration details... 10 ...compile the sources... 11 ...and install the suite. Installation 12 What needs to be installed Setting up the configuration file, smb.conf To name serve or not to name serve? 13 The options for running the servers Decisions! 14 Installing as a daemon 15 Installing for use with inetd 16 Testing your servers 17 Running Samba as non-superuser 18 Installing and using DOS/Windows clients 19 Remember - TCP/IP! A host by any other name... Introduction The Samba suite is a set of programs which run under the Unix operating system. These programs deliver most of the important functionality of a Microsoft Lan Manager server. That is, they support remote access to Unix filespace and Unix printers from Lan Manager compatible clients. In practical terms, this means that such clients can connect to and use Unix filespace as if it was a local disk drive, or Unix printers as if they were local printers. Some of the most popular Lan Manager compatible clients include Lan Manager itself, Windows for Workgroups, OS/2 and Windows NT. Using the smbclient program (part of the suite) under Unix, it is also possible to mount the filespace and printer services available on other Lan Manager compatible servers and access them from Unix. This document is mainly aimed at helping you understand and install the Samba suite under Unix, but there is a section at the end on installing clients. Credits The creator of the Samba suite is Andrew Tridgell (Andrew.Tridgell@anu.edu.au) who wrote the server suite in the first place and who has continued to provide most of the ideas, most of the code and most of the effort. For a run down on how it all began, check out the file "history" in the sources distribution. Andrew gets double credit, for after writing this great piece of software he then GPL'ed it, making it available to anyone who wants it at no cost. Many thanks also to the many people who contributed code for different platforms, bug reports, bug fixes and great ideas. Errors If you discover problems with this document or would like to suggest useful additions, please email Karl.Auer@anu.edu.au (actual text for inclusion particularly welcomed!). Legal stuff All companies and products mentioned in this document are trademarks or registered trademarks of their respective owners. This document is Copyright Karl Auer 1994. It may be reproduced freely provided that modifications are identified as such and are not attributed to Karl Auer. Contributors In alphabetical order by surname: Adams, Graham (gadams@ddrive.demon.co.uk) Allison, Jeremy (jeremy@netcom.com) Auer, Karl (Karl.Auer@anu.edu.au) Bogstad, Bill (bogstad@cs.jhu.edu) Boreham, Bryan (bryan@alex.com) Butler, Michael (imb@asstdc.scgt.oz.au) Fisher, Lee (leefi@microsoft.com) Hudson, Tim (gslmail.mincom.oz.au) Hulthen, Erik Magnus (magnus@axiom.se) Iversen, Per Steinar (iversen@dsfys1.fi.uib.no) Kaara, Pasi (ppk@atk.tpo.fi) Karman, Merik (merik@blackadder.dsh.oz.au) Kiff, Martin (mgk@newton.npl.co.uk) Kukulies, Christoph (kuku@acds.physik.rwth-aachen.de) Lendecke, Volker (lendecke@namu01.gwdg.de) Pierson, Jacques (pierson@ketje.enet.dec.com) Powell, Mark (mark@scot1.ucsalf.ac.uk) Reiz, Steven (sreiz@aie.nl) Schlaeger, Joerg (joergs@toppoint.de) Tridgell, Andrew (Andrew.Tridgell@anu.edu.au) Troyer, Dean (troyer@saifr00.ateng.az.honeywell.com) Wakelin, Ross (rossw@march.co.uk) Some terminology Here are some of the terms we will use through this discussion. host A computer (usually Unix) server Software that provides access to resources for client hosts server host A computer on which server software is running client A computer that accesses resources provided by another computer client user The (human) user of a client username A login identity on a Unix host user The entity associated with a username on a Unix host For example, Fred Nurk logs in to the Unix host deepthought. He logs in using the username fred, so on deepthought he is the user fred. deepthought is running the server smbd, so deepthought is also a server host. Fred's PC is running Lan Manager, so Fred's PC is a client and Fred is a client user - at least while Fred is using resources made available by smbd. The above terms are admittedly a little contrived, but without specific terms for all these, the situation gets very confusing! How it all works The whole system is built around the idea of "services" (sometimes called "shares" for reasons which will become obvious). A service is a resource made available by a server for access by clients. All services are defined in a single control file, called smb.conf. Actually you can call it anything, but that's the conventional name. The server can only provide access to resources that the server host it is running on has access to. Services are based on directories. When making filespace available, the directory is the directory (on the server host) to which clients are being given access. When making a printer available, the directory is the spool directory (on the server host) where data will be written before printing. Each service is defined in terms of a directory, a username and sundry other parameters. The username is of particular interest, because it is this username that defines whether clients can access the resource and what privileges they have when they do. Each username is a specific Unix user name, just as might be used by a person logging in to the server host. A client user establishes a connection to the server by specifying the desired server host and the name of the service they wish to access. For most services the client user must also specify a password. The username specified for the service in the configuration file, plus the password supplied by the client user, is then checked by the server host's usual password checking system before the client is given access to the service. Once access has been granted to a service, all operations on that service will be done as if by the user specified for the service. Files created, for example, will be owned by that user and accesses to files and devices will be governed by the privileges of that user. Security provided by the server and specified in the configuration file is in addition to the access rights specified by the Unix host the server is running on. The server cannot give any access to a user that the server host would not ordinarily allow that user. There is a default username, which is used for all services where no other username is specified. Typically this user has very few privileges, and usually would not be permitted to log on to the Unix host. This default user is typically used for public services such as shared printers or read-only directories. The programs smbd This program is the server itself. It services connections made by clients based on the information in the configuration file. nmbd This program performs netbios name serving. In almost all cases, someone installing smbd will also want to install nmbd. When a client is seeking to connect to a host, it first broadcasts a name service request, saying, in effect, "I have this name, what is the IP address?". The nmbd responds to such requests, allowing clients to locate servers. smbclient This program is a Unix-based client program. It works rather like the familiar ftp program - the client user gets a prompt, and can issue commands which the client passes on to the server. The results are then displayed by the client program to the client user. Using this client program, Unix users can access remote Lan Manager services - move files to and from Unix, print files, see directory listings and so on. smbclient differs from PC client programs in that it does not provide redirection. That is, the resources it connects to do not appear to the client user as if they were local. testprns Very much a primitive test program, this is a quick-and-dirty way to see if a printer name is valid. testparm Also a quick-and-dirty program, testparm performs a "syntax check" on the smbd configuration file. There may still be logical errors in it, but if testparm says it's OK, then at least the problems are not in the structure of the configuration file! smbprint This is a script which, when specified appropriately to your host's printing subsystem, will allow printing to a remote Lan Manager printer. The manual pages These are Unix man pages, which are typically installed after building the Samba suite. They are kept in step with the software as much as possible - except for the source code itself, the man pages ALWAYS have the most current information about software options and usage. smb.conf(5) Describes the configuration file in great depth. Reading this man page in conjunction with this document will also give you quite a good feel for how the whole system operates. Required reading if you are setting up the Samba suite! smbd(8) Describes the command line options and operation of the server program. nmbd(8) Describes the command line options and operation of the netbios name server program. It also describes fairly well what the netbios name server does - again, well worth a read if you are setting up the SMB server suite. smbclient(1) Describes the command line options and operation of the Unix-based client program. This client program is a really good way to test a new installation, particularly since no client machine is required. This man page also explains the many commands available from within the smbclient program. testprns(1) Describes the testprns program. Most importantly, it discusses the limitations of the testprns program, which are many! testparm(1) Describes the testparm program. Like testprns, testparm has a lot of limitations, being basically a development tool. Building the suite To compile the Samba suite, you need access to a suitable Unix machine with an ANSI compiler. GCC is excellent. The following steps are pretty much in the correct order, but we recommend reading this entire section before beginning. First, obtain the source code... The first step towards getting the Samba suite operational is to obtain the source code. At time of writing, the current version is 1.7.00. The source code may be obtained via anonymous ftp from: nimbus.anu.edu.au:/pub/tridge/samba ...unpack the source code... Create a directory in which to work. Copy the sources file to the directory. If the source file is compressed uncompress it and extract all components. Assuming you picked it up from nimbus, the source file will be a gzipped tar archive, so: cd source_dir gunzip samba-1.7.00.tar.gz tar xfv samba-1.7.00.tar The original tar file is no longer needed, so you can archive it or discard it. Check out the files COPYING, README and THANKS. For a bit of interesting story- telling, you might also find the file history interesting. The file change-log makes for very interesting reading too, describing as it does all the changes and improvements that have happened along the way. These files also show you how many people have contributed. As you proceed through installation and strike the inevitable frustrations, remember how much work this software represents. ...modify the configuration details... Most configuration can be done in the supplied Makefile. However, some additional configuration can be done by editing local.h. In general, there should be no need to alter local.h and we do not recommend doing so unless you know exactly what you are doing. So - edit the Makefile. The man page directories must exist if you intend to install the man pages using this Makefile - check MANDIR and correct it if necessary. You will almost certainly want to alter the installation directory (INSTALLDIR). We recommend that the servers and associated programs NOT be installed in /usr/local/bin, but instead in their own directory under /usr/local. This makes it easier to install upgrades. It also allows administrative access to be given to non-root users using groups without decreasing security on other software. The log file path and basename (DEBUGFILE), configuration file path (SERVICES) and default guest user (FLAGS4) can all be specified on the command line to the programs or overridden in the configuration file, so these can be left as they are or edited to suit your system. The default guest user specified in FLAGS4 should be set up if no suitable one exists. We suggest setting up a user called "nobody". While not mandatory, we strongly recommend that the default user should be unable to log on as an interactive user. The default user should have no privileges - they should own no files and should belong to a group of their own (we suggest a group "nogroup" be set up as well). The only access the default user should have to the system is to files, directories and devices that are world-readable or world-writable. Select the environment-specific stuff (FLAGSM and LIBSM) as appropriate to your system. Most of the ones in the Makefile are pretty much OK, but you should check and alter them if necessary - the comments in the Makefile should help here. The Makefile comes with SunOS as the target system - remember to comment it out if you are compiling for a different system. Depending on how paranoid you are, you should probably at least peruse local.h to see how other things are set up. ...compile the sources... You can do this two ways - the cautious way and the bold way. The cautious way is to "make all", which just builds the executables. You can then use "make installbin", "make installman" or "make install" to install everything. The bold way is to "make install" which will build and install everything in one fell swoop. The installation puts the executables in INSTALLDIR and the man pages in directories below MANDIR, all with appropriate permissions. We recommend the cautious approach. While every effort has been made to help the SMB suite compile on all those different platforms, it is likely that there will be some minor problems, unless you happen to be using SunOS or Linux, the two most thoroughly tested platforms. Feel free to email questions to netbios@arvidsjaur.anu.edu.au. If you fix problems on a supported platform or get the suite working on a hitherto unsupported platform, PLEASE mail context diffs to Andrew.Tridgell@anu.edu.au for incorporation in the next version. ...and install the suite. Once all the programs have compiled to your satisfaction, you can install the software and manual pages. You will probably need to be root to install man pages or to install anywhere other than your own home directory tree. These instructions assume that you either have root access yourself or can get someone with root access to help you. If neither of these is the case, simply leave the executables in the source directory and run them from there. The following section still has valuable information, but you might also like to read the section on "Running Samba as a non-superuser". If you have root access, installation is pretty simple: check that MANDIR, INSTALLDIR and INSTALLPERMS in Makefile ensure that the man page directories exist ensure that the installation directory exists type "make install". Installation As with the section on building the Samba suite, we strongly recommend that you read this section in its entirety before starting the process of installing the suite. What needs to be installed Installing the Samba suite involves four steps: install the binaries and man pages edit the configuration file to correctly define the services you need set up the netbios name server to handle connections from clients set up the Samba to handle connections from clients The first of these steps is done by the make file ("make install"). The others are a bit more complex and are described below. Setting up the configuration file, smb.conf You will need to set up a suitable configuration file to defining the services that your clients will need to access. We STRONGLY recommend that this file be called "smb.conf". The sample configuration file supplied with the Samba suite should be enough to start with. It provides all users access to their home directories and provides access to all printers supported by the local printing subsystem. Note that the sample is not installed by the make file - you need to copy it from the source directory to wherever you want it kept. For obvious reasons it should be writable only by root. It is not necessary that it be readable by anyone except root either, but typically it will be world-readable. The sample file contains comments on items that may need alteration to suit your circumstances - please read these comments carefully before allowing access to the server. Beyond the basics as supplied in the sample configuration file, requirements will vary wildly from site to site. Some example configurations are given as comments in the sample configuration file. You should also read the man page smb.conf(5). To name serve or not to name serve? Without the netbios name server software, each client must maintain its own netbios name list to map IP addresses to netbios names. This is a pain to keep up to date, is typically something most client users do not want to have to know about, and is generally Not Good. Although it is NOT strictly needed, we strongly recommend installing nmbd on one Unix machine in each subnet. The options for running the servers There are two ways the servers can be run - either as daemons or via inetd. If run as daemons, the servers will be permanently resident in memory. This saves some time when a new connection from a client is needed, because the servers do not need to be loaded from disk. On the other hand, the servers will need to be manually killed in order to be updated and the memory they occupy will be occupied even when no connections are active. The main advantage of running the servers as daemons is that this can be done without root access, allowing you to play with the servers secure in the knowledge that the only data you can obliterate will be your own. If run via inetd, the servers are started by the inetd "meta-daemon" when a connection request is received on the appropriate port. This takes a little longer, as the program must be loaded off disk. However, when no connections are active, the server code is not occupying RAM. Also, using inetd allows you to run things like TCP wrappers for extra security. Installing the servers to run via inetd requires root access to the host machine, but is the recommended way of running the servers if the system is to provide a real service. The following instructions assume you have root access and are installing the servers "for real" - ie., to provide real services to real clients. There are some notes later on about how to run the server experimentally as a non-superuser. smbd and nmbd are both installed almost the same way, so the following descriptions apply equally to both, except where specific differences are noted. Decisions! Apart from deciding whether to run as a daemon or via inetd, you also need to decide several things about how the servers will operate. Here are some important questions and some discussion to help you decide what is appropriate for your site: Where will the configuration file (smb.conf) go? Well, anywhere really. It does need to exist and to accurately describe the services smbd is to support. The main thing is that it should be writable only by root. It does not need to be world-readable, though it won't matter if it is for most installations. Where will the log files go? Bear in mind that under some circumstances the log files may contain plain-text password information. At very least they are a record of who connected when and from where. Therefore they should be treated as confidential, and placed somewhere where only root can read or modify them. The last component of the path specified for logs will be used as the basename, and appropriate log file names will be built from them For example, given a basename of "log", nmbd will create "log.nmb.debug" and so on. What port should I use? Unless you have VERY good reason to do otherwise, leave the ports at their defaults (139 for smbd, 137 for nmbd). These ports are "well known", and most DOS/Windows clients will not be configurable in this respect. What debugging level do I want? For day-to-day use, level 1 is most appropriate. Level 2 and 3 provide copious and extremely copious debugging information respectively, most of which is of interest only to developers. Levels above 3 provide ludicrous amounts of log data... Do I need to use the -S option with the netbios name server? Almost certainly yes. This allows the name server to use the gethostbyname() call to find out IP addresses other than it's own, but without needing a special list of such hosts. It usually also allows names outside the local subnet to be located. Installing as a daemon Assuming you have specified appropriate log and configuration file paths in the Makefile while building the suite, the command line for both servers will be simple - basically you need only specify the -D option, which indicates that the server should run as a daemon. In the case of the netbios name server, you probably want it to locate hosts other than itself, so also specify the -S option. Thus: /usr/local/bin/nmbd -D -S /usr/local/bin/smbd -D Obviously you should substitute the correct paths to the programs if they are not in /usr/local/bin. If you did not specify suitable defaults while building the programs, you will also need to specify the log file path and basename, and (in the case of smbd) the path and filename of the configuration file. Place these two command lines in a small script and run the script when the machine starts up, or manually. Remember that these programs must be run by root to be effective. Installing for use with inetd First, check that the ports are specified in /etc/services. Ensure that the following lines appear somewhere in the file: netbios-ns 137/udp netbios-ssn 139/tcp You don't have to use these particular ports, but it is highly recommended. If you don't remember you will have to specify the appropriate port numbers to smbd, nmbd and any clients you use. Next, add the following lines to /etc/inetd.conf: netbios-ns dgram udp wait root nmbd nmbd -S netbios-ssn stream tcp nowait root smbd smbd You should prefix the first occurrence of the server name in each line with the complete path to the executable. If you did not specify suitable defaults while building the programs, you will also need to specify the log file path and basename, and (in the case of smbd) the path and filename of the configuration file. These should be appended to the lines shown above. The syntax for inetd.conf does vary somewhat between systems. You should use existing entries as your guide, and check your local system documentation for the correct syntax. Finally, restart inetd. This can be done for most systems by sending it a HUP signal. For example, if the running inetd is process ID 6789, you could restart it thus: kill -HUP 6789 Restarting inetd in this way is harmless. Testing your servers The simplest way to test smbd is to use smbclient on the same host that you have just installed the servers on. This minimises the likelihood of network-related problems. We also recommend reading the man page smbclient(1) before continuing. If running the servers as daemons, use the ps command to check that both servers are actually running. Now, substituting the local host name for "host" and a suitable service name for "service" (your username will do if you have defined a [homes] section in smb.conf), try this: smbclient "\\host\service" Obviously this assumes that smbclient is in the path - otherwise prefix the command with the directory in which it is installed. With some shells, all those backslashes need to be escaped: smbclient "\\\\host\\service" If using [homes], give your usual password when prompted, otherwise give the password for the username specified in smb.conf against the service. If the service is public, just press ENTER at the password prompt. If "host" cannot be found, it may be that the desired host is not locatable via the normal gethostbyname() call. At the moment, smbclient uses only TCP names, not netbios names. If the host you want to connect to has a netbios name that differs from its "real" name, you have a problem. Try using the -I option and the IP address of your host to overcome this. If the connection is refused altogether, double check the permissions and paths of the executables - this is the single most common cause of failure, especially when running the servers via inetd! Another common problem is using the wrong case for usernames, passwords and service names. When in doubt use upper case for all. Running Samba as non-superuser If you don't have root access to your target host but still want to experiment, you can run smbd as an ordinary user. However, the server will have a lot of limitations, as it is designed to run as root. The biggest limitation is access to security - if you are using a system that uses shadow passwords, you will only be able to use guest services, as root access is required to check shadow passwords. Since installing the servers to run via inetd requires root access to several system files, your only option as an ordinary user is to run the server as a daemon. You'll need to specify a path to a configuration file you can edit. This can be done in the makefile during compilation or (more sensibly) on the command line when you run smbd. You'll also have to specify a log basename and path that you can write to - again, this can be done in the makefile during compilation or on the command line when you run either of the servers. Most Unixes forbid non-root access to low-numbered ports, so you'll almost certainly have to specify a port number greater that 1024. This effectively precludes experimentation with most DOS/Windows clients, as they rarely have configurable port numbers. You will be able to play with the Unix-hosted smbclient, of course, because you can specify a port number to it. Your configuration file should specify services that provide access to directories and printers that you have access to - while you may be able to mount other services, you will be unable to use them if you do not have Unix privileges to access them. Again, if shadow passwords are used on your system, you will not be able to access non-public resources. Installing and using DOS/Windows clients There are quite a few of these and to fully describe even a few would be a very big task. The two most obvious ones are Lan Manager client software (the commercial one and the free one) and Windows for Workgroups. Installing these is straightforward and reasonably well documented, so that will not be covered here. However, there are some useful tips and tricks to remember. Remember - TCP/IP! Whatever client you use, it must support the TCP/IP protocol in order to communicate with the Unix-hosted Samba. Typically LanMan-compatible clients run NetBEUI, so your first step after installing the client software should be to install that protocol as well. In the case of Windows for Workgroups, a TCP/IP extension is available at no cost from ftp.microsoft.com - look for WFWTCP.EXE. This is a self-extracting file which can be extracted to a clean directory on your hard disk. Use the "Network Setup" icon in Windows for Workgroups, select "Drivers" and install an "Unlisted" protocol, specifying the directory you put the extensions in when prompted. Alternatively, unpack the distribution file to a floppy and insert it when prompted. Note that TCP/IP can coexist with NetBEUI and all the other protocols Windows for Workgroups supports. In the case of the free Lan Manager client and others, the TCP/IP extension is either an install option (run the setup again to add it) or an installable extra (contact your vendor for details). A host by any other name... A computer running Windows for Workgroups can be set up so that it acts as a server host as well as a client. In Windows for Workgroups jargon, this is called "sharing" and the resource being made available is a "share". Windows for Workgroups can share printers and directories. Many Lan Manager compatible servers require user names, service names and passwords to be in upper case. When sharing resources, Windows for Workgroups is such a server. Most DOS-based clients automatically uppercase all server host names, user names and passwords. The smbclient program (being Unix based and thus aggressively case sensitive) does not. Remember to hit CAPS LOCK when using the smbclient program to connect to DOS-hosted servers.