Linux in a Windows World

Chapter 4. File and Printer Shares

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.

Common File Share Options

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 smb.conf, but 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 features.

Defining a File Share

A minimal file share consists of a single line that contains the share name in square brackets:

[sample]

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, to share /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 files in /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 the following:

available

This parameter’s value defaults to Yes, which makes the share available. If you want to temporarily disable a share, you can set available = 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.

comment

This share-level parameter is a share’s equivalent of the global server string parameter; it creates a description of the share that’s visible from clients’ file browsers.

browseable

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 browseable = No. This parameter is also usually set to No for [homes] shares, as described in Section 4.5.1.

Setting Write Access

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 writeable, writable, and write ok parameters are all synonyms, and when any of them is set to Yes, read/write access to the share becomes possible. The read 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:

invalid users

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 @students. (The @ 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.)

read list

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.

valid users

This share-level parameter is the opposite of invalid 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 @students.

write list

This share-level parameter is the opposite of read 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.

Setting writeable = 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.

Tip

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.

Setting Filename Options

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 and 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:

case sensitive

This share-level Boolean parameter controls whether Samba treats filename access in a case-sensitive way. The default value of No works 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 case sensitive = No is still the preferred option for it. Some Linux and Unix clients may work better with case sensitive = Yes, but this setting usually isn’t required even for these clients. Samba 3.0.6 introduced the Auto value 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 cifs filesystem, among others.

preserve case

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 default case (described shortly). Setting this option to No can 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 preserve case, but it applies only to short (8.3) filenames.

default case

This share-level parameter accepts values of Upper and Lower. It defaults to Lower, but this default is meaningless unless you set either preserve case or short preserve case to No. If you do so, Samba converts newly created filenames to the specified case.

mangled names

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.

mangle case

Ordinarily, Samba doesn’t mangle short filenames that don’t match the client’s case expectations. If you set mangle case = 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.

mangled map

This share-level option specifies pairs of filename wildcards that should be mangled in particular ways. For instance, mangled map = (*.html *.htm) converts all filenames that end in .html so that they end in .htm instead. 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.

mangling method

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 hash and 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 hash2 is also less likely to produce collisions —identical hashes derived from different original filenames.

mangle prefix

This global parameter sets the number of characters to be preserved from the original filename when creating a mangled filename using the hash2 mangling method. The default value is 1, but you can improve the intelligibility of mangled filenames by increasing this value (the maximum is 6).

unicode

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.

dos charset

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.

unix charset

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 dos charset. This parameter takes code page numbers without a preceding CP string, as in 850 or 866.

character set

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 charset in 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 adjust the short preserve 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 mangle prefix can improve the intelligibility of mangled filenames on DOS clients. Linux and Unix clients can benefit from setting case sensitive = Yes, but this change isn’t usually required. (For versions of Samba that support 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.

Tip

You can place filename options in OS-specific configuration files and use the include parameter with the %a variable in the [global] section to load them only for appropriate client OSs. For instance, add include = smb-%a.conf to smb.conf and then create files called smb-WfW.conf, smb-Samba.conf, and so on, in which you store OS-specific options. Table 3-1 describes the %a variable and its possible values.

Setting Access Control Features

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.

Setting Linux ownership

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 smb.conf 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:

force user

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, force user = linnaeus tells 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 force 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).

force group

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 group.

guest ok

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 = Yes and if a guest logon occurs, Samba uses the account specified by guest account for accesses, much as if force user had been used. A synonym for this parameter is public. Note that the global map to guest parameter must also be set appropriately before this parameter will work.

guest account

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 nobody.

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 force user.

Setting Linux permissions

File ownership alone 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 r, w, or 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 as 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:

create mask

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 create mask = 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 4.1.4.3. A synonym for this parameter is create mode.

directory mask

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 directory mask = 755 (the default value). A synonym for this parameter is directory mode.

inherit permissions

This share-level Boolean parameter defaults to No, but if you set it to Yes, it overrides create mask and 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.

Mapping DOS-style flags

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:

map archive

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 map archive = Yes (the default), Samba maps this bit to the owner execute bit.

map hidden

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 map hidden = Yes (the default is No), Samba stores this bit using the world execute bit.

map system

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 Yes and when the preceding three options are all set to No, store dos attributes causes 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_xattr filesystem 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 either 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 Yes, 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.

Using ACLs

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 smbd -b | grep -i HAVE.*ACL. The result is a list of the ACL features in the smbd binary. The following parameters control this support:

inherit acls

This Boolean share-level parameter is similar to inherit permissions, but it tells Samba to copy ACLs from a parent directory when creating new subdirectories. The default value is No.

nt acl support

This Boolean share-level parameter is the key ACL feature; setting it to Yes tells Samba to enable SMB/CIFS ACL support, mapping it to the server’s Unix-style permissions and, if supported, local filesystem ACLs.

security mask

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.

Tip

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 security 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.

Figure 4-1. Windows ACL access tools work on Samba shares once they’ve been appropriately enabled

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.

Enabling Unix extensions

Most Samba features are designed with Microsoft-style clients (DOS, Windows, or OS/2) in mind. A few, though, cater to other operating systems; unix 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 it.

In order to do any good, the unix extensions 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 cifs filesystem type code for Linux’s mount command. Chapter 6 describes how to use the Unix extensions from a Linux client computer.

Tip

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.