Chapter 3 described basic Samba configuration—assigning NetBIOS and workgroup names to the Samba server, setting password options, and so on. In most cases, though, a Samba server’s primary responsibility is to provide file and printer shares to clients. This is the topic of this chapter.
This chapter begins with a look at file shares—how to define them, set access options, and so on. Printer shares are basically just variants of file shares, but because they must interface with the Linux printing system, this chapter describes a few details of Linux’s printing architecture, including the basics of configuring the Common Unix Printing System, the most popular printing software on Linux. Another printing-related feature is the delivery of printer drivers to Windows systems; SMB/CIFS and Samba support special options to handle this task. Finally, this chapter concludes with several example shares that demonstrate common file- and printer-sharing scenarios.
At many sites, file sharing is the most
important duty of a Samba server. File shares can store
users’ data files and programs run by many users,
exchange data between users, be part of a network backup system, and
serve other purposes. (Examples of shares for many of these roles
appear in the later Section 4.5.) You can create a basic
file share with just one line in
fine-tuning it to do what you want will take more lines. Options you
may want to tune include those that control write access to the
share, those that adjust how Samba reports filenames to clients, and
those that influence local Linux or client filesystem security
A minimal file share consists of a single line that contains the share name in square brackets:
If you include this line in
smb.conf at the end
of the file, or with another share definition immediately following
it, Samba will create a file share called SAMPLE. This share will be a read-only share
corresponding to the
/tmp directory on the
server. Chances are these options aren’t the ones
you want. At a minimum, you’ll almost certainly want
to use the
path parameter or its synonym,
directory. These parameters tell Samba what
directory to use as the root of the share you define. For instance,
/var/samba/somedir, you might enter a
share definition like this:
[sample] path = /var/samba/somedir
This entry creates a file share that appears in Windows network
browsers as SAMPLE, just like the
previous definition; but this share provides read-only access to
/var/samba/somedir. Note that the share
name (SAMPLE in this example) and
the name of the directory to be shared
/var/samba/somedir) are unrelated. Of course,
they could be related, and doing so can help you
administer your system, but doing it isn’t strictly
necessary. Other share-level options you might want to use include
This parameter’s value defaults to
Yes, which makes the share available. If you want to temporarily disable a share, you can set
No. (This won’t work for the
[homes]share, which is described in the later Section 4.5.1.) The effect is much the same as commenting out or deleting the entire share definition.
This share-level parameter is a share’s equivalent of the global
stringparameter; it creates a description of the share that’s visible from clients’ file browsers.
Shares that are browseable appear in file browsers on clients. Those that aren’t browseable don’t appear in browse lists but are still accessible to users who type the share name into an access tool. By default, Samba makes file shares browseable, but you can hide them by setting
No. This parameter is also usually set to
[homes]shares, as described in Section 4.5.1.
The default for Samba file shares is to
provide read-only access. Of course, many types of shares must be
read/write in order to be useful, so Samba provides a way to provide
this type of access—in fact, several ways. The
ok parameters are all
synonyms, and when any of them is set to
read/write access to the share becomes possible. The
only parameter is an
antonym for these parameters; setting
read only = No has the same effect as setting
writeable = Yes.
In addition to the critical
writeable parameter or
one of its synonyms, several other parameters affect write access to
the share based on other features:
This share-level parameter doesn’t strictly affect write access; instead, it provides a list of users who are denied all access to the share. All users who aren’t explicitly listed are granted access to the share. You can specify a Linux group by preceding its name with an at sign (
@) or a plus sign (
+), as in
@sign first attempts to look up a netgroup name and then uses the local group database. The plus sign uses the local group database alone.)
You can provide a list of users who are permitted only to read the files on an otherwise read/write share with this share-level parameter.
This share-level parameter is the opposite of
users; it provides a list of users who are permitted to access the share. Attempts by other users to access the share are denied. You can specify a Linux group by preceding its name with an at sign (
@) or a plus sign (
+), as in
This share-level parameter is the opposite of
list; you provide a list of users who are permitted to write to an otherwise read-only share. It’s often used to specify share administrators who may add files to a share.
Yes, one of its synonyms, or one of the modifier
parameters, is enough to provide read/write access to a shared
directory from Samba’s perspective, but you must
also consider the underlying Linux permissions. In most cases, Samba
uses the access rights of the user who initiated a connection. For
instance, if the user linnaeus is
accessing a share, and if linnaeus doesn’t have write
access to a directory, Samba won’t be able to save
files in that directory for this user. Thus, you should consider user
access rights from a traditional Linux permissions perspective when
preparing file shares. Modifying Samba’s permissions
system is described in Section 4.1.4, and practical examples of
some systems are described in the Section 4.5.
Samba provides some extremely powerful options for modifying both read and write access to its shares. As a general rule, though, it’s best to keep it simple; overuse of sophisticated access control tools can create a complicated configuration that will easily break. Worse, you might inadvertently create a security hole that a user can exploit accidentally or deliberately.
Windows and Linux make different assumptions about filenames. Because SMB/CIFS is so strongly associated with Windows and related clients, Samba is designed around the Windows assumptions. The problem comes in translating filenames stored on a Linux filesystem into the format expected by Windows. Samba provides many parameters that help you accomplish this goal. Broadly speaking, differences come in a few areas:
- Filename length
Most Linux filesystems provide long filenames—typically up to 255 characters. Windows clients can use long filenames, but they also expect to see short filenames (eight characters with a three-character extension, or so-called 8.3 filenames) in addition to the long filenames. Older DOS clients can use only the short filenames. DOS and 16-bit Windows programs require short filenames even when they’re run from more modern versions of Windows. Because Linux native filesystems store a single filename and don’t automatically create shortened filenames that correspond to long filenames, Samba generates short filenames on the fly, using a process called filename mangling . Samba provides several parameters that enable you to fine-tune this mangling process.
- Filename case
Linux filesystems are case-sensitive ; two filenames that differ only in case, such as
AFile.TXT, are considered unique. Both files can exist in a single directory, and if you enter the filename’s case incorrectly, Linux won’t be able to access an existing file. Windows, by contrast, is case-retentive: filename case is preserved when you save a file, but the OS doesn’t care about case when you specify a filename. This means that two files that differ only in case can’t exist in the same directory. DOS is even more primitive; it uses completely case-insensitive filenames. DOS stores all filenames entirely in uppercase. (DOS programs can usually access lowercase filenames on a Samba server, though.) Samba provides case-sensitivity options, some of which interact with filename mangling options, to accommodate these different case-handling systems.
- Character sets
Traditionally, filenames have been stored on both Windows and Linux filesystems using the American Standard Code for Information Interchange (ASCII). ASCII is inadequate, though, for storing filenames that contain letters from non-Roman alphabets, such as Cyrillic or Arabic letters. An older solution to this problem involved code pages , which are basically alternatives to ASCII. A more modern solution uses Unicode , which uses a 16-bit encoding system for characters, thus greatly increasing the number of characters that can be used in filenames. Samba must have a way to translate between either system and the filenames actually stored on the disk.
As a general rule, Samba’s default options work well. These defaults cause Samba to present the illusion of a case-retentive filesystem with both long and short filenames. Samba does this by looking for files that differ only in case when a provided filename can’t be found, and by creating mangled filenames to go along with long filenames when the client requests them. Sometimes, though, you may need to tweak these settings by using some parameters:
This share-level Boolean parameter controls whether Samba treats filename access in a case-sensitive way. The default value of
Noworks well with DOS and Windows clients, and, in fact, DOS and Windows 9x/Me clients will likely misbehave in various ways if you set this option to
Yes. Windows NT/200x/XP is better at handling case-sensitive filenames, but
Nois still the preferred option for it. Some Linux and Unix clients may work better with
Yes, but this setting usually isn’t required even for these clients. Samba 3.0.6 introduced the
Autovalue for this option and made it the default. This setting enables the server to detect some clients’ preferred case sensitivity and should work with the Linux
cifsfilesystem, among others.
When set to the default value,
Yes, this share-level Boolean parameter causes Samba to store new files in the same case as provided by clients. When set to
No, Samba converts filenames to the case specified by
case(described shortly). Setting this option to
Nocan be handy if you have clients that generate ugly all-uppercase filenames, and you want to access the files from other clients.
short preserve case
This parameter works just like
case, but it applies only to short (8.3) filenames.
This share-level parameter accepts values of
Lower. It defaults to
Lower, but this default is meaningless unless you set either
No. If you do so, Samba converts newly created filenames to the specified case.
When set to
Yes(the default), this share-level Boolean parameter causes Samba to generate mangled filenames for files longer than the DOS 8.3 limits. These names are delivered in addition to the regular filenames, so this option won’t cause problems for clients that expect long filenames. This feature is most important for DOS clients, but it can also be important for Windows clients that run DOS or 16-bit Windows programs.
Ordinarily, Samba doesn’t mangle short filenames that don’t match the client’s case expectations. If you set
Yes, though, Samba mangles filenames that aren’t entirely in the case specified by
default case. Chances are this action won’t be necessary, and in fact it’s likely to produce very ugly results, but it’s conceivable you’ll run across some DOS programs that choke on lowercase names, in which case using this option may be your only solution. This option was eliminated over the development of the 3.0.x versions of Samba.
This share-level option specifies pairs of filename wildcards that should be mangled in particular ways. For instance,
*.htm)converts all filenames that end in
.htmlso that they end in
.htminstead. Unlike other mangling options, this one applies to all filenames, not just those delivered to DOS or as short filename alternatives to Windows clients. This option is not being actively maintained and so may develop bugs in the future.
Samba uses one of two methods to create mangled filenames. You can specify which method to use with this global parameter, which accepts values of
hash2. The latter option, which is the default with Samba 3.0 and later, produces filenames that bear less resemblance to the original than does the first, but
hash2is also less likely to produce collisions —identical hashes derived from different original filenames.
This global parameter sets the number of characters to be preserved from the original filename when creating a mangled filename using the
hash2mangling method. The default value is
1, but you can improve the intelligibility of mangled filenames by increasing this value (the maximum is
This global Boolean parameter defaults to
Yes, which tells Samba to support Unicode filenames provided by clients. Normally there’s no need to change this parameter. It’s available only in early 3.0.x releases and has been dropped in later versions.
You can tell Samba what code page to use when communicating with older clients that don’t support Unicode with this global parameter. You specify code pages using three-digit codes preceded by the string
CP, as in
CP850(Latin 1, which works well for most North American systems) or
CP866(Cyrillic). This option is new with Samba 3.0.
This global parameter sets the name of the character set Linux uses for its filenames. The default value is
UTF8. This value stands for Unicode Transformation Format 8, which is a method of encoding Unicode in an 8-bit character set such as ASCII. Ordinarily, you won’t change this option, which is new with Samba 3.0.
client code page
This global parameter was used through the 2.2.x versions of Samba as a way to specify what code page the client used. It’s since been replaced by
charset. This parameter takes code page numbers without a preceding
CPstring, as in
This global parameter was used in Samba through the 2.2.x series to tell the server how to encode different code pages on the server’s filesystem. Values were character set values, such as
ISO8859-1(Latin 1) or
KOI8-R(Cyrillic). This parameter has been replaced by
unix charsetin Samba 3.0 and later.
This list of parameters may be intimidating (and
I’ve even left out some of the more exotic
options!), but in most cases, you need not change any of these
values. When dealing with DOS clients, though, you might want to
case option, if you want to force DOS filenames to
appear in all-lowercase on the server. (This will make them look
better in most non-DOS clients.) Changing
prefix can improve the intelligibility of mangled
filenames on DOS clients. Linux and Unix clients can benefit from
Yes, but this change
isn’t usually required. (For versions of Samba that
Auto for this parameter, using this
feature is usually better, too.) If your users regularly create files
with non-ASCII filenames, you may need to investigate the various
character set and code page options.
You can place filename options in OS-specific configuration files and
include parameter with the
%a variable in the
section to load them only for appropriate client OSs. For instance,
then create files called
smb-Samba.conf, and so on, in which you store
OS-specific options. Table 3-1 describes the
%a variable and its possible values.
Linux uses Unix-style access control mechanisms, which provide read, write, and execute permissions for each of three classes of users: the file’s owner, the file’s group, and all other users (a.k.a. world access). Linux also provides access control lists (ACLs) in most of its native filesystems, although Linux ACL support is still new and few programs are designed with it in mind.
Windows and SMB/CIFS, by contrast, originally provided little in the way of access controls; users who mounted a share were given access to all files on the share. Windows NT/200x/XP, though, provides ACLs similar to Linux ACLs. Integrating these two access control heritages can be tricky sometimes, particularly because Samba must support both older clients that don’t use ACLs and newer clients that do. In order to accomplish this task, Samba provides a series of options that affect the way it treats Linux file ownership, Linux file permissions, DOS-style filesystem features, and ACLs. Recent versions of Samba also support Unix extensions , which are extensions to SMB/CIFS that more directly support Unix-style ownership and permissions. Samba’s Unix extensions support is intended for Linux or Unix clients.
Linux’s local file
security model relies heavily on the concept of file
ownership—both the file’s owner and the
file’s group. In order to interface Samba clients
with this system, Samba provides several
parameters that affect
the ownership of files a user creates. In conjunction with existing
files’ permissions, Samba’s
ownership parameters also influence whether a user is granted the
right to read or change an existing file. The most important of these
parameters are as follows:
You can pass a local Linux username to this share-level parameter to have Samba treat all file accesses as if they originated with the specified user. For instance,
linnaeustells Samba to give the user read access to those files that linnaeus can read, write access to files that linnaeus can write, and so on. Files created when accessing the share are owned by linnaeus. In addition, unless you use
group, the group used for accesses is set to the specified user’s default group. The default is to use the account of the username provided by the user (or mapped by
username map, if you employ that parameter).
This share-level parameter is similar to
force user, but it applies to the group used for file accesses. A synonym for this parameter is
This Boolean share-level parameter tells Samba whether to accept guest accesses to the share—that is, accesses without the benefit of a password. If
guest ok = Yesand if a guest logon occurs, Samba uses the account specified by
guest accountfor accesses, much as if
force userhad been used. A synonym for this parameter is
public. Note that the global
map to guestparameter must also be set appropriately before this parameter will work.
This global option sets the account used for guest accesses, as authorized on a share-by-share basis by
guest ok. The default value is a compile-time option, but it’s usually set to
map to guest
This global parameter controls the conditions that trigger a guest logon. Samba accepts values of
Never(Samba never accepts a guest logon; this is the default value),
Bad User(Samba accepts a guest logon when a user specifies an invalid username), and
Bad Password(Samba accepts a guest logon when a user specifies an invalid username or password).
Generally speaking, the best approach is to use
Samba’s default options. Forcing Samba to use
particular users or groups can be a convenient way to avoid having to
set permissions properly on files (including ensuring that Samba sets
them in a sensible way), but forcing a user or group also means that
you’ll lose information. Should strange files begin
appearing, for instance, it may become very difficult to track down
who’s creating the files if you use
doesn’t go very far in Linux. To be effective,
ownership must be paired with file permissions (a.k.a. the file
mode). Linux’s traditional
Unix-style permissions apply read, write, and execute permissions to
each of three classes of users: the owner, the group, and the world.
Each of these permissions is a single bit, for a total of nine bits
of permission information. These may be expressed as a string, as in
rwxr-x---, in which a dash (
stands for no permission and an
x stands for read, write,
or execute permission, respectively. Alternatively, ownership may be
expressed as three octal (base-8) numbers corresponding to the 3-bit
value for read, write, and execute permission, as in 750 for
rwxr-x---. A leading 0 is often added to the octal
form of the mode; higher values signify some special file-permission
bits. A leading dash is often added to the string value. This dash is
replaced by other characters to signify particular file types, such
d for a directory.
Because DOS and Windows know nothing about Unix-style permissions, and therefore don’t pass information on appropriate permissions when creating new files, Samba must generate this information. It does so as specified by these parameters:
This share-level parameter specifies the default and maximum permissions to apply to new files created by the client. It’s expressed in an octal form, as in
744(the default value). Note that clients can remove write access by setting the DOS read-only flag. If you enable any execute permissions (by specifying an odd value for any of the three octal digits), they can also be removed by the client if the appropriate DOS attribute mappings are configured, as described in Section 188.8.131.52. A synonym for this parameter is
This share-level parameter works just like
create mask, except that it applies to directories rather than files. Because Linux requires the execute permission bit to be set on directories for some read operations, this parameter typically uses octal values of 7, 5, or 0, as in
755(the default value). A synonym for this parameter is
This share-level Boolean parameter defaults to
No, but if you set it to
Yes, it overrides
directory mask. In this case, files and directories acquire permissions based on the values of their parent directories. (The execute bits of parent directories are stripped when creating files, however.) For instance, if a directory has a mode of 750 and a user creates a subdirectory in that directory, it will also have a mode of 750.
You should give careful thought to the values you specify for these parameters. Setting permissions too loosely can enable users who don’t own the file the ability to read (or potentially even write) files and directories to which they should have no access. On the other side, setting these values too strictly can deny access to users who should be able to read or write files. Precisely what policy is right varies from one site to another, and perhaps even one share to another. Several examples appear in the Section 4.5.
DOS and its descendent operating systems, including Windows, support several filesystem flags that don’t appear in Linux or Unix filesystems. In order to support these flags, Samba can optionally map them onto the execute permission bit, which DOS and Windows don’t use. Several parameters control this mapping:
The DOS/Windows archive bit is set when a file is created and cleared when it’s backed up with certain backup tools. If you set
Yes(the default), Samba maps this bit to the owner execute bit.
The DOS/Windows hidden bit signals certain programs, such as file managers, to hide the presence of a file from users. The file is still accessible but won’t appear in file listings. This bit can be used to hide files that would likely confuse users. If you set
= Yes(the default is
No), Samba stores this bit using the world execute bit.
The DOS/Windows system bit marks certain critical OS files as such. Most file managers hide these files, and some utilities treat them differently from other files. Chances are you won’t be storing system files on a Samba server, so the default value of this parameter is
No, but if you set it to
Yes, Samba stores this bit in the group execute bit.
store dos attributes
This share-level Boolean parameter defaults to
No. When set to
Yesand when the preceding three options are all set to
store dos attributescauses Samba to store the DOS-style archive, hidden, and system attributes as extended attributes (EAs) on the Linux filesystem. EAs are supported only on the 2.6.x and later kernels and require the
user_xattrfilesystem mount option. They also require explicit filesystem support, which is present in ext2fs, ext3fs, ReiserFS, JFS, and XFS, but Linux doesn’t support EAs in most non-Linux filesystems. One advantage of this parameter is that it supports storing attributes for directories as well as files. This parameter was added to Version 3.0.3 of Samba.
The first three of these parameters interact with the settings of the
create mask parameter; if
create mask or the
appropriate mapping parameter disables a particular execute bit,
users can’t set the matching DOS/Windows flag. The
mapping works both ways; if you enable a mapping and then create a
file under Linux that has execute permissions set (say, a script), it
appears to Samba clients with the archive, hidden, or system bits
set. For this reason, if you wish to let users legitimately create
executable Linux files, leave these parameters at the default; this
prevents the files from disappearing from view in Samba clients
because of hidden or system bits appearing on these files. Disabling
the archive bit (either by setting
map archive = No or by setting a
create mask value
that disables access to the user execute bit) prevents files created
on Samba clients from appearing under Linux as executable files.
Under Linux, the equivalent of hidden files are dot
files—files whose names begin with dots
(.). If a share will be accessible both from Samba
clients and from Linux logins, you may want to ensure that
hide dot files is set to
as it is by default. This option tells Samba to set the hidden bit on
all Linux dot files, no matter what the setting s of the world
execute bit and the
map hidden parameter are.
ACLs provide a finer-grained method of access control than do Unix-style permissions. Windows NT has long supported ACLs on its New Technology File System (NTFS), and SMB/CIFS also supports ACLs. This support has only recently started to become common with Linux, though. In particular, the 2.6.x kernel series adds ACL support to most common Linux filesystems—as of the 2.6.7 kernel, ext2fs, ext3fs, JFS, and XFS all support ACLs. (With earlier kernels and most common Linux filesystems, you had to patch the kernel to add ACL support. Consult http://acl.bestbits.at for details.)
Samba has long supported the SMB/CIFS ACLs as a tool for accessing
Unix-style permissions from Windows NT/200x/XP systems. If you use an
ACL-enabled filesystem, this same support gives Windows users fuller
access to the Linux filesystem’s ACL features. This
support is, however, a compile-time option. To determine whether your
Samba binary includes ACL support, type
HAVE.*ACL. The result is a list of the ACL
features in the smbd binary. The following
parameters control this support:
This Boolean share-level parameter is similar to
permissions, but it tells Samba to copy ACLs from a parent directory when creating new subdirectories. The default value is
nt acl support
This Boolean share-level parameter is the key ACL feature; setting it to
Yestells Samba to enable SMB/CIFS ACL support, mapping it to the server’s Unix-style permissions and, if supported, local filesystem ACLs.
This share-level parameter tells Samba which Unix-style permissions should be accessible to clients. The default value (
777) gives users access to all the Unix-style permission bits.
directory security mask
This share-level parameter works just like
security mask, but it applies to directories rather than files.
Samba’s ACL features require the client to know more
about the underlying Linux accounts than is necessary for most other
purposes. Samba can most easily provide this information in user- or
domain-level security modes (set with the
parameter, as described in Chapter 3).
Attempting to use ACLs when using share- or server-level security is
likely to cause problems. In the case of share-level security,
username mapping can vary between logins; for server-level security,
the authentication against the logon server is too convoluted to be
traced properly by Samba.
Whether your underlying filesystem supports ACLs or not, clients access these features using the file’s Properties dialog box, which can be obtained by right-clicking the file in a Windows file browser and selecting Properties from the resulting dialog box. The Security tab provides access to the ACLs or Unix-style permissions, as shown in Figure 4-1.
Precisely how you manipulate ACLs differs between Windows versions. Figure 4-1 shows a Windows 2000 dialog box, in which users can click on the appropriate box in the Allow column to enable or disable access. If your Samba server system supports true ACLs, users can also click the Add button to add a new ACL that gives some other user access to the file. Older versions of Windows used a more awkward ACL-access mechanism that involved more dialog boxes. Even if Samba supports ACLs, these features aren’t accessible from Windows 9x/Me or from the Home version of Windows XP.
Most Samba features are designed with
Microsoft-style clients (DOS, Windows, or OS/2) in mind. A few,
though, cater to other operating systems;
extensions is one that may be of particular
interest. It’s a global Boolean parameter that tells
Samba whether to support a set of SMB/CIFS extensions that deliver
Unix-style filesystem data—Unix-style ownership, Unix-style
permissions, and a few special file types such as hard and symbolic
links. This parameter defaults to
Yes in Samba 3.0
and later and shouldn’t cause problems for non-Unix
clients; thus, chances are you don’t need to change
In order to do any good, the
parameter must be paired with a client that can use them. As the name
suggests, these extensions are intended for use by Unix-like OSs;
Windows clients can’t use them. Some Linux clients
can use them, though, including Samba’s own
smbclient and the
filesystem type code for Linux’s
mount command. Chapter 6
describes how to use the Unix extensions from a Linux client
Linux client-side Unix extensions support is still rather limited. Enabling it on the Samba server shouldn’t do any harm, but for Linux-to-Linux (or Linux-to-Unix) file sharing, NFS still offers better support for Unix-style filesystem features than does Samba. This may change in the future as the Unix extensions support matures, both in Samba and in the Linux kernel.