As most UNIX or Linux users probably know, Samba is the Open Source Software package that allows a UNIX or Linux server to participate in a Windows network, and even become the Windows primary domain controller (PDC).  In fact, it is possible for a properly configured Samba server to completely replace its Windows equivalent in the overwhelming majority of cases, affording a level of performance, stability and economy that is unmatched by anything Microsoft has produced to date.  Samba also offers to the administrator a lot more control over how his/her machine responds to requests from Windows clients.  Unavoidably, more control can mean more complexity.

Virtually everything that Samba does in a running environment is controlled by an ASCII configuration file called smb.conf.  The exact location of this file may vary from one system to another, and in fact, can be specified by the command line used to start Samba.  On most of the systems we build, smb.conf is stored in /etc/samba.d, along with some other files that may be required for a particular installation.  Regardless of its location, smb.conf will contain numerous statements that will dictate exactly how Samba will behave, and how it will present the underlying filesystem and operating environment to Windows clients.

For those who are not comfortable with a shell prompt and/or editing ASCII files in the UNIX/Linux environment, a web browser-based tool called SWAT ships with Samba, and may be used to put together a usable configuration.  However, there are limits to what SWAT can do (it cannot add comments to a complex file, for example), and you really should have a good understanding of what is inside smb.conf, if nothing else so you take an existing copy and tailor it to a different machine.

My intention here is not to teach Windows or Samba networking basics (several excellent books are available on that subject) but to instead illustrate a real-world example of Samba configuration running on a live system.  So, what I have done here is present the (slightly edited) contents of smb.conf from our office file and print server (which happens to be a SCO OpenServer 5 unit), annotated with comments describing what the various statements accomplish.  In writing this article, I have taken the liberty of assuming that you are familiar with how your server and network are configured, and know what terms such as subnet and broadcast mean.  If tasks such as mounting filesystems and configuring IP addresses, netmasks and broadcast addresses make your brain swell and start to hurt, you're going to run into some difficulty in understanding the balance of this diatribe.  If, on the other hand, all that technical tedious minutiae titillates your thought processes, please continue reading!

In the following text, smb.conf statements will be displayed in monospace blue text and my comments and assorted blathering will be appear in whatever the default font is for your browser.  Reference to elements of smb.conf will also be in blue monospace font.  The terms 95/98/ME and 2000/XP will refer to the two distinct versions of 32 bit Windows and the baggage each drags along for the ride.  Little consideration has been given to Windows for Workgroups 3.11, as this software is way too old and lame to even be considered on a modern system.  Ditto for NT 4.0 and earlier.  Also, it should be understood that where "UNIX" is mentioned "Linux" may be substituted.  Lastly, you should consult with the official Samba Team smb.conf definition as required.  So here we go...

; =======================
; Samba Runtime Variables
; =======================
;
; The following variables may be used as substitutions in this file. They
; are organized by function and within each function, by alphabetical
; precedence.

Comments in smb.conf are typically preceded by a semicolon.  I highly recommend that you thoroughly comment your smb.conf so as to record your intentions for posterity (and for the benefit of the jabroney who will take over when you leave for greener pastures).  The presence of comments has little effect on Samba's performance, so be as wordy as necessary to convey your thinking.  You are thinking, right?  :-)

; client-specific...
;
; a            client architecture, e.g., WinNT
; I client IP address
; m client NetBIOS name
; M client DNS name

Within its running environment, Samba understands a number of variables that relate to the underlying operating system and network resources.  Samba-specific variables are designated by compiled-in names that may be referenced elsewhere in smb.conf by preceding the variable name with a percent sign (%).  For example, in a configuration statement where %I is used, Samba will replace %I with the IP address of the connecting client machine.  You may also access environment variables created by the shell (BASH, ksh, etc.) from which Samba was started.  Here you would use the form %$(<varnam>).  For example, to refer to the TMPDIR shell variable in your smb.conf just say %$(TMPDIR).  You'll see some examples of this parameter substitution later on.

%a, %I, %m and %M are unique for each client machine that has connected.  This makes sense once you understand that each client connection is serviced by a separate Samba smbd daemon, which when started, itself reads smb.conf.  Hence it is possible for Samba's behavior to vary depending on the client that has connected.  For example, an external shell script can be executed when a client initially connects to perform various tasks (e.g., logging the date and time of the connection).  The client's architecture (WinNT, Win98, etc.) can be passed into the script by using the %a variable as a command line argument, making it possible for the script to operate in ways that are specific to the Windows version in use.

; user-specific...
;
; g primary group associated with the UNIX username (%u)
; G primary group associated with the NetBIOS username (%U)
; H home directory associated with the UNIX username
; u UNIX username
; U NetBIOS username

Samba is all about effacing fundamental operating system differences between UNIX and Windows.  For example, the owner, group and permissions concepts of UNIX have no exact equivalents in any version of Windows.  Ditto for hard links, symbolic links, device files, etc.  However, Samba has to work within the framework of the security features imposed by the UNIX kernel, which means that every Windows username (aka NetBIOS username) that is to be used with Samba must map to a valid UNIX username, who must, in turn, have a home directory somewhere in the file space accessible to Samba.

Further complicating matters is the concept of a NetBIOS workgroup (the workgroup parameter you define in Windows networking), which has no real analog in UNIX.  In that regard, it is customary for one NetBIOS group to be defined for all machines.  If your installation requires the use of multiple NetBIOS groups, you will need more than one server, since Samba can only be a member of one such group (which is also true of a real Windows machine).

;disk share specific...
;
; p NFS automounter path to share's root directory
; P share's root directory, not necessarily identical to the
; parameter passed in %p
; S share name as seen in NetHood

