Amiga Tools 5/Amiga Tools 5.iso/tools/net-tools/samba/samba-unix.doc/smbguide.txt

Text File | 1995-04-28 | 29.6 KB | 788 lines

=================================================================
NOTE! The following document is now VERY out of date. Anyone feel
like doing an updated version?

If you read this info in it's cuirrent form then I strongly suggest
you also read the manual pages, README and the *.txt files that come
with Samba. They are much more uptodate. If your find they disagree
with this document then this document is almost certainly in the
wrong!

Refer to the man pages for more up to date info.
=================================================================



Samba Suite. Document version 1.7.00. Copyright Karl Auer 1994




Samba






A LanManager(R)-compatible server suite for Unix


created by
Andrew Tridgell
([e-mail])

with help from the 'Net!


General Notes and Installation Guidelines
by Karl Auer
([e-mail])

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
([e-mail]) 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 [e-mail] (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        ([e-mail])
Allison, Jeremy        ([e-mail])
Auer, Karl        ([e-mail])
Bogstad, Bill        ([e-mail])
Boreham, Bryan        ([e-mail])
Butler, Michael        ([e-mail])
Fisher, Lee        ([e-mail])
Hudson, Tim        (gslmail.mincom.oz.au)
Hulthen, Erik Magnus    ([e-mail])
Iversen, Per Steinar    ([e-mail])
Kaara, Pasi        ([e-mail])
Karman, Merik        ([e-mail])
Kiff, Martin        ([e-mail])
Kukulies, Christoph    ([e-mail])
Lendecke, Volker    ([e-mail])
Pierson, Jacques    ([e-mail])
Powell, Mark        ([e-mail])
Reiz, Steven        ([e-mail])
Schlaeger, Joerg    ([e-mail])
Tridgell, Andrew    ([e-mail])
Troyer, Dean        ([e-mail])
Wakelin, Ross        ([e-mail])

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 [e-mail]. If you
fix problems on a supported platform or get the suite working on a
hitherto unsupported platform, PLEASE mail context diffs to
[e-mail] 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 or "homes" 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.