Linux in a Windows World/Sharing Files and Printers/File and Printer Shares

From WikiContent

< Linux in a Windows World | Sharing Files and Printers
Revision as of 21:46, 11 March 2008 by Docbook2Wiki (Talk)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search
Linux in a Windows World

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:


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:

   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:

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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#The [homes] Share|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 server string parameter; 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 browseable = No. This parameter is also usually set to No for [homes] shares, as described in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#The [homes] Share|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.


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


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


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

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.


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.

Printing with CUPS

Although file shares are an important feature of many Samba servers, printer shares are also important. Before you can configure a Samba printer share, though, you must have a working local printer configuration. Most Linux distributions now use the Common Unix Printing System (CUPS; as the local printing software. Therefore, before moving on to describing Samba printer share configuration, I present some basic information on CUPS configuration.

Installing CUPS

Because CUPS is a standard part of most Linux distributions, it may be installed on your system already. Use your package tools to look for a package called cups. If it's not installed, your computer either has no printing system installed or it uses an older printing system, such as LPRng or BSD LPD.

If your system uses an older printing system, you can either uninstall it and install CUPS in its place or forgo CUPS and use the older system instead. Samba configuration is similar in either case, and if local printing is working to your satisfaction, leaving your current printing system in place is likely to be the less troublesome solution, so you may want to skip ahead to Section 4.3. If you want to switch to CUPS, you should uninstall your existing printing software, if it's installed. In an RPM-based distribution, the -e parameter to rpm can uninstall the software: rpm -e lprng uninstalls the lprng package, if that's what your system uses. In Debian or its derivatives, the -r parameter to dpkg should do the job, as in dpkg -r lprng.

Once your system is shed of any printing system, the best way to install CUPS is to use a package for your distribution. These packages include SysV startup scripts designed for your distribution, as well as sample configuration files and perhaps patches. As with uninstalling programs, using your package system is usually the best approach. Some tools, such as Debian's apt-get and Gentoo's emerge, work over the network; for instance, typing emerge cups on a Gentoo system downloads and installs CUPS. Other tools, such as rpm on an RPM-based system or Debian's dpkg, require that you have a package file available locally. Frequently, these files are available on your installation CD-ROMs.

If you're using an older distribution, or one of the rare modern ones that doesn't yet provide CUPS as at least an option, you can obtain the CUPS source code from its web page. You must then compile and install the software locally. Consult the CUPS documentation if you need help doing this.

Linux printing, like the Unix printing systems before it, typically works on a PostScript model: printers are assumed to be PostScript printers, and programs that print generate PostScript files. (Some programs with simpler printing needs generate plain-text printing output, though.) Most printers sold today aren't PostScript models, though. For this reason, CUPS, like other printing tools, relies on Ghostscript ( and related tools to convert PostScript into formats suitable for whatever printer you actually use. Frequently, installing CUPS automatically installs Ghostscript and perhaps a set of drivers and descriptions that CUPS uses to help pass data through Ghostscript. Particularly if you use a lower-level package management tool, you may need to install these tools manually before you can install CUPS; the package tool will complain about an unmet dependency if you haven't installed the appropriate prerequisites. In some cases, you may need to search for and manually install some driver files. One site that's likely to be helpful in this respect is the Linux Printing web site, Enter your printer brand and model in the selection boxes, and then click the Show button to obtain a report on the printer's compatibility with Linux. This page may include links to special drivers for some particularly new and exotic models. In most cases, downloading the PostScript Printer Description (PPD) file is worthwhile; it's often not necessary, but when it is, you can quickly add it to your system's printer list.

A basic CUPS installation knows how to handle generic PostScript printers and a few common non-PostScript models from a handful of manufacturers. If you begin following the options presented in the Section 4.2.2 and can't locate your printer model, you may need to track down and install additional drivers and/or CUPS printer descriptions. These are available from several different sources:

Your distribution
Most Linux distributions ship printer definitions in a package called cups-drivers or something similar. This package may just be a renamed version of one or more other printing packages.
The Linux Printing site provides a series of CUPS printer definitions at The information for particular printers on the Linux Printing site is likely to point you to a Foomatic driver for the printer.
GIMP Print
The GNU Image Manipulation Program (GIMP) is a popular graphics package for Linux, and it's spawned a series of Ghostscript drivers and CUPS printer definitions that can be used even without the GIMP. Check for more information on this package.
ESP Print Pro
Easy Software Products (ESP) developed CUPS and released it as open source software. ESP makes commercial printer definitions available, though; check for details.

After you install one of these packages and restart the CUPS daemon, you should be able to select your printer by make and model in the CUPS configuration tools. In a few cases, though, you'll need to select a compatible model. For instance, many mid-range laser printers use the Printer Control Language (PCL) created by Hewlett-Packard (HP). Thus, you may be able to get a printer working by selecting an appropriate HP LaserJet model even if yours is another make. Consult your printer's documentation to learn if it's compatible with a more popular model.

Adding Printers to CUPS

The simplest way to add printers to CUPS is to use the CUPS web-based administration tool. This tool runs on port 631 and is accessible by entering http://localhost:631 in a web browser running on the computer you want to configure. (You may be able to use the hostname rather than localhost, or even access a CUPS server from another computer on your network, depending on the CUPS security settings.) The result is a list of CUPS server options, such as Manage Printer Classes and Manage Jobs. Click the Manage Printers item to add, delete, or modify printer definitions. If this is the first time you've done this in your current session, you'll be asked for an administrative username and password. Type root and the root password. The result should resemble Figure 4-2, although this figure shows a system with several printers already configured, and yours may show none set up.

Figure 4-2. CUPS provides a web-based tool for managing printers

CUPS provides a web-based tool for managing printers


CUPS can be configured to refuse all web-based administration features. Configuring CUPS access controls is covered in the section Section 4.2.3, so check there if you can't get into the CUPS web-based interface.

To add a local printer using the web-based interface, follow these steps from the printer administration screen shown in Figure 4-2:

  1. Click the Add Printer button at the bottom of the printer list. (This button is below the edge of the page shown in Figure 4-2.)
  2. In the page that results, enter text for the name, location, and description of the printer. You'll use the name you enter to refer to the printer, so make it short and descriptive, such as hp4000 if your network has just one HP 4000 printer. The location and description fields provide additional information for you and your users, so you can enter anything you like for them. When you're done, click Continue.
  3. CUPS now asks for the printer device—the hardware port to which it's connected. Chances are you'll select a parallel or USB port. You can also select various network printer options, should you want to configure a Linux system to use a remote printer queue. For this description, I assume you're configuring a parallel printer; some options (particularly for network printers) deviate somewhat from this description. In particular, you must enter a network path for a network printer device, such as lpd://server/queue for an LPD printer. Click Continue when you're done.
  4. CUPS presents you with a list of printer makes. If you've installed Foomatic, GIMP Print, or some other printer description package, this list will be fairly long, and chances are your make will be available. If not, either install additional packages and restart the CUPS daemon or select a compatible make, such as HP or HEWLETT-PACKARD if you're using a PCL printer. Click Continue when you're done.
  5. CUPS presents you with a list of printer models. Select yours. Sometimes you may need to pick between two drivers for a single model. You can pick the one that's flagged as being recommended, configure two queues so you can try both, or consult a source such as the Linux Printing web site for advice. If you don't see your model, either pick a compatible one or use your browser's back button to look for an alternate spelling for your printer make. When you've selected a model, click Continue.
  6. CUPS should respond that the printer has been added. You can then click its name to bring up a control panel for the printer. Figure 4-2 shows these options for three printers.
  7. Click Print Test Page to test the printer's functionality. After a brief delay, the printer should spring into action and print a test page.

Of course, the CUPS web interface, like other Linux GUI administration tools, works by modifying text files. In the case of CUPS, most configuration files reside in /etc/cups and its subdirectories. In particular, the file printers.conf defines the actual printers. If you prefer to directly modify the configuration file yourself, you can do so by editing this file. Printer definitions begin with the string Printer or DefaultPrinter (the latter is for the default printer; there should be only one of these) followed by the printer name and enclosed in angle brackets (<>). Subsequent lines set the options entered in the web-based tool; each begins with a keyword and continues with a string of some sort. A few options, such as State, are adjusted by CUPS as it operates. An example entry looks like this:

<DefaultPrinter hp4000>
Info Hewlett-Packard HP LaserJet 4000 Series
Location Parallel printer on /dev/lp1
DeviceURI parallel:/dev/lp1
State Idle
Accepting Yes
JobSheets none none
QuotaPeriod 0
PageLimit 0
KLimit 0

As a general rule, it's easiest to create printer definitions using the CUPS web-based tool. Directly editing the printers.conf file can be tricky because you must know the syntax for all of the options, as well as option names. Directly editing the file can be a handy way to quickly make a change, though, such as changing the default printer.

Adjusting CUPS Browsing and Security

In addition to printers.conf, another CUPS configuration file is critically important: cupsd.conf . This file, which also resides in /etc/cups, controls overall server operations, including security features and browsing. In the context of CUPS, browsing refers to the automatic discovery of printers that are shared via the Internet Printing Protocol (IPP), the printing protocol used by CUPS for CUPS-to-CUPS printer sharing. One of the main advantages of CUPS over earlier Linux printing systems is that CUPS supports browsing. This fact can greatly simplify printer configuration on Linux clients: just ensure that the server and client support browsing, and the client will automatically detect remote printers and add them to its printer list. If you subsequently add a printer to a CUPS server, you won't need to touch the clients; they'll detect the new printers within a matter of minutes.

To enable browsing on a CUPS server, open cupsd.conf in a text editor, and look for the Browsing line, which will probably be about half-way through the file:

Browsing On

The default value for this option is On, meaning that browsing is enabled. Some distributions set this parameter to Off, though, presumably as a security precaution. If you want a server to announce its printers to other computers, be sure that Browsing is set to On.


After you make a change to the CUPS configuration file and restart the CUPS daemon, it may take several seconds for clients to see the new printers.

You may also want to adjust the BrowseAddress lines, which appear shortly after the Browsing option. This parameter specifies the network addresses to which browse lists should be broadcast. On a small LAN, a value of @LOCAL should do well. This option tells CUPS to broadcast browse lists to its local network interfaces. You can also specify network blocks using broadcast IP addresses, as in to send broadcasts to the network. In fact, you can include several BrowseAddress lines to specify multiple networks:

BrowseAddress @LOCAL

On the client side, the BrowseAllow and BrowseDeny options specify addresses from which browse packets should or should not be accepted. You can set these options as DNS hostnames, as domain names preceded by dots (as in, as IP addresses, as IP address/netmask pairs, or in various other forms. You can also use the same @LOCAL notation accepted by BrowseAddress. Typically, you'll set a CUPS client to accept browse packets from your local network, and perhaps from some others:

BrowseAllow @LOCAL

The default for BrowseAllow is All, which accepts all browse packets. This configuration is appropriate for CUPS clients on small LANs, but if you're configuring a system on a larger network, you may want to restrict the remote printers it adds by explicitly setting BrowseAllow.

Most of the options in cupsd.conf are global; they apply to the CUPS configuration as a whole. CUPS also supports more fine-grained control in sections that are delimited by Location directives. These begin with the keyword Location and a location name, surrounded by angle brackets (<>), and end with </Location>:

<Location /printers>
Order Deny,Allow
Deny From All
Allow from
Allow from
Allow from
Allow From @LOCAL

This example uses the Allow directive to tell CUPS to grant access to the specified computers and networks. This example also controls access to the /printers location, which, as you might expect, provides the means to access printers. Other locations of interest include the root (/), which sets the default security policy; /jobs, which controls the ability to adjust job priorities, delete jobs, and so on; and /admin, which controls administrative functions such as adding new printers. This last section frequently includes AuthType and AuthClass options, which tell CUPS to require authentication; after all, you don't want to let just anybody access the printer administration tools.


If you can't access the CUPS administration web page, try examining the /admin location. Be sure that an Allow line grants access to the computer used to access the server. Frequently, this is set to, for localhost access only, but you can add more lines to grant access to other computers. I recommend doing so with caution, though; granting other computers access to a CUPS server is a potential security risk.

Creating a Printer Share

Now that you've got printers working on the Samba server using CUPS or some other printing software, it's time to begin configuring a printer share in Samba itself. Printer shares are very much like file shares, so you can configure printer shares much as you would configure file shares, but with a few key differences. You'll also need to decide whether to share a non-PostScript printer as a PostScript model (using Ghostscript to convert PostScript into the printer's native format) or using native drivers on the clients (bypassing Ghostscript on the server).

File Shares Versus Printer Shares

SMB/CIFS printer shares are virtually identical to file shares from a Samba configuration perspective. The difference is what the server does with files sent to the share by clients. In the case of file shares, the files are stored in a local directory and then ignored—at least, until they're accessed by the same or another client. In the case of printer shares, though, the server stores the file and then passes that file to the local printing system. The printing system typically prints the file and then deletes it. (Samba supports specifying an arbitrary command as the printing system, though, so you can use "printer" shares to perform unusual tasks, such as creating a CD-R.)

Because SMB/CIFS printer shares are so similar to file shares, they're defined just as you would define a file share, by placing the share name in square brackets, as in [okidata] to create a printer share called OKIDATA. In order to create a printer share, though, you must set one or more additional parameters:

This share-level Boolean parameter, when set to Yes (the default is No), defines a printer share; it alone will create a printer share, although it might not work, depending on other parameters and the overall computer configuration. This parameter overrides the writeable parameter and its synonyms; all printable shares are necessarily read/write. A synonym for this parameter is print ok.
This parameter sets the printing system that Linux uses. Samba supports 11 values (BSD, AIX, LPRng, PLP, SysV, HPUX, QNX, SoftQ, CUPS, OS2, and NT), but only BSD, LPRng, and CUPS are common in Linux. (The SoftQ option was removed early in the 3.0.x series, while OS2 and NT are recent additions.) This parameter sets the defaults for several other parameters, enabling Samba to most efficiently submit print jobs to your local print queues. Until Samba 3.0.3, this parameter was global, but it's a now a share-level parameter.
print command
This share-level parameter sets the command that's used to print a file. The default depends on the printing parameter. You can tweak this option to achieve special effects, such as setting duplex printing. If you try changing this parameter, be sure that the command you specify deletes the input file (identified by the Samba %s variable).
printer name
You can specify the name of the local print queue with this parameter. If you omit it, the default is based on the share name; for instance, if the share is called OKIDATA, Samba will try to submit the job to a queue called okidata. One important exception is described shortly. This option actually sets the %p variable, which specifies the print queue in the print command.
printcap name
This parameter points Samba at a file that defines local printers. It's important only if you define a [printers] share, as described shortly. Ordinarily, this parameter points to /etc/printcap, but if you set printing = CUPS, you can also set printcap name = CUPS to have Samba use the CUPS API to obtain a printer list. This requires CUPS support in the Samba binary, which may be added or omitted as a compile-time option. If this support is missing, you may still use printing = CUPS, but Samba won't use the CUPS API, and you may need to set printcap name = /etc/printcap.
load printers
This global Boolean parameter tells Samba whether to load the printers specified in printcap name for browsing. This parameter defaults to Yes, and if you intend to use a [printers] share, you shouldn't change it.
min print space
To minimize the risk of problems due to insufficient disk space, you can specify a minimum that must be present before Samba will accept a print job. This parameter takes disk space in kilobytes; if less space is free in the target directory, Samba will refuse the print job. The default value is 0, which disables this check.

Several other options are available to tweak features, such as the commands used to delete print jobs, pause the print queue, and so on. Consult the smb.conf manpage for details. In addition, some common file share parameters are important. Most notable of these is directory or its synonym, path. These parameters tell Samba where to store the print job before it's submitted to the print queue. The default value of /tmp usually works, but you may want to change this to a Samba-specific directory, such as /var/spool/samba. You should not try pointing Samba to your CUPS, LPRng, or other local printing system's queue! If you create a new Samba printer queue directory, be sure it's readable to all users who are authorized to use the printer. You may also want to set the sticky bit on the directory, which will prevent users other than the files' owners from deleting a file:

# mkdir /var/spool/samba
# chmod 777 /var/spool/samba
# chmod o+t /var/spool/samba

One unusual printer share is defined as [printers]. If this share is present, Samba creates individual shares for all of the shares in /etc/printcap (or another file specified by printcap name). Using a [printers] share can greatly simplify printer configuration, particularly on a server with many printers you want to share. This share is described in more detail in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#The [printers] Share|Section 4.5.4]].

Sharing PostScript Printers

In Linux's native printing system, most programs treat printers as PostScript models. Part of the job of CUPS (or any other Linux printing queue) is to pass PostScript files through Ghostscript to convert them into formats that the printer can actually understand. (Of course, if the printer is a PostScript model, this conversion process isn't necessary when programs generate PostScript output.) From a purely Linux point of view, Samba is just another program; the fact that the files Samba prints originate from another computer is unimportant.