References to the above three variables are useful within smb.conf statements that deal with specific disk shares.  In Windows-speak, filesystem resources on one machine that can be accessed by another are called shares (a kind of New Age, touchy-feely term for what we UNIX dinosaurs might call an NFS export).  A Samba disk share exposes part of the underlying UNIX filesystem to Windows clients, to which they can gain access via normal Windows methods (e.g., Network Neighborhood -- NetHood -- or by mapping drive letters).  As on a real Windows server, you would normally expose only a limited part of the filesystem in this way.  You definitely would not want to expose areas like /bin or /etc to PC clients -- unless, of course, you like fixing busted systems.

The recommended practice is to set up a directory tree (possibly on a completely separate disk from the root disk, as I have done on our office server) and make everything under it the Windows filesystem.  I usually refer to the root of this tree with a symbolic link named vfs ("virtual filesystem") so I can relocate the entire mess without having to change all references within smb.conf.

One of the interesting features of Samba is that it can map NFS exported filesystems into the virtual Windows filesystem that Samba creates for its clients.  The p variable (that's a lower case 'p') tells Samba the local path that has been mapped to the particular NFS filesystem being shared (if a term such as automounter doesn't mean anything to you you need to read up on NFS in general).  The P variable, on the other hand, points to the actual location of the exposed portion of the filesystem, that is, the UNIX pathname, such as /vfs/profiles.  Note that a Windows client would not actually see /vfs/profiles in NetHood, but would instead see a share name such as PROFILES (if that's the name that was assigned).

; printer share-specific...
;
; f spool filename (generated by Windows client)
; j UNIX print job number, e.g., hp2250a-3241
; p UNIX printer name
; s fully qualified spool filename

As with disk resources, you can expose your UNIX printers to Windows clients.  The mechanism by which this is done will be described later when we get to the printer shares part of smb.conf.  References to the above four variables are useful within smb.conf statements that deal with specific printer shares.

; d current server process ID -- different for each connected user
; h server's DNS host name
; L server's NetBIOS name
; N NIS home directory server, if defined
; v Samba version, e.g., 3.0.2

With the lone exception of the %d variable, the above variables define information that is specific to the host machine on which Samba is running.  %d defines the UNIX process ID (PID) on a per daemon basis.

; miscellaneous...
;
; R negotiated SMB protocol level
; T current date & time
; $(v) shell environment variable, e.g., %$(PATH)

The above are self-explanatory.  %R is seldom used in the normal course of events but could be useful for debugging certain types of network problems that you hopefully will never encounter.  Incidentally, if you refer to shell variables in smb.conf make sure that they are properly defined by whatever starts Samba.  Otherwise, Samba's error log will quickly fill up with possibly cryptic complaints.

; GLOBAL DEFINITIONS
;
[global]

The structure of smb.conf strongly resembles a typical Windows .ini file.  Sections within the file are demarcated by bracketed words, such as [global].  The following statements are a series of assignments, with a parameter name on the left hand side of the expression and one or more parameters on the right hand side.  As a general rule, case doesn't matter unless referring to specific UNIX resources (such as directory names), where, as always, case does matter.

The [global] section refers to parameters that affect all aspects of Samba's operation.  Some global parameters can be overridden by reassignments within share definitions.  This feature allows you to define defaults for most cases and then create exceptions for specific shares.

; basic server definitions...
;
browsable= yes
deadtime= 30
domain master= yes
local master= yes
netbios aliases=  alarms-bcs
netbios name= unifismb
os level= 65
preferred master= yes
server string= BCS Technology -- Samba V%v
workgroup= bcs

The above (in the order given) tell Samba that by default all shares on this server should be visible in NetHood; idle Samba sessions should be killed after 30 minutes if no files are opened; this server is the Windows domain master browser; it is also the local master browser (which would matter if other Samba and/or Windows machines are interested in assuming that role); this server responds to the NetBIOS names alarms-bcs (an alias I use with an alarm clock feature on our system) and unifismb (its primary NetBIOS name); that of all the machines on the network, this one has the highest probably of winning browse master elections -- we've "rigged" the elections by setting the os level real high; this machine is the preferred master browser if more than one such machine exists on the subnet; the phrase BCS Technology -- Samba V%v will appear as a comment associated with this server when viewed through NetHood (where the Samba release version will be inserted by the %v variable); and that the NetBIOS workgroup is bcs., which is also the name of the Windows domain supported by this system.

Speaking of browsing, note that only NT/2000/2003 and XP professional Windows versions are capable of being domain members and master browsers.  95/98/ME can execute a domain log-in but cannot act as a domain member or master browser.  XP home edition is totally unsuitable for client-server environments, something that you should keep in mind when you get ready to buy a new PC.  Actually, my opinion of XP home is that it isn't suitable for much of anything, except for dumbing down the machine to the intellectual level of a trained gorilla and executing the worm de jour.  :-)

; network configuration...
;
bind interfaces only=    yes
hosts allow= 127.0.0.1 192.168.100.
interfaces= net1
keepalive= 180
name resolve order= wins host lmhosts bcast
socket options= TCP_NODELAY SO_RCVBUF=16384 SO_SNDBUF=16384

Here's where things get a little more complicated.  The particular machine from which this smb.conf was copied is multi-homed, with one of the two network interfaces directly routed onto the Internet with a static IP address.  I don't want Samba exposing anything to the outside world, so I added the first, second and third statements to limit the scope of Samba's connectivity.  The first statement tells Samba to not automatically scan the system for network interfaces on which to advertise services, which it would do by default.  The hosts allow statement defines the subnets and machines from which I am willing to allow connections to Samba.  In this case, anything on the (internal) 192.168.100 subnet is acceptable.  The local host loopback address (127.0.0.1) is required because I told Samba not to go looking for interfaces to link up with.  As is the case with the majority of UNIX applications that utilize networking, Samba will not correctly function if it cannot communicate with the loopback device.

interfaces = net1 tells Samba which of the machine's network interfaces through which it is to communicate -- implying that any other interfaces present in the server should be ignored.  Without this specification, Samba would listen for connections on all both network interfaces, which would be contrary to the hosts allow statement.  Such an ambiguous condition would undoubtably populate Samba's running log with complaints about unauthorized attempts to connect as various and sundry external machines probed the server for a way in.  Absent these parameters, Samba will accept connections from any interface, and from any client, subject to further authentication rules that you might implement.  Incidentally, you could specify an IP address in place of the net1 parameter and further qualify that address with a CIDR (Classless Inter-Domain Routing) suffix.  For example, interfaces = 10.1.2.10/29 would tell Samba, in effect, to accept traffic from the 10.1.2 subnet, with masking to 29 bits (i.e., 255.255.255.248 would be the subnet mask).  Naturally, such a subnet would have to be accessible to the machine -- you'll quickly find out if it isn't when you go to start Samba!

keepalive = 180 tells Samba to send keepalive packets to each client at 3 minute intervals.  This is a mechanism that allows Samba to detect when a client goes down and is a required parameter with SCO OSR5.  With other UNIX flavors the SO_KEEPALIVE socket option can be used to achieve the same result.  Without periodic keepalive checks, Samba smbd daemons might continue to uselessly run for a while (see deadtime above) if the clients they were serving crashed or otherwise unceremoniously went offline, thus wasting server resources.

The name resolve order = wins host lmhosts bcast parameter tells Samba how to resolve NetBIOS machine names to IP addresses.  In this example, Samba would first consult its WINS (Windows Internet Naming Service) database, which it builds from information sent by clients as they go on-line.  If that failed, Samba would next do an nslookup operation (i.e., consult with DNS if configured), followed by a lookup in the lmhosts file if present (seldom used anymore on most systems).  If all else fails, Samba will try to achieve resolution by resorting to subnet broadcasts.

socket options = sets network socket options that Samba may negotiate with the kernel when establishing network connectivity.  The available options and parameters are somewhat system-dependent.  The above socket options were ones that I arrived at by experimentation in an effort to optimize performance.  If you go too far astray with the SO_RCVBUF and SO_SNDBUF values, you may either hurt performance due to excessive packet fragmentation or exceed a system-defined limit on the maximum permissible packet size, the latter which may prevent Samba from starting.  The 16384 values are a good balance between avoiding fragmentation and making best use of available network resources.  Your system's mileage may vary.

; default share settings...
;
hide dot files= yes
kernel oplocks= no
level2 oplocks= no
map archive=    no
map hidden= yes
map system= no
oplocks= no
wide links=     no

The above parameters are defaults that apply to all disk shares that are defined later in smb.conf.  In UNIX, a file whose name begins with a . (e.g., .profile) is normally invisible to regular users in ls listings.  The hide dot files parameter tells Samba to honor that feature, causing such files to behave as though the Windows hidden attribute has been applied.

Windows has a feature called opportunistic locks (oplocks) which is touted as a performance enhancement in situations where one workstation would lock all or part of a file as a prelude to updating the file's content.  The theory is that the station that locked the file could relinquish the lock in specific situations where another workstation needs short-term access to the same file (usually a passive read operation).  Unfortunately, oplocks are not entirely trustworthy and some Windows applications will choke on them.  Therefore, I never enable oplocks because I can never be sure that all installed software on all clients will work with them.  The kernel oplocks parameter is for use only with those UNIX versions that support them (OSR5 doesn't).  Do not enable them unless you are sure they are supported, and only if you enable oplocks and level2 oplocks.  My advice is to steer clear of oplocks.

