The original version of this article was first published on IBM
developerWorks, and is property of Westtech Information Services. This
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux Documentation team.
This document is not actively maintained.
Introduction to Samba, Part 3
Getting Samba to samba: The configuration stage
A brief review
Here's a listing of the smb.conf that we've been working with:
Code Listing 1.1: /etc/smb.conf
workgroup = YOURWORKGROUP
security = user
encrypt passwords = yes
guest account = guest
# wins server = IP address of WINS server
# wins support = yes
local master = yes
os level = 99
domain master = yes
preferred master = yes
# hosts allow = 192.168.1. 127.
# interfaces = eth1
Adding some shares
While this smb.conf file is functional, all it does is share the
/tmp directory with Windows by creating a share with the name of
"tmp". Not too exciting. Let's create another share that could be more useful.
Add the following lines to your smb.conf and restart Samba.
Code Listing 1.2: Adding an FTP share
If you have an ftp site or some kind of file archive on your Samba server, you
can use something like this to share the data over the network. The
writeable=no parameter tells Samba that no one should be allowed to
create or modify files on this share. Anyone who has a valid Samba account set
up will be able to access this share.
An exciting share
OK, I know what you're thinking. This still isn't too exciting. How about
sharing a home directory? Here's how:
Code Listing 1.3: Sharing a home directory
comment=Home directory for drobbins
path = /home/drobbins
force user = drobbins
read only = no
valid users = drobbins administrator
This one is a lot more interesting. Adding something like this to your
smb.conf will allow you to share a home directory. In this example,
a "drobbins" share is created. This shares the contents of
/home/drobbins over the network. Fortunately, however, thanks to
the valid users line, not just anyone can access this hare. This line
causes Samba to reject access by anyone other than the "drobbins" or
"administrator" account. Since I'm using Windows NT, I'm often logged in as
administrator. In such situations, it's nice to still be able to access the
"drobbins" share. Such a valid users line allows this to happen.
You'll also notice the use of the read only parameter. As you might
guess, read only is the opposite of the writeable parameter. We
could have just as easily replaced this line with writeable=yes. This
means that Samba will permit writing to this particular share, as long as you
have the proper permissions to do so. Since the Samba "drobbins" user maps
directly to the Unix "drobbins" user, and drobbins happens to be the owner of
the /home/drobbins directory and its contents, writing and
modifying files will be permitted.
Have you ever created a file in your home directory as root, and then tried to
modify it when you're logged in as a normal user only to be denied write access?
This seems to happen all the time to me. To fix the problem, I need to
su, chown drobbins.drobbins filename and then exit from
root. Finally, I'm allowed to modify the file.
I bring this up because a similar problem can occur when you share out home
directories and access them using different Samba users. Consider the following
situation. I access a share as administrator and created a file. Normally, this
file would be owned by administrator and it would not be modifiable by the
drobbins user. If drobbins tried to modify it, access would be denied.
Fortunately, Samba has the force user option that works around this
situation. The force user option will cause all actions performed on
files (on a particular Samba SMB/CIFS share) to be performed using a single Unix
account. In my "drobbins" share example, this means that any files that
administrator creates will actually be owned by drobbins, preventing any
ownership conflicts. Since the "drobbins" share contains the contents of my home
directory, I like to keep everything in it owned by the drobbins account.
Before we head on to the next topic, I should mention the comment
parameter. This allows you to complement your share with a descriptive comment
visible from Windows.
Sharing lots of home directories
So, we've covered how to share a single home directory. But what do you do if
you happen to administrate a server that contains hundreds of users, all of whom
want to be able to access their home directories from Windows? Fortunately,
Samba has a special share just for this purpose called "homes". Here's how it
Code Listing 1.4: Sharing multiple homes
comment=Home directory for %S
valid users = %u administrator
writeable = yes
browseable = no
As I mentioned, this is a "special" share. It doesn't work like ordinary shares.
Samba recognizes the special identifier [homes] and treats this share
One of the most unusual things about this share is the use of the
browseable=no parameter. This particular option causes a share to be
invisible under the Network Neighborhood, and it's normally used to deter those
malicious users who may be tempted to "explore" any share they can see. But why
use it here?
The answer is a bit tricky. You see, the "homes" share does create a share
called "homes". But that particular share is of no use to us. It doesn't do
anything, so we hide it. What the "homes" share does do for us is quite
tremendous. It tells Samba to automatically create home directories on the fly
for each individual user. For example, let's say our "drobbins" share wasn't
defined in smb.conf and we explored the Network Neighborhood as NT
user "drobbins". We would find a share called "drobbins" that would behave
identically to our original "drobbins" share. If we accessed Samba using the NT
user "jimmy", we'd find a perfectly configured "jimmy" share. This is the beauty
of homes. Adding one special share causes all home shares to be properly
Now, how does it work? When the "homes" share is set up, Samba will detect which
NT user is accessing Samba. Then it will create a home share that's been
customized for this particular user. This share will show up in the Network
Neighborhood as if it's a normal, non-dynamic share. The NT user will have no
idea that this particular share was created on the fly. Let's look at what each
particular option does.
The comment parameter uses the %S wildcard, which expands to the actual
name of the share. This will cause the "drobbins" share to have the comment
"Home directory for drobbins", the "jimmy" share to have the comment "Home
directory for jimmy", etc. The path parameter also contains the wildcard
%u. %u expands to the name of the user accessing the share. In
this particular case, %u is equivalent %S, so we could have used
path=/home/%S instead. This allows Samba to dynamically map the share to
the proper location on disk.
Again, we use macros in the valid users= line so that only the owner of
the share and administrator are allowed to access it. force user uses a
macro too, so that all file access will be performed by a single account. And of
course we make the share writeable for any authenticated users. While we use the
browseable=no parameter, the dynamically-created shares will be
browseable when they are created. Again, this just hides the non-functional
We've seen a couple of handy techniques to use when creating shares. In this
section I'll cover several popular options that allow you to customize Samba
functionality on a per-share basis. All share-related options can also be placed
in the [globals] section to set a default value for all shares.
The comment= parameter is a very handy option to make your Samba system
look more professional from the Windows side. It allows you to specify a comment
that accompanies a particular share intended to describe its contents. When
specifying comments (especially when using "homes"), I often use the %S
macro, which expands to the name of the share.
path= is one of the most fundamental Samba share parameters. It allows
you to set the path to the directory to be exported. Note that by default any
symlinks in this directory tree can be followed. So it is possible for users to
"jump out" of the directory tree. From the Windows side, they will have no
indication that they are following a symlink. It will just appear as a regular
file or directory. We'll look at several parameters that can change this
behavior to make Samba more secure.
force user= is one of my favorite parameters. It forces all file
modifications to be performed by the account of a single user. You'll want to
use the valid users= option often with this one so that you can limit
access to select users. Since all file operations are performed using a single
user account, one of the side effects of force-user= is that you can't
look at the Unix file permissions to figure out who did what. Thus for writeable
shares, the force user= option should be accompanied by reasonable
security defaults. Without this option, all file operations will be performed by
the Samba user who is accessing the share.
Code Listing 2.1: force user example
One simple way to enhance your security is to make certain shares invisible.
Shares are browseable by default under the Network Neighborhood. Making them
invisible can help to deter unwanted hacking attempts. But this should not be
used as the only means of security. Just because a share isn't listed in the
browse list does not prevent it from being accessed from Windows. It just
decreases the amount of information you may potentially be providing to a
malicious user. To access a hidden share, you can type its UNC name into the
Run... dialog box. For example, the hidden share on myserver called
'test' can be accessed by typing \\myserver\test from Windows.
Code Listing 2.2: browseable example
The available= option, which is 'yes' by default, is just a handy way of
disabling a share without commenting it out or erasing it from the
smb.conf entirely. available=no will make the share inactive
after Samba is restarted.
Code Listing 2.3: available example
Definitely take advantage of the valid users= option to restrict access
to certain shares. By default, any authenticated user will be allowed to access
a Samba share. You can refer to a valid NIS netgroup or Unix group by appending
an "@" to the group name.
Code Listing 2.4: valid users example
valid users = drobbins @wheel
dont descend= specifies directories in the share that Samba should not
enter. This can be handy to prevent Samba from entering a directory that
contains recursive symlinks, or to restrict access to irrelevant directories
like /proc and /dev. Be sure to test out your dont
descend= settings to make sure they are working. You may need to switch
dont descend= /dev to dont descend= ./dev, for example.
follow symlinks= normally defaults to 'yes' and will cause Samba to
follow all symlinks, even if they redirect Samba to files or directories outside
of the exported directory tree. Setting follow symlinks to 'no' will turn off
this functionality, and prevent symlinks from being followed at all. Turning off
follow symlinks does eliminate a potential security hole and should be done when
symlinks are not needed or required.
Code Listing 2.5: follow symlinks example
The volume= option can cause Samba to associate a "volume name" with the
particular share. This is especially useful if you are using a Samba share to
export the contents of a CD-ROM. Many installation programs will expect to find
an exact volume name on the CD, without which they won't work.
Code Listing 2.6: volume example
volume=My Favorite CD
Samba uses the create mask to set the proper permissions on newly
created files. The create mask defines which permissions newly created
files will allow. The supplied octal number will be combined with the desired
permissions using a binary and operation. This causes any permissions
not in the mask to be dropped from the new file's permissions.
Code Listing 2.7: create mask example
create mask= 0755
directory mask= works in a manner similar to create mask=. It
specifies an octal number that defines those permissions allowed for the new
The many options of smb.conf
In this section, we've covered only those smb.conf options that
are the most essential in configuring a useful and secure Samba system. Samba
itself has many additional configuration options that you may find useful. To
find out more about them, check out the smb.conf main page, where they are
listed and described in detail. (See Resources.)
Printing from Samba
Samba's printer-sharing abilities come in handy and work well. To refresh your
memory, Samba allows you to export existing lpd-based printers so that Windows
clients can connect and print to them. One of the wonderful things about this
arrangement is that all printer-specific code is generated on the Windows side.
This means that your Unix system does not need to have explicit support for a
particular printer. As long as your Unix system is able to dump raw data to the
printer, it will work and work well. This even allows you to share and use
printers that are not fully functional in a pure Unix environment, such as my
Adobe PrintGear-based NEC SuperScript 870.
How Samba printing works
To get printing to work, you first need to get lpd working. While
lpd configuration is beyond the scope of this article, it's not too hard
and is described in detail in the Printing FAQ available at tldp.org. (See
Resources.) You'll want to configure your printers
to be "raw" printers by default, so that any data sent to the printer using an
lpr command is copied verbatim without any filtering or massaging. It's
easy to test lpd to make sure that it is configured in "raw" mode. On
the Windows side, install a printer driver for that particular printer that
prints to FILE:. Print a page from your favorite Windows word processor
and save it to file. Then copy it to your Unix machine and print it using
lpr. If you get correct output, you're all set to configure Samba to use
the printer automatically.
Samba print globals
To get Samba working properly for printing under a Linux system, you'll want to
add the following parameters to your [global] section:
Code Listing 3.1: Edit smb.conf to allow printing
If your printcap is located somewhere else, adjust the printcap name=
parameter accordingly. If you use a printing system other than standard BSD
lpd, consult the rinting= option on the smb.conf main
page for more information on how to get Samba to work with your printing system.
Now, setting up the printer share. This is what I have in smb.conf
for my printer. We'll use it as a model:
Code Listing 3.2: Example printer share
print command=/usr/bin/lpr %s
lprm command=/usr/bin/lprm -P%p %j
It is important to first understand the path parameter. When Samba accepts a
print job from Windows, it needs to store it somewhere on disk before Samba can
submit the job using lpr. The directory referred to by the path=
parameter should have Unix permissions 1777 so that anyone can write to this
directory. The print command= and lprm= lines are not usually
needed. Include them if you want to specify the exact path for your print
commands or if you need to pass any command-line parameters to lpr. Use
the above macros as an example. %s expands to the temporary file name,
%p expands to the printer name, and %j expands to the job number.
The printer= option, as you may guess, tells Samba which Unix printer to
print to. Make sure this printer is set up in raw mode. public=yes
allows even users with no password to connect to this printer. Eliminate this
option later if you want to tighten up security (you may want to replace this
line with a valid users= line to really tighten up security).
printable=yes tells Samba both that this share should be configured as a
printer, and to allow this share to accept print jobs.
After restarting Samba, you should be able to see the new printer from Windows.
At this point you should be able to install this printer on the Windows side
and fire off a test-page to your new, shared resource. (Windows will tell you
that you are installing a driver for the NULL printer. Don't worry. Just select
the correct printer driver from the list.) If for some reason printing doesn't
work, be sure to check /var/log/log.smb for any error messages. I
should also mention that there are tons of printer-related
smb.conf configuration options that you may find useful. I've just
touched on the most popular ones. Be sure to check out the
smb.conf main page to get familiar with all of them.
In this article we've covered the key elements of Samba functionality,
including sharing home directories and printing. I've also tried to highlight
several security-related parameters. But don't get the idea that this is all
there is to Samba. Samba is not only very powerful, but also very configurable.
It's designed to let you, the administrator, decide how and to what extent it
will be used in your organization. While quite a bit of manual
smb.conf configuration is involved in a Samba setup, the results
are well worth it because you can get everything working exactly how you want.
Samba has additional functionality that we haven't even touched on, including
the ability to become part of (or even control!) an entire Windows NT domain. I
encourage you to fully explore the potential of this extremely powerful tool.
Download Samba at the main Samba web
a password synchronization utility to set Samba and shadow passwords
SambaLink/Q is a
version-independent editor for the smb.conf file.
See the Printing FAQ at tldp.org.
Read Samba by Ed Weinberg.
(O'Reilly Publishing; 1999) is a comprehensive guide to Samba
administration, including such recent additions as integration with Windows
NT domains and the SWAT graphic configuration tool.
Visit the SWAT main
Check out Samba/iX,
a suite of programs that allow an HP e3000 running MPE/iX operating system
to provide service using Microsoft's Message Block (SMB).
Unleashed, by Steve Litt, with contributions from Daniel Robbins.