The result of this arrangement is that sharing a printer as a PostScript printer is usually fairly straightforward. If you can print from the Samba server computer itself using commands like lpr or the CUPS test page printout, you can share a printer with a fairly basic smb.conf entry:

   directory = /var/spool/samba
   printable = Yes

This entry makes a printer share called EPSON available to clients. On the clients, you must use a PostScript driver to print to the printer, whether or not the printer is really a PostScript model; to the client, it looks like a PostScript printer. (Windows printer drivers are described in more detail in Section 4.4.)


Some Windows PostScript drivers generate output that can confuse a normal Linux queue into thinking the file is not, in fact, PostScript. If your Windows printouts to genuine PostScript printers consist of PostScript code rather than the documents you intended, one workaround is to use a raw queue like the one described in the Section 4.3.3, on the Samba server.

Sharing printers as PostScript models means that print jobs are sent over the network as PostScript. In the case of text documents, this is generally fairly efficient because the content is mostly text, rather than text converted to bitmaps. Using PostScript can also simplify driver installation and maintenance on a network with many printers; you may be able to use just one driver for several different printers. On the other hand, if the printer isn't really a PostScript model, the Samba server computer will need to convert the text into some other form (usually a printer-specific bitmap), which can consume a fair amount of CPU time on the server.

Sharing Non-PostScript Printers