The three map... parameters allow you to map Windows filesystem attributes into the UNIX environment.  UNIX directories and files do not have equivalents to any of these attributes, so what Samba does is map them onto various permission bits associated with the file.  When viewed on the UNIX side, files with such mappings will appear to have odd combinations of permissions.  You should enable these features if you wish to copy Windows files to the server and retain these specific attributes.

The wide links parameter tells Samba whether Windows clients can follow symbolic links that lead outside of the scope of defined disk shares.  For example, with wide links off, a symlink in a disk share that points to, say, /etc/ntp.conf would not be honored by Samba.  With wide links on, the symlink would be valid for Windows access, which could be hazardous to the health of the file in some cases.  I do not recommend the enabling of wide links on any production Samba server.

; user & machine access configuration...
;
domain logons= yes
encrypt passwords= yes
guest account= vfs
guest ok= no
invalid users= daemon bin sys adm uucp nuucp auth \
asg cron sysinfo dos mmdf network \
backup nouser listen lp audit
valid users= dave kenna stan steggy vfs

The above parameters define some of the essential elements of user connectivity.  The domain logons and encrypt passwords parameters say that this machine will authenticate Windows users logging into the bcs Windows domain (which was defined earlier), using encrypted passwords (encryption is a bit of a misnomer: Windows passwords are actually repeatable hashes and are not all that difficult to crack).  Also implied by these parameters is that a Samba password database must have been created so as to authenticate users.  You can allow clear text passwords if you choose by setting encrypt passwords to no, which is not recommended, but may necessary with older versions of Windows (e.g. Windows 95 OSR 1.0) that do not support the hashing of passwords.

Speaking of user access, 2000/XP has what is known as a "guest account," which is basically an unauthenticated user who is granted limited access to the system.  You can do likewise in Samba by assigning a Samba user with the guest account parameter and by setting guest ok = yes.  Printing usually requires that a guest account statement be present.  Note that although I defined a guest account, I explicitly disabled guest access because our office system is a Windows domain that requires appropriate user authentication.  If you decide that guests are okay, be careful to limit their access to system resources.  Well-intentioned but clueless users can break things for you, and you will be just as clueless trying to figure out who did what to what.

On all UNIX systems there are a number of user accounts that are associated with various administrative functions that may have greater privileges than what you are willing to extend to Windows users.  You do not want to ever give such accounts access via Samba, which is the purpose of the invalid users parameter.  This is especially important if the server is exposed to the Internet.  If a username is present in this statement, that user cannot connect, even though their username is later specified in a valid users list.  Incidentally, the above invalid users example illustrates how to continue a logical line onto several physical lines.  This is a handy mechanism for use when the number of parameters associated a statement is large.

The valid users statement specifies which Windows users are allowed to connect to Samba.  This parameter can be used to limit access to a Samba server when it is on the same subnet as another Samba or Windows server.  Within share definitions, this list can be overridden by a more restrictive list, which will be illustrated later on.  Absent a valid users list, any user could theoretically connect to this machine unless their username appears in the invalid users list.  The general rule is that if a user is not listed in the invalid users list and there is no valid users list, then that user will be granted access rights, subject to authentication.

;; logon drive maps the given drive letter to the user's home directory on
;; WinNT/2K/XP clients -- it has no effect on Win95/98/ME...
;
logon drive=  p:
;
;; logon home is for storing Win95/98/ME user profiles, which are further
;; organized on a machine-by-machine basis...
;;
logon home=   \\%L\%u\%$(WINPROF)\%m
;
;; logon path is for storing WinNT/2K/XP user profiles, which are further
;; organized on a machine-by-machine basis...
;;
logon path=   \\%L\%$(WINNTPROF)\%u\%m
;
;; a separate log-in script (batch file) is created for each user on this
;; system...scripts can be customized as required...
;;
logon script= %$(SMBUSERSCRIPTS)\%u.bat

The above statements define how Samba will behave at the time of a valid user log-in.  During the domain log-in sequence Samba can be configured to provide various services that establish a desired degree of connectivity.  The above parameters specify what those log-in services will be. logon drive = p: defines the drive letter that will be mapped to the user's home directory share when s/he logs on to a 2000/XP machine.  To establish the same relationship with a 95/98/ME unit it is necessary to insert a net use p: /home statement into the user's log-on script (batch file).  Incidentally, you are free to use any drive letter than has not already been assigned in Windows.  I use p: because each user's home directory is "private" storage that only s/he and the system administrator (root) can get into.

Despite what it might suggest, logon home = \\%L\%u\%$(WINPROF)\%m has nothing to do with the user's home share.  What it does is tell Samba where to store 95/98/ME roaming profiles (the information Windows generates for each user about the desktop layout, Internet Exploder...er...Explorer cookies and history, etc. -- logon home is ignored by 2000/XP machines).  At log-on time, the client machine, if 95/98/ME, will retrieve the roaming profile from the server and use it to present the user interface.  logon home is an example of using Samba  and shell variables to tailor the statement to the specifics of each user's environment.

Recall from above that %L is the Samba server's NetBIOS name (unifismb in this case), %u is the user's UNIX username and %m is the client machine's NetBIOS name.   On our office system, WINPROF is a shell variable that specifies the subdirectory under the user's home directory where 95/98/ME roaming profiles will be stored (WINPROF is defined in a custom configuration file called /etc/default/samba, which I use to externalize some aspects of the Samba environment for easier adaptation to different systems).  When Samba parses \\%L\%u\%$(WINPROF)\%m, it will substitute the relevant values for each variable and assign the result to the logon home parameter.  If, for example, the log-in user is tony, the roaming profile subdirectory is .winprofile and the client machine on which Tony is working is bcsa0001, the statement will expand to logon home = \\unifismb\tony\.winprofile\bcsa0001.

It is essential that you generate a separate profile subdirectory for each 95/98/ME client so as to preserve the specifics of each machine's configuration, especially the desktop layout.  If you make the (common) error of using one subdirectory to store this user's roaming profile, e.g., \\unifismb\tony\.winprofile -- no client machine specified in the path, the retrieved profile will be that of the last machine on which Tony was working.  If Tony had been working on bcsa0001, logs out and then logs on to bcsa0002, he will see bcsa0001's environment, which, unless both machines are identically configured and have identical copies of the same software, would be wrong (and could possibly result in a major mess).

logon path = \\%L\%$(WINNTPROF)\%u\%m is to 2000/XP machines as logon home = \\%L\%u\%$(WINPROF)\%m is to 95/98/ME boxes: it defines where 2000/XP roaming profiles are to be stored.  The principles of parameter substitution apply as they do with logon home. WINNTPROF is another shell variable that is defined in my /etc/default/samba configuration file.

Following authentication, Windows will attempt to execute a log-on script (aka batch file -- MS-DOS mumbo-jumbo stored in a text file on the server) as specified by the logon script = %$(SMBUSERSCRIPTS)\%u.bat statement.  Log-on scripts may used to set up the client machine's environment, such as drive letter and local printer mapping, sync the workstation's clock to the server's, etc.  Here's an example of such a script:

rem @echo off
net time \\unifismb /set /yes
net use lpt2: \\unifismb\hp2250_00 /yes
net use lpt3: \\unifismb\oki395 /yes
net use h: \\unifismb\apps
net use p: /home
net use r: \\unifismb\public
net use s: \\unifismb\shared
rem pause

I won't go into any detail as to what these statements mean, except to explain that, in theory, most anything that can be executed in a standard MS-DOS batch file could be used in a log-in script.  By the way, although log-on scripts are stored on the UNIX filesystem they must be formatted as DOS-compatible files.  In other words, each line of text must be terminated with an ASCII carriage return (<CR>) and ASCII line feed (<LF>), which is not the same as the UNIX convention of terminating lines with <LF> alone.  Be aware of this requirement if you decide to use a UNIX text editor such as emacs or vi to create log-on scripts.  Otherwise, you will find yourself chasing your tail trying to figure out why your scripts aren't working.  Within the vi editor you can insert a <CR> by typing Ctrl-V and then typing Ctrl-M or the Enter key.