When sharing a non-PostScript printer, another option is available: you can share the printer using a "raw" Linux printer queue. This queue uses the local Linux printing system, such as CUPS, but it bypasses Ghostscript. The result is that programs, such as Samba and its clients, must produce files the printer can parse. Typically, you do this by installing and using a printer's native drivers, as supplied by the manufacturer, on the Windows clients.

The Samba printer share configuration for a non-PostScript printer is likely to look much like the configuration for a PostScript printer. The main difference on the Samba server side is in the Linux printer queue configuration. In the case of CUPS, when you provide CUPS with the printer's make (in Step #4 of the procedure in the Section 4.2.2), you select Raw, followed by Raw Queue as the model. Alternatively, in Samba 3.0.3 and later, you can use the Samba cups options = raw parameter if you set printing = CUPS. This option tells CUPS to handle the input as if it were to a raw queue. If you're using LPRng or BSD LPD, omit the if line in /etc/printcap to create a raw queue.

When sharing printers in this way, the client generates printer-specific codes. For many low-end printers, this means that the clients generate bitmaps, even when printing text. These bitmaps are likely to be larger than PostScript files describing the same page, so raw printer queues may increase the network bandwidth requirements of printing. On the other hand, because Ghostscript isn't involved on the print server, the CPU requirements on the server are likely to be reduced. Non-PostScript Windows printer drivers are also likely to provide access to printer features that aren't easily adjusted through PostScript drivers, such as a printer's resolution.