Important to note is that the initial Windows search path for log-on scripts is hard coded into the form \\<server_NetBIOS_name>\netlogon (netlogon is a special disk share that will be discussed later on).  Here again, parameter substitution may be used to tailor the statement to the user who is being authenticated.  Our friend Tony, upon logging in to our unifismb Samba server, would probably see a brief "console" window appear on his desktop, in which statements read from \\unifismb\netlogon\smbscripts\tony.bat would execute and any output caused by those statements -- including errors -- would appear.  The smbscripts component of the path is derived from %$(SMBUSERSCRIPTS), which is also defined in my custom configuration file, /etc/default/samba.

Hint: debugging log-on script errors can be somewhat difficult because the console window normally closes as soon as all script statements have been executed.  If you need to "single step" a script consider placing a pause statement in appropriate locations in the script, or a single pause at the very end to hold open the window so you can read any errors that were generated.

min passwd length= 4
null passwords=    no
smb passwd file=   /etc/samba.d/smbpasswd
security= user
username map=      /etc/samba.d/smbusers

The above statements define some additional security parameters that Samba will use while authenticating users.  The first and second entries are self-explanatory.  Unless your system has very limited access, you do not want to allow null passwords, that is, allow users to not have to use a password to get in.  min passwd length and null passwords do not conflict with each other: if a minimum password length is stipulated but null passwords are acceptable, a user could get in with no password, but if a password were used, it would have to be at least min passwd length characters.

smb passwd file = /etc/samba.d/smbpasswd and username map = /etc/samba.d/smbusers tell Samba where to look for the files that identify authorized users. smbpasswd stores usernames, their corresponding UNIX UID's and the hashes of their passwords, while smbusers maps NetBIOS usernames to UNIX equivalents when there are differences between the two (smbpasswd also stores details about machine trust accounts that are associated with 2000/XP clients that are part of the Windows domain).

The security of Samba itself is no better than the security given to these two files.  Whatever directory you choose to store these files, be sure to set its ownership to root:sys and permissions to rwxr-x--x. smbpasswd should have rw------- permissions and smbusers should be set to rw-r--r--.  Both files must be owned by root:sys as well.  I cannot overemphasize how important this is.  Without proper protection of these files a malicious user could, for example, hand-enter him/herself into the smbpasswd file and thus become an authorized Windows user.

username map = /etc/samba.d/smbusers accounts for a sticky configuration issue that arises when a user's UNIX and NetBIOS usernames are different.  Here's a simple one-line smbusers example:

gwash = "george washington"

This entry tells Samba that Windows user george washington (George's NetBIOS username, which is surrounded by double quotes so Samba will not think that it is really two names) is actually UNIX user gwash.  Hence you may map long-winded NetBIOS usernames such as Bill Clinton to more succinct UNIX equivalents, such as hillary.  If smbusers is present but a specific Windows user is not mentioned within, that user's UNIX username will be assumed to be the same as his NetBIOS username.  In all cases, UNIX directory and file ownerships map to UNIX usernames, not to NetBIOS usernames.  Be careful to distinguish between the two means of refering to a user.

Lastly, security = user means that access to Samba-controlled resources will be granted or denied on a user-by-user basis, which is the default for all current Windows versions.  Only the oldest versions of Windows are incapable of functioning at the user security level (and thus should be avoided).

; logging...
;
debug timestamp= yes
;
;; uncomment next entry to generate a log for each client machine
;;
;log file=       %$(LOGDIR)/%m.log
;
log level= 0
max log size=    50
syslog= 0

Samba has extensive logging capability that may be used to keep track of how well the server is running, as well as to identify specific problems that may appear for any number of reasons.  The first statement tells Samba to prefix each log entry that it generates with a date and time stamp, which is essential to debugging errors that are sporadic in nature.  The following log file = %$(LOGDIR)/%m.log statement tells Samba to generate a log for each client machine that connects to the server.   I place this entry in every smb.conf that I prepare but leave it commented out unless I need machine-specific details.  Use this feature sparingly to prevent a bunch of huge logs from choking out your filesystem.  You could  also edit the %m parameter to a specific client name (e.g., bcsa0001) to log only one machine's activity.  The %$(LOGDIR)parameter also comes from my custom /etc/default/samba configuration file and usually points to /vfs/logs.

The log level tells Samba how much detail should be logged.  log level = 0 says only log items of significant interest, errors in most cases, or unauthorized attempts to connect.  As you increase the log level the amount of detail in the log files will likewise increase.  Any log level higher than 3 will increase the level of detail to the mind-numbing category -- such information is primarily of value to Samba developers.

The max log size = 50 parameter specifies how much any Samba log will be allowed to grow in kilobytes.  When a log reaches max log size kilobytes it will be renamed and a new log will be started.  syslog = 0 states that Samba should not make entries into the server's syslog.  If you wish to have Samba write log data to syslog change syslog = 0 to anything higher than 0.  For example, syslog = 1 will map Samba complaints onto syslog's LOG_WARNING status level.  As with log level, increasing the syslog value will increase the amount of verbiage recorded for posterity.  I generally recommend against syslogging Samba complaints, as syslog gets enough junk as it is without Samba adding to the load.

; resource discovery & naming...
;
wins support= yes

Essential to the correct operation of Windows networking is the presence of some mechanism that can map NetBIOS machine names on to IP addresses.  The possible methods available with Samba are DNS lookups, WINS, LMHOSTS lookups and subnet broadcasts.  If your server is expected to support both 95/98/ME and 2000/XP clients WINS is necessary for best performance and reliability.  95/98/ME machines cannot use DNS at all and LMHOSTS files are a royal pain to maintain (there has to be an up-to-date copy of LMHOSTS on every machine).  Absent DNS, WINS and LMHOSTS, all machines will resort to subnet broadcasts, which are grossly inefficient, and unreliable.  Also, broadcast packets usually cannot jump through routers, which means that resource disccovery will not function across subnets unless WINS or an LMHOSTS file is used.

In order for WINS to work there has to be an accessible WINS server somewhere in the domain.  Adding to the complication, a Windows or Samba server acting as a local master browser has to be present on each subnet (thanks to Microsoft's greediness) to support cross-subnet browsing.  One of these servers can also act as the WINS server -- be sure to pick the most reliable machine to perform this critical function.

Samba is capable of acting as a WINS server, a feature that you may enable with the wins support = yes statement.  wins support = no will disable WINS on this server, thus requiring that another machine on the network handle name resolution requests.  In such a case, a wins server = <ipaddr> statement must be entered into smb.conf to tell Samba where to direct its WINS discovery queries (where <ipaddr> is the IP address of the WINS server).  Note that wins support and wins server statements are mutually exclusive: Samba will complain at startup if both statements are present in smb.conf.

;miscellaneous...
;
max smbd processes= 25
message command=    /usr/local/bin/setalarm %f %s
printing = sysv
read raw= yes
time server= yes

The above global parameters fall into the "everything else" category.  One of the problems frequently encountered in Windows networks is resource hogging.  With Samba, each connected client starts a new instance of the smbd daemon, thus consuming some percentage of the available machine resources.  If your Samba server is also expected to support other UNIX activities you should include a max smbd processes = n statement to limit the number of Samba daemons that can be concurrently running.  Without this statement, Samba will spawn as many new daemons as required to support all connections.  In some cases, a runaway condition can occur that could take down the server.  Avoid setting this value any higher than necessary to support the maximum expected load (one smbd daemon per connected client plus the "master" daemon) plus two or three "spares."

The message command = statement tells Samba what to do when it is the target of a WinPopUp message.  By default, Samba will not respond to a WinPopUp, which will cause the sending client to report an error (except Windows for Workgroups 3.11).  You can use the message command = statement to define a specific action that your server should take when it receives a WinPopUp.  A guest account must be defined (see above) and must be assigned to a UNIX user who actually exists and has some access privileges.

On our office server, it is possible for users to set an alarm by sending a specially formatted WinPopUp message to the server.  In the message command = /usr/local/bin/setalarm %f %s statement, the %f parameter identifies the sending user and the %s parameter identifies the name of a file that contains containing the message -- this file is created by Samba in response to the WinPopUp.  The setalarm  shell script parses the file identified by %s and uses the information within to set up the alarm as an at job.  When the at job is finally executed the server will find out where the user is logged in (it uses a script that parses the output of Samba's smbstatus utility) and will send a WinPopUp to him or her announcing the alarm.

If you decide to implement a message command function on your server, be sure that whatever is executed immediately returns control -- in other words, execute the program asynchronously.  Otherwise, the WinPopUp function on the client machine will stall until message command has finished.

printing = sysv tells Samba the type of print subsystem supported by the operating system.  Acceptable definitions are BSD, AIX, LPRNG, PLP, SYSV, HPUX, QNX, SOFTQ, and CUPSprinting = sets a default for use by any subsequent printer shares that do not specify another method of printing.  In this case, printing = sysv says that absent more specific information, Samba should submit and control print jobs using AT&T UNIX System V style commands and options.  There is no default for this statement, so something should be present somewhere in smb.conf to tell Samba how to handle printing.

read raw affects overall network performance as related to how Samba processes SMB read data requests. read raw = yes allows any given SMB packet to be up to 64 KB in size, which will generally produce the best throughput on most systems.  Unless you are running a WWG 3.11 client on your system you should not change this setting (it defaults to yes).

Lastly, time server = yes tells Samba to act as a time source for any Windows client that asks for the date and time (the proper MS-DOS syntax is net time \\<server /set /yes).  If you enable Windows time services be sure to configure ntpd to keep the server's clock accurate.  Naturally, ntpd is of limited value if the server has no Internet access.

; ======================
; Disk Share Definitions
; ======================

A large part of what Samba does is expose a portion of the UNIX filesystem to Windows clients.  On the client side, the filesystem looks just as it would on a real Windows machine, save that some of the bizarre behaviors for which Windows is famous won't be evident.  There are some minor differences that are an unavoidable part of mapping UNIX file space over to Windows, but in practice, these differences usually are not a cause for concern.

In order to allow Windows clients to read and write on the UNIX filesystem it is necessary to define one or more disk shares in Samba, a process that is analogous to setting up shares on a real Windows server.  Most shares that you might define will be for general purpose use by all users of the system, while a few shares will be available only under specific conditions.  In all cases, each share definition starts with a bracketed name that will appear as the share name in NetHood, such as [shared] or [public] (with three exceptions, all disk share names are arbitrary).  Following the bracketed name will be a series of statements that will tell Samba what it needs to know to properly present the share to clients.  The only statement that is absolutely necessary is the one that indicates what part of the UNIX filesystem is being shared.  Other statements may be added as needed to control share access or to define specific actions that should occur when a user connects to or disconnects from the share.

For the purposes of discussion, I broadly classify disk shares as static and general.  Static shares define resources that may be needed to support basic Windows networking functionality -- they have analogs on a real Windows server and must be present if the Samba server is to act as a primary domain controller.  General shares support whatever functionality is required by the local installation and may be added or subtracted as needs change.

; static share definitions...
;
[homes]
comment= %U's private storage
browsable= no
create mask= 0600
directory mask= 0700
path=           %$(VFSDIR)/private/%u
root postexec=  %$(SMBSCRIPT) O %m %I %G %u %U %P
root preexec=   %$(SMBSCRIPT) I %m %I %G %u %U %P
volume= %U
writeable= yes
csc policy= disable

The layout of the above definition is typical for all shares.  The definition starts with its name, [homes] in this case.  Samba will assume that all statements that follow the share name are part of the share definition until a new bracketed name is encountered or EOF has been reached.  [homes] is one of the special Windows shares that is expected to be found on the PDC.  It defines the per user private server storage that is (should be!) available to each authenticated user.  Without a [homes] share, a log-on script statement such as net use p: /home will not work -- there wouldn't be anything to call home.

Following the share name is a comment, which can be any reasonable text.  The comment will appear in NetHood when the server is browsed.  In the above comment, the %U variable will be replaced with the user's NetBIOS name.  Comments are not required but are a good idea, especially for shares that are generally accessible.  Without a suitable comment, users might be forced to browse the share to figure out what it contains.  Obviously, the comment should make sense to your users -- try to avoid cryptic computer mumbo-jumbo!

The balance of the statements define the share's characteristics.  browsable = no means that the share cannot be browsed by the "general population," even though there was an earlier browsable = yes statement in the [global] section.  This is an example of how a share statement can override the effects of an earlier global statement.  Since this is a user's private share you wouldn't want all and sundry seeing it when they go into NetHood (it will be browsable by its owner).  The browsable = no statement only affects this particular share definition.

The create mask = and directory mask = statements define how UNIX filesystem permissions will be applied to newly created files and directories controlled through this share.  The perms are exactly as you would specifiy with the chmod command and in this case, would create new files with rw------- perms and directories with rwx------ perms.  As this is private storage, you must restrict access only to the owning user.

The path = statement identifies the part of the UNIX filesystem that is mapped to the share.  The statement path = %$(VFSDIR)/private/%u is special in that it will vary depending on the identity of the connecting user.  Recall that each client connection spawns a new instance of the smbd daemon and that each daemon reads smb.conf in its entirety at start up.  Therefore, the [homes] share will map to a different part of the private subdirectory, based upon the UNIX username of the connecting user.  If VFSDIR is defined as /vfs and the user's UNIX name is kenna, the path will be /vfs/private/kenna and the displayed share name will be kenna (not homes, as one might think).  If the log-on script for this user includes the statement net use p: /home, the p: drive on kenna's PC will be mapped on this server to \\unifismb\kenna.  Naturally, the directory should be accessible only to user kenna.

The root postexec = %$(SMBSCRIPT) O %m %I %G %u %U %P and root preexec = %$(SMBSCRIPT) O %m %I %G %u %U %P statements specify actions that are to occur on the server when the user disconnects and connects, respectively, to his/her home share.  SMBSCRIPT (defined in my /etc/default/samba configuration file) defines the program that will be executed as root (with all the risks that that entails).  This is another custom script that I have developed to automate some new user server-side tasks, as well as to maintain a log of each user's comings and goings.  It makes use of several Samba variables to adapt its operation as needed.

The volume = %U statement is used to define the volume name that will be seen when an MS-DOS style directory listing of the share's root is displayed.  It affects the Volume in drive x is part of the directory listing.  If the user's NetBIOS name is tony and the mapped drive letter is p: tony will see Volume in drive P is tony.

The writeable = yes statement means what it says: the disk space assigned to this share is treated as read/write by Samba, subject to the underlying UNIX permissions.  Note that if the disk space is set to read only in UNIX, Samba will treat it as read only, even in the presence of a writeable = yes statement.  writeable = no would make the share read only, even though UNIX permissions have no such restriction.  An alternate form of writeable = no is read only.

The csc policy = disable statement controls whether clients may cache file contents associated with this share (csc means client-side caching).  Caching and oplocks have often been blamed for mangled files and for that reason, I normally disable this feature (as well as oplocks).  I just can't see how a modest performance improvement can be justification for possible bizarre behavior.  In addition to disable, options are manual, documents, and programs.

[netlogon]
comment= network services
browsable= no
create mask= 0640
directory mask= 0750
path= %$(NETLOGONDIR)
root preexec=   %$(SMBSCRIPT) S %L "" %g %u %U %P
volume= netlogon
writeable= no
csc policy= disable

netlogon is the second of the three static shares.  If this machine is to support domain log-ons this share and the associated subdirectory must exist and should be configured exactly as shown to protect it from tampering.  If an attempt is made by a 2000/XP client to log on without this share being present Windows will complain and depending on how the client was configured, may refuse to continue the log-on session.  Following initial user log-on, the Windows client will look in this share for a log-on script as defined by the earlier logon script= %$(SMBUSERSCRIPTS)\%u.bat statement in the global section.  The search is relative to the netlogon share.  Most of the statements for this share are similar to homes, except that it is made read only to protect it from casual tinkering.

[profiles]
comment= 2000/XP user profiles
browsable= no
create mask= 0600
directory mask= 0700
path=           %$(VFSDIR)/%$(WINNTPROF)
volume= profiles
writeable= yes
csc policy= disable

The profiles share is the third static share.  This is where 2000/XP roaming profiles are stored and is referred to by the logon path = \\%L\%$(WINNTPROF)\%u\%m statement in the global section.  If this machine is to support domain log-ons this share and its associated subdirectory must exist and should be configured exactly as shown to protect it from tampering.  If an attempt is made by a 2000/XP client to log on without this share being present Windows will complain and depending on how the client was configured, may refuse to continue the log-on session.  Be sure that each authorized user has a profile subdirectory in this share before allowing them to log on.  That subdirectory must have the user's name, be owned by the user and have access limited to the user (rwx------ permissions).

;general share definitions...

The following share definitions provide general storage access to all clients, subject to rules that may be imposed on a per share basis.  I will not go into detail on every item, as context and reference to items already covered will be sufficient information in most cases.

[apps]
comment= shared applications
browsable= yes
create mask= 0640
directory mask= 0750
force user= vfs
path= %$(VFSDIR)/apps
volume= shared apps
write list=     vfs
csc policy= disable

In the above definition there are some access control features not previously discussed.  force user = vfs means that the effective UNIX user for this share will always be vfs, regardless of the identity of the Windows user seeking access.  On our system, vfs is a pseudo-user who has administrative rights on all workstations and is also the Samba administrator.  Only vfs has write permissions on this share, which is specified by the write list = vfs statement.  All other users have read only permissions.

[install]
comment= installation software
browsable= yes
create mask= 0640
directory mask= 0750
force user= vfs
path=           %$(VFSDIR)/install
valid users=    vfs
volume= install
write list=     vfs
csc policy= disable

In this share, the more restrictive valid users = vfs statement prevents anyone except vfs from gaining access, which makes sense in this case because vfs is the administrator.  Incidentally, if you need to add more than one user to such access lists, separate the names with whitespace and quote names that have more than one word (e.g., "system administrator").

[logs]
comment= runtime logging
browsable= yes
create mask= 0640
directory mask= 0750
force user= vfs
path= %$(LOGDIR)
valid users=    steggy vfs
volume= logs
writable= yes
csc policy= disable

Here two users are allowed access to the logs share.  Although writable = yes would seem to give everyone write permissions on the share, the valid users = steggy vfs statement keeps everyone out except users steggy and vfs.

[public]
comment= public read-only access
browsable= yes
create mask= 0640
directory mask= 1750
force user= vfs
path=           %$(VFSDIR)/public
volume= public
write list=     steggy vfs
csc policy= disable

[shared]
comment= public read-write access
browsable= yes
create mask= 0640
directory mask= 0750
force user= vfs
path=           %$(VFSDIR)/shared
volume= shared
writable= yes
csc policy= disable

The above two shares are typical of general access storage that you might define on your system.

[cdr00]
comment= UNIX CD-ROM 00
browsable= yes
force group= bin
force user= bin
path= /cdrom
writeable= no
csc policy= disable

This is an example of how you could share the CD-ROM in the server.  Of course, this share won't be valid unless the CD-ROM filesystem has been mounted onto the /cdrom directory.  The bin:bin user and group mapping should work with most systems.  The writeable = no statement assures that Samba understands that a CD-ROM is a read only filesystem.  Incidentally, writable and writeable are synonyms.

; ==============
; Printer Shares
; ==============

Printer shares expose UNIX printing resources to Windows clients, allowing users to route their print jobs to a server-controlled printer.  This sort of arrangement reduces the number of printers that have to be purchased and maintained, which can effect a sizable cost-savings over time.

The share definition syntax is similar to that for a disk share, except some statements that are specific to Samba printing are used.  On the client side, the share is seen as a Microsoft network printer and is accessed as it would if it existed on a real Windows server.  The client needs to have the appropriate drivers installed and configured.  One client-side configuration setting that matters is spooling: it should be disabled in most cases, as the UNIX spooler will off-load that task from the client.  The only reason you would enable client spooling would be if the UNIX print command associated with the share bypasses the lp spool service and writes directly to the device file for the target printer (which setup should be avoided if possible).

[hp2000_00]
comment= ink jet in sales office -- HP 2000c
printer= hp2000a
path=          %$(VFSDIR)/spool/hp2000a
print command= /usr/local/bin/smblp %p hp2000a %L %m %s
printable= yes

In the above definition, the printer = statement defines the Windows printer name, which can be different than the share name.  The path = statement defines the subdirectory on the server where clients will submit their print jobs.  This directory should be owned by the guest user defined in the global section (vfs on our system, who is also the administrator), have same UNIX group as the system's Samba user and should have rwxrwx--T permissions.  On our system, I have separate spool paths for each printer, primarily as an aid to debugging printing problems.

As the client machine generates the print job, the output will collect in the location defined by path =, with the client assigning a unique filename.  When the job has been fully spooled, Samba will execute the optional print command to drive the target printer.  If no print command has been defined Samba will use standard lp subsystem commands to drive the printer, the particular commands having been determined by the printing = statement in the global section.  On our system, I use a custom script (smblp) that in addition to driving the printer, can also send the user a WinPopUp in case the print job encounters an error.  The %s parameter to smblp is the name of the client-generated spool file.

Lastly, printable = yes simply means this printer share is enabled and users can print to the associated printer.  Not including this statement in the share definition or saying printable = no will make the associated printer inaccessible to everyone.  Speaking of accessibility, all of our office printers are accessible to all users, which works well for many situations.  However, your needs may differ, especially if your environment includes printers designed for a specific purpose.  For example, if you have a high-end color laser printer for printing advertising matter, you might not want the lady down the hall using it to print pictures of her family, cat, dog and the neighbor's pet monkey.  You can restrict access to a select few users by adding a valid users statement to the appropriate printer share.  The syntax is identical to that for a disk share.

After editing smb.conf always check it for errors with the testparm Samba utility.  Doing so may save you a lot of grief, as errors caused by improper smb.conf statements can be exasperating to debug, especially if you are new to Samba.  Finally, there are many more smb.conf statements available than I mentioned herein.  If you have a specific requirement that wasn't covered in this article you need to visit the Samba website and peruse their documentation.  Did I also mention books?  Check out the Samba site for recommendations.  Before you know it, you'll be on your way to becoming a Samba advocate when you see what it can do for you and your business!



Got something to add? Send me email.





(OLDER) <- More Stuff -> (NEWER)    (NEWEST)   

Printer Friendly Version

-> -> AN ANNOTATED GUIDE TO SAMBA CONFIGURATION


1 comment



Increase ad revenue 50-250% with Ezoic


More Articles by © BigDumbDinosaur