When deciding between PostScript and raw queues, your best bet is to set up both types of queue and evaluate performance yourself. Try printing some documents in both ways and judge the output quality, print speed, and network load. You can then decide which method to use when you make the printers available to all your users. In some cases, you may want to make a printer accessible in both ways. This will enable your users to pick the optimum driver—say, to use a PostScript driver when printing text but to use a printer-specific driver when printing graphics.

Delivering Printer Drivers to Windows Clients

One critically important part of Samba printer configuration is distributing drivers to Windows clients. This task can be accomplished in several different ways. One approach that requires little explanation is to use the driver CD-ROM that came with the printer (or a generic PostScript driver for Ghostscript-driven printers) to install the driver on all the clients. This approach is simple enough on a small network, but it becomes awkward when many clients are involved. For these cases, SMB/CIFS provides mechanisms to help deliver drivers to many clients, and Samba supports these mechanisms.


If you fail to configure Linux to deliver a Windows printer driver, Windows NT/200x/XP clients may display spurious "unable to connect" error messages. To avoid this problem, set use client driver = Yes. However, you should not use this option if you configure Linux to deliver printer drivers to Windows NT/200x/XP clients.

You can take a middle ground. Instead of using the semiautomated driver installation mechanisms described here, you can create an ordinary file share that holds the printer drivers. You can then install the drivers from that share on all the clients. This procedure obviates the need to carry a CD-ROM around from one computer to another, or to keep track of the CD-ROM for the benefit of computers you add after setting up the printer.

Picking a Driver

The first task you must undertake in driver installation is to select the drivers you want to install. To a large extent, this decision depends on whether you share the printer using a PostScript queue or a raw queue. (This difference is moot, of course, in the case of PostScript printers.) In many cases, though, you can choose between drivers from more than one source:

OS drivers
Windows (and most other operating systems) ship with an array of printer drivers. You may be able to select a driver from among those that ship with the OS. This is true for both PostScript and non-PostScript drivers.
Printer manufacturer drivers
Printer manufacturers invariably ship Windows drivers with their printers. For older printers, you may need to check the manufacturer's web site to obtain drivers that can work with more recent versions of Windows.
Adobe's PostScript drivers
Adobe makes drivers for PostScript printers available from its downloads page ( These drivers are generic PostScript drivers that require PPD files to operate. (Adobe makes these available for printers with Adobe interpreters, as well.) They're also licensed only for printers that use PostScript interpreters written by Adobe.
The CUPS PostScript driver
A Windows PostScript driver is associated with the CUPS project. Because you can install this driver from the Samba server computer without the help of a Windows system, it's particularly simple to install, as described in Section The CUPS driver works only on Windows NT/200x/XP systems, however; if you need to deliver drivers to Windows 9x/Me systems, you'll need another driver source, at least for those clients.

Because of the array of printers available today, I can't make a blanket recommendation for what driver to use; any of the preceding classes of drivers might work well. In fact, chances are any of them will work well with most printers, with the exception of PostScript drivers if you already know you want to share a non-PostScript printer raw.

Defining Necessary Shares

Samba 2.2 and later use a special file share to deliver printer drivers. This share is defined as [print$]. Ultimately, printer driver files will reside in this share, but for the moment you must simply create it. A typical [print$] share looks like this:

   comment = Printer Driver Storage
   directory = /usr/share/samba/drivers
   browseable = No
   read only = Yes
   write list = gutenberg

The location of the shared directory is somewhat arbitrary, but the key point is that it must exist. This directory must also be readable to all those who might want to add printers to their machines. You'll typically give one or more users write access to the share (gutenberg in this example). These users are the printer administrators; they're authorized to add printer drivers to the share. Be sure that the printer administrators have Linux write privileges to the location you've chosen as the PRINT$ share directory. You should also list these users on the printer admin line in the [global] section of smb.conf:

printer admin = gutenberg

Before adding drivers, you must also define some printer shares. If you want to share all the printers on the server, a [printers] share, as described in the section [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#The [printers] Share|Section 4.5.4]], should do nicely.

   comment = All Printers
   path = /var/spool/samba
   printable = Yes

After you make these changes to smb.conf, you must either wait a minute or two for Samba to discover and implement the changes or force Samba to restart or reload its configuration file.


Samba stores printer driver files in the PRINT$ share, but it stores information about these files in Trivial Data Base (TDB) files located elsewhere—typically in /var/cache/samba and /var/cache/samba/printing. In theory, you can edit these files with the help of Samba's rpcclient command, but unless you're an expert with this tool, doing so is extremely tedious. In case of errors when installing printer drivers, you may need to delete these files and start from scratch.

Installing the Driver on the Server

Once you've reconfigured Samba with the PRINT$ share and one or more printer shares, you can install Windows printer drivers in Samba. You can perform this task from the Samba server, from another Linux or Unix system, or from a Windows client. The CUPS driver can only be installed from a Linux or Unix system, the Adobe PostScript driver can be installed in either way, and most other drivers can be most easily installed from a Windows client.

Installing drivers from Linux

CUPS ships with a program, called cupsaddsmb , which can install Windows printer drivers on a Samba server computer. This command's syntax is as follows:

cupsaddsmb [-H samba-server] [-U samba-user] [-h cups-server] [-v] 
    {-a | printer-list}

In the simplest case, you can type cupsaddsmb -a on the server system as the printer administrator. The system defaults to installing the CUPS drivers from localhost to localhost. The -a parameter tells the program to add drivers for all available CUPS printers. If you don't share all these printers, you must specify them individually. The -v parameter increases the verbosity of the program's output, which can be handy for debugging problems.

Of course, cupsaddsmb can't conjure printer drivers out of thin air; you must place them somewhere the program can find them before executing the program. By default, cupsaddsmb looks for drivers in /usr/share/cups/drivers. These drivers can come from one of two sources:

The CUPS PostScript drivers for Windows
These drivers can be found at The CUPS documentation recommends using them. As of CUPS 1.1.20, though, these drivers support only Windows NT/200x/XP.
The Adobe PostScript drivers for Windows
You can find Adobe's drivers at These drivers support Windows 9x/Me as well as NT/200x/XP.

In either case, you must install driver files in /usr/share/cups/drivers, but how you place them there depends on the driver. In the case of the CUPS drivers, you download a tarball from the CUPS web site, extract the tarball, and run the cups-samba.install script from the tarball. This script asks for confirmation and installs the files in /usr/share/cups/drivers. You can then run cupsaddsmb to install the drivers on the Samba server.

The Adobe drivers, on the other hand, were designed to be installed from a Windows system to a Windows system. They come in the form of a Windows executable (.EXE) file. This file is a self-extracting Microsoft Cabinet archive, which can be extracted in Linux using the cabextract program. (Check your distribution for this program, or visit to download the source code or a binary package.) When you extract the drivers file, you must copy several files into /usr/share/cups/drivers, as detailed in Table 4-1. Note that cupsaddsmb expects these files to appear in all-uppercase, but some of them are in lowercase or mixed case in the archive; you need to rename some of the files to change their case. Also, these files are scattered about in the Windows and WinNT subdirectories. In my experience, this option works well for Windows NT/200x/XP, but Windows 9x/Me tends to complain about a missing .INF file when installing the drivers installed in this way. If you run into this problem, you may need to install Windows 9x/Me drivers another way.

Table 4-1. Adobe PostScript driver files

Windows 9x/Me Windows NT/200x/XP

Once you've installed the CUPS or Adobe driver files, you can type cupsaddsmb -a or whatever variant you need to type, given your printer administration username and other variables. The program should ask for your password on the Samba server, copy the driver files, and configure the server to deliver the files to clients when they connect, as described in Section 4.4.4.

Unfortunately, cupsaddsmb is rather delicate and sometimes doesn't work correctly. Likely problems include missing driver files, an attempt to install drivers without appropriate privileges on the server, and a mismatch of CUPS and Samba printer names (cupsaddsmb assumes that these names match). If you have problems, check these items. You may also want to add the -v parameter and check your Samba log files for clues to the cause of the problem.


Whenever possible, cupsaddsmb copies the PPD files used by CUPS as part of the driver installation. Both the CUPS and Adobe PostScript drivers for Windows use PPD files. It's possible, though, that the PPD file used by CUPS for Linux clients will not work well from Windows. If you suspect this is the problem, try replacing the PPD file on the Samba server and then re-install the driver on the clients. Look for a PPD file with your Windows PostScript driver package and copy it to the name and location in which Samba looks for the PPD file for that driver.

Installing drivers from Windows NT/200x/XP

In theory, any Windows driver can be installed from Linux. The cupsaddsmb command merely copies files to the server and issues a few commands using the smbclient utility. You should be able to do the same for any printer driver files. In practice, though, the task is tedious without the help of cupsaddsmb, and it only supports the CUPS and Adobe PostScript drivers. For this reason, you may want to install some drivers from Windows clients. (This task can be accomplished only from Windows NT/200x/XP clients; Windows 9x/Me doesn't support this operation.) Doing so employs the same facilities on the Samba server cupsaddsmb uses, but the Windows driver-installation tools use these features.


Some drivers, particularly for older printers, come with installation programs that assume the printer will be connected locally or that don't support network installations. These drivers can be very difficult to install on a network print server. If you have such drivers and can't find more network-friendly updates, you may want to consider creating an ordinary Samba file share in which you can place the installer. You can then run the installer from each client that needs to use the printer.

When installing drivers from Windows, you must take one extra step on the Samba server computer. Windows printer drivers are installed in fixed directories on the Samba server's PRINT$ share. You must create these directories and set their permissions so that the user adding the drivers can write to them. Table 4-2 summarizes the directories you must add.

Table 4-2. Windows driver directories in PRINT$ share

Client OS Directory name
Windows 9x/Me win40
Windows NT/200x/XP for x86 CPUs w32x86
Windows NT for Alpha CPUs x32alpha
Windows NT for MIPS CPUs w32mips
Windows NT for PowerPC CPUs w32ppc

Before proceeding, you should obtain the driver installation files. If you choose to use a driver that ships with Windows, you need only the Windows installation CD-ROM. Alternatively, you can download drivers from the printer manufacturer, from Adobe, or conceivably from some other source. Once you've obtained the drivers, follow these steps on the Windows computer to install drivers for the OS you're running:

  1. In My Network Places, browse to the Samba server on which the share you want to install is located, and open the Printers and Faxes or Printers folder.
  2. Right-click the printer you want to install and select Properties from the resulting pop-up menu. If no driver is installed, Windows asks if you want to install one.
  3. Click No in response to the question about installing a driver. Clicking Yes will install a driver locally, not to the print server. Windows now displays a Properties dialog box.
  4. Select the Advanced tab in the Properties dialog box.
  5. Click the New Driver button in the Advanced tab of the Properties dialog box. Windows launches an Add Printer wizard to help guide you through the driver installation process.
  6. Click Next in the Add Printer wizard's introductory screen. The result is a dialog box in which you can select the make and model of your printer from a list of standard Windows drivers, as shown in Figure 4-3.

    Figure 4-3. Windows ships with a large number of printer drivers

    Windows ships with a large number of printer drivers

  7. Select the driver for your printer from the list and click Next. Alternatively, click Have Disk to point the wizard at driver files you've obtained from another source.


    If you can't find your printer in the list and don't have a disk, try using the Apple LaserWriter IINT driver for monochrome PostScript printers or the QMS magicolor driver for color PostScript printers. These drivers are fairly generic and usually produce acceptable results.

  8. The Wizard informs you that you're about to add drivers. Click Finish to do so.

This procedure adds drivers for the OS that the client you used to install them is running. If you want to add drivers for additional operating systems, follow these steps.

  1. Open the Properties dialog box for the printer in question, if necessary.
  2. Click the Sharing tab in the Properties dialogue box.
  3. Click the Additional Drivers button in the Sharing tab. This action brings up an Additional Drivers dialog box, as shown in Figure 4-4.

    Figure 4-4. You can install drivers for additional Windows OSs

    You can install drivers for additional Windows OSs

  4. Check the box next to the Windows version for which you want to install drivers.
  5. Click OK. Windows will ask for the location of the drivers.
  6. Enter the path to the driver files or browse to them. The system will present a list of printers similar to that shown in Figure 4-3.
  7. Select the printer and click OK. Windows should install the drivers.

Installing Drivers on Clients

Windows printer drivers, by their very nature, are Windows programs and so must be installed on Windows print clients. Installing them on a Samba server merely makes the drivers available for semiautomatic installation on Windows clients, thus obviating the need to keep track of driver installation CD-ROMs or files. Despite the fact that installing the drivers on the Samba server simplifies client driver installation, this task isn't wholly automatic, at least not when using SMB/CIFS printing. To install a driver on a Windows client, follow these steps:

  1. Browse to the print server that hosts the printer you want to add to the computer. You should see an icon for the printer you want to add. If you don't, chances are the server is misconfigured.
  2. Double-click the icon corresponding to the printer you want to add. The result is a notice that you're about to connect to a printer and add a driver for it.
  3. Click Yes to continue the setup process. In some versions of Windows (most notably Windows 9x/Me), you'll be asked some additional questions, such as whether you intend to print to this printer from DOS programs.

If all goes well, you'll see a dialog box summarizing the progress as the client transfers files from the server. An icon for the printer should then appear in your Printers or Printers and Faxes window, which you can open from the Control Panel. Windows 9x/Me asks if you want to print a test page during the install process. You should probably do so to test the printer's operation, particularly on the first client you install. If you skip this step during installation but want to do so afterwards, right-click the printer icon in the Printers or Printers and Faxes window and select Properties from the resulting menu. This action opens a Properties dialog box. Click Print Test Page from the General tab in this dialog box to print a test page.


Under Windows NT/200x/XP, one reason you may not be able to print is because the printer data in the Registry didn't get set correctly. You can set this data by setting the default page orientation in the printer control dialog box.

Some Windows PostScript printer drivers generate PostScript that can confuse Linux printer queues into thinking the file is plain text. The result is a printout of PostScript commands, rather than the file you'd intended to print. If this happens, you can try several solutions.

  • Look for client-side options to disable a Ctrl-D before the print job. This character, if present, can be the cause of problems.
  • Look for client-side options to disable printer mode-setting features. Some printer drivers generate special code to kick dual-language printers into PostScript mode, but this code can have the effect of confusing the Linux printer queue.
  • Define a new raw printer queue on the Samba server and share the printer using that queue rather than the normal queue used from Linux.
  • Change the driver used on the Windows client. If you've installed it in Samba, this action requires reinstalling the driver in Samba, which itself may require deleting TDB files.

Example Shares

Knowing what the parameters are that control Samba share definitions and knowing how to use those parameters are two different things. Failing to see the forest for the trees, as it were, is easy to do when confronted with a list of Samba parameters. For this reason, this chapter concludes with a look at several common uses of Samba file and printer shares: the [homes] share, which provides users with data storage space for their own files; a share that can store program files, templates, and other shared read-only files; shares for exchanging files between users; a closer look at the [printers] share introduced earlier; and a "printer" share that generates PDF files rather than paper printouts.

The [homes] Share

Many Samba server computers function, in whole or in part, as centralized storage locations for users' files. Users store their important files on the Samba server, enabling them to store more or larger files than would fit on their clients' disks and to move from one client to another and access their own home files. This strategy can also greatly simplify backup; if users' data files are on a single server, that server can be backed up more easily than can an entire network's worth of files, thus providing more reliable insurance in case of hardware failure.

The user data storage function is so important that Samba provides a special share name just for this purpose: [homes]. This share functions much like an ordinary file share but with several important differences:

  • The share can be accessed via the user's username, as in LINNAEUS for the user linnaeus. The share can also be accessed by the name HOMES, but this name is usually considered secondary.
  • In a Windows-dominated network, the username-based share name is typically what appears in network browsers. The HOMES name might not appear in browsers; this detail depends on configuration options, as described shortly.
  • The default path for the share is the user's home directory, as specified in /etc/passwd or other account-definition files.

A typical [homes] share definition can be quite short:

   comment = Home Directories
   writeable = Yes
   create mask = 644
   browseable = No

The Samba default is to make shares read-only, but because the intended [homes] shares enable users to store files that they create, changing this default is particularly important for these shares. The create mask = 644 parameter isn't necessary, and, in fact, it's undesirable if you want to preserve the archive bit on files. Using this parameter keeps the owner execute bit from being set, though, which may be desirable if users make heavy use of shell access or access via NFS or some other means that preserves this bit as such.

Ordinarily, shares on which you set browseable = No aren't visible in file browsers, but [homes] shares are exceptions to this rule. Specifically, the browseable parameter applies to the share called HOMES; if you omit the browseable = No parameter or set it to Yes, a share called HOMES appears in clients' network browsers. Part of the definition of the [homes] share is that a share named after the user who accesses the server appears in the user's browse lists. (Only the home share for the user who accesses the server is displayed; users won't see other users' home shares, although they can be accessed by entering their names directly.)

This example share doesn't specify a directory or path; it relies on the [homes] default. Although you can set a directory for the share, setting a static directory is usually undesirable. If you want to provide users with different home directories for remote text-mode or GUI logins than for Samba access, you can specify a Samba directory that is unique for each user by including variables such as %S, %u, or %U; these variables all expand to values related to the username. (In many cases, they expand to the same value.) For instance, you might set the path like this:

path = /home/samba/%u


Some clients, such as the BeOS network browser, don't deliver a username until after they've retrieved lists of shares. For these network browsers, a [homes] share will be invisible unless you set browseable = Yes. Such clients might also not work well if you use a %S (share name) variable in a [homes] share's path or directory parameter.

Many sample smb.conf files include [homes] shares, so this share may already exist on your server. Of course, if you don't need it, you can delete it or change the definition to suit your particular needs.

A Windows Program Share

Samba servers can also be used as central repositories for files that many clients must access in a read-only manner—program executables, templates, clip art, fonts, and so on. Most users have no need to write to such shares, so most users receive read-only access. Somebody must maintain these shares, though, so a write list parameter provides an exception to the rule:

   comment = Program Files for All Users
   path = /usr/share/samba/windows-programs
   write list = linnaeus, mendel
   force user = linnaeus
   force group = users
   read only = Yes
   create mask = 660
   directory mask = 770

In addition to the write list, this example share includes force user and force group parameters. These parameters force all files to be owned by a single user and group; even those files written by mendel will be owned by linnaeus, which makes for a cleaner on-server set of ownerships; however, this also means you can't track whoever installed a particular file. These parameters also guarantee that all users will be able to read the files in the share, at least assuming that no files are written to the share through non-Samba means. Note that the force user parameter in conjunction with write list does not give all users write access to the share; write list applies to users' true logon usernames, not their identities as determined by force user.

If you create a share like this, be sure to set appropriate permissions on the share's directory (/usr/share/samba/windows-programs in this example). If you don't give linnaeus write access to the directory, neither linnaeus nor mendel can store files in the share. You may also want to consider local Samba server security issues. For instance, if the share contains files that shouldn't be accessible to some non-Samba users of the server, you should set create mask and directory mask parameters that deny world access (as in the example) and ensure that these users aren't in the group specified by force group.

File-Exchange Shares

A read-only share such as the [programs] share is relatively straightforward to configure. A share that's used for data exchange between users is much more complex because you must decide how to set ownership and permissions that enable those who should be able to write to files to do so, while preventing those who shouldn't. Several approaches to solving this problem exist:

Shared access to [homes] directories
You can set permissions on users' home directories such that they can read each others' files. If necessary, you can create local Linux groups and enable read access to group members while denying world access, thus providing support for groups of users. One drawback to this approach is that users will have to type in their collaborators' usernames when accessing shares; they won't be able to browse directly to those directories. (Creating symbolic links between users' home directories from Linux may provide a partial fix to this problem.)
Multiple file exchange shares
You can create several shares for file exchange, giving different groups access to different shares. You can use valid users or invalid users to control access. Using Linux groups and permissions on files in shares also works to this end. Depending on your needs, using multiple sharing directories can be awkward because it clutters your list of shares if you need to create shares for many different groups
One big happy file exchange share
You can create a single share with lenient permissions—say, setting create mask=666 and directory mask=777 or using force user to set ownership of all files to a single user. The effect is that all users can read and write all files in the share. This can be a good approach on servers on which you don't need to worry too much about keeping files from particular groups of local users. Even if that's the case, judicious use of such a share may be acceptable, but users will have to be warned against placing sensitive files on the data-exchange share.
One big exchange share with internal security
If you use the inherit permissions = Yes parameter, you can use a single file-exchange share but maintain internal security by setting up subdirectories with different ownership and modes. For instance, one subdirectory might have 777 (rwxrwxrwx) permissions, enabling anybody to read and write it, whereas another subdirectory might have 770 (rwxrwx---) permissions, enabling members of its group to use it to exchange files while keeping it off-limits to other users. This approach is very flexible, but you need to give some thought to the local Linux permissions on the subdirectories. You also need to create these subdirectories from Linux. Users are likely to find this scheme confusing, but giving the subdirectories descriptive names, such as dna-analysis-group or instructors-only, should help on that score.

Precisely how you would configure such a share depends on which approach you take and on your Linux server's local security configuration. For one example, consider this file share:

   comment = Share for Use by Sane Scientists Only
   path = /usr/share/samba/sane
   valid users = @sane, linnaeus, mendel, curie
   writeable = Yes
   force group = sane
   create mask = 660
   directory mask = 770

   comment = Share for Use by Mad Scientists Only
   path = /usr/share/samba/mad
   valid users = @mad, morbius, moreau, frankenstein
   writeable = Yes
   force group = mad
   create mask = 660
   directory mask = 770

These two shares, in combination, provide separate file-exchange areas for two groups of users. The first grants access to all members of the Linux sane group, plus three others who might or might not be members of that group. The second share does the same for the mad group and three other users. You can include a user in both groups if you like, in which case that user has access to both shares. For instance, you can place the user jekyl in both the sane and mad groups, or add the user explicitly to one or both shares' valid users lines. If you want to give one group read-only access to another group's shares, add the members of both groups to the share's valid users line but use read list to restrict some users' access to the share.

Another way to implement a similar system is to create a single share:

   comment = Share for Use by All Scientists
   path = /usr/share/samba/scientists
   valid users = @sane, @mad
   writeable = Yes
   inherit permissions = Yes

You then create subdirectories within the share's directory with appropriate permissions set to enable only members of particular groups to access the directories. The result might look like this, as viewed using Linux's ls:

# ls -l /usr/share/samba/scientists
total 8
drwxrwx---  2 root mad  4096 May  2 14:47 mad
drwxrwx---  2 root sane 4096 May  2 14:47 sane

The result is that members of the mad group can exchange files in the mad subdirectory, and members of the sane group can exchange files in the sane subdirectory. As configured, members of each group can't view the contents of or read files from the other group's subdirectory unless the individual is a member of both Linux groups. By changing permissions on the directories to 775 (rwxrwxr-x) rather than 770 (rwxrwx---), you can enable members of the groups to read but not write files in each others' directories. Because of the reliance on the local Linux groups, this scheme doesn't work well if some users aren't members of the underlying groups; this is the reason the individual users (linnaeus, morbius, and so on) were omitted from the valid users line in the share definition. You should also attend to ownership and permissions on the share directory itself; depending on its settings, users could create new subdirectories, which can complicate your security settings.


Both examples omit the nt acl support parameter, which defaults to Yes. As a result, Windows NT/200x/XP users can set ACLs on their files, which will complicate access permissions. Of course, these ACLs won't help users read files if the users can't read the shares or directories in which they're stored, but if users can read the directories, ACLs can broaden or restrict access to specific files, particularly if the underlying filesystem supports ACLs.

These are just two examples of common-access file shares. Many variants and alternatives are possible, that use Samba's security features, Linux's security features, or an interaction of the two. As a general rule, it's best to start with a simple security system; trying to use too many sophisticated features can lead you into trouble if you forget an important consequence or interaction.

The [printers] Share

Most print servers use a single [printers] share to make all printers available. This share can consist of just a few lines, but it relies on a few global settings, and some of its implications deserve elaboration. First, before defining a [printers] share, be sure to set the following parameters in the [global] section of smb.conf:

printing = CUPS
printcap name = CUPS
load printers = Yes
printer admin = gutenberg
guest ok = Yes

In this example, the printing and printcap name parameters are both set to CUPS, which tells Samba to use CUPS for printing, including using CUPS' own API for determining what printers are available. Of course, if you use another printing system, you'll change these parameters appropriately—say, to printing = LPRng and printcap name = /etc/printcap.


Samba provides CUPS support as a compile-time option. If Samba wasn't compiled on a system with appropriate CUPS development libraries installed, or if CUPS support was explicitly disabled, Samba won't include the necessary tools to use the CUPS API. In this case, you can still use printing = CUPS (Samba will use old-style printing commands rather than the CUPS API to submit print jobs). You may need to set printcap name = /etc/printcap, though. If Samba doesn't find your printers, try making this change. In fact, CUPS provides compatibility commands, so it should work even if you set printing = LPRng, printing = BSD, or certain other values.

The load printers = Yes parameter tells Samba to read information on available local printers from the file pointed to by printcap name (or, if printcap name = CUPS, to read the data using the CUPS API). By itself, this doesn't do anything; only if you provide an explicit [printers] share does this parameter have any effect.

The printer admin line is optional; it sets the Linux username of a printer administrator—a user whose accesses to printer shares are done as if by root. This user should be able to delete others' print jobs and otherwise perform maintenance on the queues.

The guest ok = Yes parameter tells Samba to accept guest access to the printer shares. This can be handy if you don't want to maintain a user database on a dedicated print server, but you'll need to adjust the global map to guest and guest account parameters. Enabling guest access also opens the system to potential abuses, particularly if the server is accessible to the Internet at large. (Imagine coming in one morning to discover that a high-speed, high-capacity printer has printed its entire load of paper with completely black pages, wasting both paper and toner or ink.)

Once you've set the global options, you can create a [printers] share. This share is likely to be fairly uninteresting on the surface:

   comment = All Printers
   path = /var/spool/samba
   printable = Yes

Once this share is defined, and Samba either detects the changes (which it should do after a few minutes) or is restarted, you should see printer shares corresponding to all of your local printers that appear in clients' network browsers. The shares won't be usable, though; you must first install printer drivers on the clients, as described in Section 4.4.

Using a [printers] share doesn't mean that you're restricted from creating other printer shares. You can do so in either of two ways:

  • You can create a separate printer share using a name that doesn't correspond to a print queue on the underlying Linux computer. This share will be presented to users in addition to the shares created by the [printers] share.
  • You can create a printer share that uses the same name as one of the printer queues on the underlying Linux computer. This share will override the share of the same name created by the [printers] share.

The shares generated by [printers] may be PostScript printers, non-PostScript printers that appear to clients as PostScript printers because of the use of Ghostscript in the Linux printer queue, or non-PostScript printers with raw Linux printer queues for which native printer drivers are necessary on the clients. In fact, you can provide a mixture of share types; the [printers] share simply doesn't care.

A PDF-Generation Printer Share

Samba printer shares can be unusually flexible. This flexibility is derived, in part, from the print command parameter, which enables you to bypass the usual print processing. In fact, you can do some extremely complex and unusual things with this parameter, but in this section I describe a use that's at least related to printing: creating Portable Document Format (PDF) files.

Several tools exist to generate PDF files from various formats. One of these is almost certainly already installed on your Linux computer: Ghostscript. In addition to generating output in formats that can be printed by your printer, Ghostscript can generate several common file formats, such as Tagged Image File Format (TIFF), Portable Network Graphics (PNG), and PDF. To create a Samba share that generates a PDF file, you call Ghostscript (with appropriate parameters) as the print command:

   comment = Share to Make PDFs
   path = /var/spool/samba
   printable = Yes
   print command = gs -dNOPAUSE -dBATCH -q -sDEVICE=pdfwrite \
                   -sOutputFile=%H/%s.pdf; rm %s

When the MAKEPDF share receives a PostScript file, it passes it through Ghostscript (gs), specifying various parameters to generate PDF output without prompts and saving the output as %H/%s.pdf. Because %H is the user's home directory and %s is the print job's filename, the result is a file whose name begins with the Samba print job name and ends in .pdf. This filename is likely to be ugly, but it will at least be unique. The print command line ends with rm %s, which deletes the original print job, keeping it from cluttering the disk.

Of course, the [makepdf] share, as just presented, requires users to have access to their home directories, presumably through a [homes] share. If this isn't true of your system, you can deliver the results in some other ways. For instance, you might have Samba email the PDF files to users. If necessary, you can write a script that passes the file through Ghostscript, looks up users' email addresses in a list, and sends the file. Then call the script on the print command line, passing it whatever Samba variables you need, such as the print job filename (%s) and the username (%u or %U).

To clients, this particular share is indistinguishable from a real printer's share. Because it expects PostScript input, you should install PostScript drivers on clients—ideally a fairly generic PostScript driver. Instead of printed output, though, users will find PDF files in their home directories soon after printing documents. This share can be a good way to provide basic PDF-generation capabilities to all users in all their programs that can print. It might not be enough for all functions; some dedicated PDF-generation tools support features that aren't available through Ghostscript or Windows PostScript printer drivers.


You may want to install drivers in Samba for the share for automated delivery to clients, as described in Section 4.4. You can do so from a Windows client, as described in the Section If you create a CUPS queue with the name of the PDF-generation share and set it up using a generic PPD file, you can then install the CUPS PostScript drivers for Windows as described in Section You can then delete the bogus CUPS queue. Alternatively, you can generate the queue to print to a networked SMB/CIFS queue to begin with and point it as the Samba queue you're creating. If you do the latter, CUPS clients can create PDFs by printing to CUPS, which then submits the print job to Samba.


Samba was created as a file and print server for Linux and other Unix-like operating systems, enabling these systems to fill an important role on many LANs. Although Samba has grown over the years to take on many other SMB/CIFS duties, such as domain controller and NetBIOS name server, sharing files and printers remains at the core of Samba's functionality. Creating these shares requires that you understand the basic Samba share-creation parameters. File shares are likely to use many of these options, but printer shares are likely to use a smaller subset of these options, along with a few printer-specific options. Printer shares also require configuring a local Linux printer queue, which in the case of modern Linux distributions usually means CUPS. Actually using printer shares usually requires driver installation on clients, and Samba provides tools to help automate this process.

Personal tools