Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Tue, 11 Mar 2008 21:46:06 GMT

Initial conversion from Docbook

New page

{{Linux in a Windows World/TOC}}
[[Linux in a Windows World/Sharing Files and Printers/Basic Samba Configuration|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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Example Shares|Section 4.5]].) You can create a basic file share with just one line in ''smb.conf'', but fine-tuning it to do what you want will take more lines. Options you may want to tune include those that control write access to the share, those that adjust how Samba reports filenames to clients, and those that influence local Linux or client filesystem security features.

=== Defining a File Share ===

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

[sample]

If you include this line in ''smb.conf'' at the end of the file, or with another share definition immediately following it, Samba will create a file share called ''SAMPLE''. This share will be a read-only share corresponding to the ''/tmp'' directory on the server. Chances are these options aren't the ones you want. At a minimum, you'll almost certainly want to use the <tt>path</tt> parameter or its synonym, <tt>directory</tt>. These parameters tell Samba what directory to use as the root of the share you define. For instance, to share ''/var/samba/somedir'', you might enter a share definition like this:

[sample]
path = /var/samba/somedir

This entry creates a file share that appears in Windows network browsers as ''SAMPLE'', just like the previous definition; but this share provides read-only access to files in ''/var/samba/somedir''. Note that the share name (''SAMPLE'' in this example) and the name of the directory to be shared (''/var/samba/somedir'') are unrelated. Of course, they ''could'' be related, and doing so can help you administer your system, but doing it isn't strictly necessary. Other share-level options you might want to use include the following:

;<tt>available</tt>
: This parameter's value defaults to <tt>Yes</tt>, which makes the share available. If you want to temporarily disable a share, you can set <tt>available</tt> <tt>=</tt> <tt>No</tt>. (This won't work for the <tt>[homes]</tt> 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.
;<tt>comment</tt>
: This share-level parameter is a share's equivalent of the global <tt>server</tt> <tt>string</tt> parameter; it creates a description of the share that's visible from clients' file browsers.
;<tt>browseable</tt>
: 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 <tt>browseable</tt> <tt>=</tt> <tt>No</tt>. This parameter is also usually set to <tt>No</tt> for <tt>[homes]</tt> 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 <tt>writeable</tt>, <tt>writable</tt>, and <tt>write</tt> <tt>ok</tt> parameters are all synonyms, and when any of them is set to <tt>Yes</tt>, read/write access to the share becomes possible. The <tt>read</tt> <tt>only</tt> parameter is an antonym for these parameters; setting <tt>read only = No</tt> has the same effect as setting <tt>writeable = Yes</tt>.

In addition to the critical <tt>writeable</tt> parameter or one of its synonyms, several other parameters affect write access to the share based on other features:

;<tt>invalid users</tt>
: 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 (<tt>@</tt>) or a plus sign (<tt>+</tt>), as in <tt>@students</tt>. (The <tt>@</tt> 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.)
;<tt>read list</tt>
: 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.
;<tt>valid users</tt>
: This share-level parameter is the opposite of <tt>invalid</tt> <tt>users</tt>; 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 (<tt>@</tt>) or a plus sign (<tt>+</tt>), as in <tt>@students</tt>.
;<tt>write list</tt>
: This share-level parameter is the opposite of <tt>read</tt> <tt>list</tt>; 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 <tt>writeable</tt> <tt>=</tt> <tt>Yes</tt>, 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Setting Access Control Features|Section 4.1.4]], and practical examples of some systems are described in the [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Example Shares|Section 4.5]].

<div class="tip">
'''Tip'''

Samba provides some extremely powerful options for modifying both read and write access to its shares. As a general rule, though, it's best to keep it simple; overuse of sophisticated access control tools can create a complicated configuration that will easily break. Worse, you might inadvertently create a security hole that a user can exploit accidentally or deliberately.
</div>

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

;<tt>case sensitive</tt>
: This share-level Boolean parameter controls whether Samba treats filename access in a case-sensitive way. The default value of <tt>No</tt> 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 <tt>Yes</tt>. Windows NT/200x/XP is better at handling case-sensitive filenames, but <tt>case</tt> <tt>sensitive</tt> <tt>=</tt> <tt>No</tt> is still the preferred option for it. Some Linux and Unix clients may work better with <tt>case</tt> <tt>sensitive</tt> <tt>=</tt> <tt>Yes</tt>, but this setting usually isn't required even for these clients. Samba 3.0.6 introduced the <tt>Auto</tt> 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 <tt>cifs</tt> filesystem, among others.
;<tt>preserve case</tt>
: When set to the default value, <tt>Yes</tt>, this share-level Boolean parameter causes Samba to store new files in the same case as provided by clients. When set to <tt>No</tt>, Samba converts filenames to the case specified by <tt>default</tt> <tt>case</tt> (described shortly). Setting this option to <tt>No</tt> can be handy if you have clients that generate ugly all-uppercase filenames, and you want to access the files from other clients.
;<tt>short preserve case</tt>
: This parameter works just like <tt>preserve</tt> <tt>case</tt>, but it applies only to short (8.3) filenames.
;<tt>default case</tt>
: This share-level parameter accepts values of <tt>Upper</tt> and <tt>Lower</tt>. It defaults to <tt>Lower</tt>, but this default is meaningless unless you set either <tt>preserve</tt> <tt>case</tt> or <tt>short</tt> <tt>preserve</tt> <tt>case</tt> to <tt>No</tt>. If you do so, Samba converts newly created filenames to the specified case.
;<tt>mangled names</tt>
: When set to <tt>Yes</tt> (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.
;<tt>mangle case</tt>
: Ordinarily, Samba doesn't mangle short filenames that don't match the client's case expectations. If you set <tt>mangle</tt> <tt>case</tt> <tt>=</tt> <tt>Yes</tt>, though, Samba mangles filenames that aren't entirely in the case specified by <tt>default case</tt>. 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.
;<tt>mangled map</tt>
: This share-level option specifies pairs of filename wildcards that should be mangled in particular ways. For instance, <tt>mangled</tt> <tt>map</tt> <tt>=</tt> <tt>(*.html</tt> <tt>*.htm)</tt> 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.
;<tt>mangling method</tt>
: 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 <tt>hash</tt> and <tt>hash2</tt>. 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 <tt>hash2</tt> is also less likely to produce ''collisions'' —identical hashes derived from different original filenames.
;<tt>mangle prefix</tt>
: This global parameter sets the number of characters to be preserved from the original filename when creating a mangled filename using the <tt>hash2</tt> mangling method. The default value is <tt>1</tt>, but you can improve the intelligibility of mangled filenames by increasing this value (the maximum is <tt>6</tt>).
;<tt>unicode</tt>
: This global Boolean parameter defaults to <tt>Yes</tt>, 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.
;<tt>dos charset</tt>
: 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 <tt>CP</tt>, as in <tt>CP850</tt> (Latin 1, which works well for most North American systems) or <tt>CP866</tt> (Cyrillic). This option is new with Samba 3.0.
;<tt>unix charset</tt>
: This global parameter sets the name of the character set Linux uses for its filenames. The default value is <tt>UTF8</tt>. 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.
;<tt>client code page</tt>
: 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 <tt>dos</tt> <tt>charset</tt>. This parameter takes code page numbers without a preceding <tt>CP</tt> string, as in <tt>850</tt> or <tt>866</tt>.
;<tt>character set</tt>
: 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 <tt>ISO8859-1</tt> (Latin 1) or <tt>KOI8-R</tt> (Cyrillic). This parameter has been replaced by <tt>unix charset</tt> 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 <tt>short</tt> <tt>preserve</tt> <tt>case</tt> 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 <tt>mangle</tt> <tt>prefix</tt> can improve the intelligibility of mangled filenames on DOS clients. Linux and Unix clients can benefit from setting <tt>case</tt> <tt>sensitive</tt> <tt>=</tt> <tt>Yes</tt>, but this change isn't usually required. (For versions of Samba that support <tt>Auto</tt> 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.

<div class="tip">
'''Tip'''

You can place filename options in OS-specific configuration files and use the <tt>include</tt> parameter with the <tt>%a</tt> variable in the <tt>[global]</tt> section to load them only for appropriate client OSs. For instance, add <tt>include</tt> <tt>=</tt> <tt>smb-%a.conf</tt> to ''smb.conf'' and then create files called ''smb-WfW.conf'', ''smb-Samba.conf'', and so on, in which you store OS-specific options. [[Linux in a Windows World/Sharing Files and Printers/Basic Samba Configuration#linuxwinworld-CHP-3-TABLE-1|Table 3-1]] describes the <tt>%a</tt> variable and its possible values.
</div>

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

;<tt>force user</tt>
: 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, <tt>force</tt> <tt>user</tt> <tt>=</tt> <tt>linnaeus</tt> 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 <tt>force</tt> <tt>group</tt>, 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 <tt>username map</tt>, if you employ that parameter).
;<tt>force group</tt>
: This share-level parameter is similar to <tt>force user</tt>, but it applies to the group used for file accesses. A synonym for this parameter is <tt>group</tt>.
;<tt>guest ok</tt>
: 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 <tt>guest ok = Yes</tt> and if a guest logon occurs, Samba uses the account specified by <tt>guest account</tt> for accesses, much as if <tt>force user</tt> had been used. A synonym for this parameter is <tt>public</tt>. Note that the global <tt>map to guest</tt> parameter must also be set appropriately before this parameter will work.
;<tt>guest account</tt>
: This global option sets the account used for guest accesses, as authorized on a share-by-share basis by <tt>guest ok</tt>. The default value is a compile-time option, but it's usually set to <tt>nobody</tt>.
;<tt>map to guest</tt>
: This global parameter controls the conditions that trigger a guest logon. Samba accepts values of <tt>Never</tt> (Samba never accepts a guest logon; this is the default value), <tt>Bad User</tt> (Samba accepts a guest logon when a user specifies an invalid username), and <tt>Bad Password</tt> (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 <tt>force user</tt>.

==== 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 <tt>rwxr-x---</tt>, in which a dash (<tt>-</tt>) stands for no permission and an <tt>r</tt>, <tt>w</tt>, or <tt>x</tt> 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 <tt>rwxr-x---</tt>. 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 <tt>d</tt> 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:

;<tt>create mask</tt>
: 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 <tt>create</tt> <tt>mask</tt> <tt>=</tt> <tt>744</tt> (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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Mapping DOS-style flags|Section 4.1.4.3]]. A synonym for this parameter is <tt>create mode</tt>.
;<tt>directory mask</tt>
: This share-level parameter works just like <tt>create mask</tt>, 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 <tt>directory</tt> <tt>mask</tt> <tt>=</tt> <tt>755</tt> (the default value). A synonym for this parameter is <tt>directory mode</tt>.
;<tt>inherit permissions</tt>
: This share-level Boolean parameter defaults to <tt>No</tt>, but if you set it to <tt>Yes</tt>, it overrides <tt>create mask</tt> and <tt>directory mask</tt>. 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Example Shares|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:

;<tt>map archive</tt>
: 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 <tt>map</tt> <tt>archive</tt> <tt>=</tt> <tt>Yes</tt> (the default), Samba maps this bit to the owner execute bit.
;<tt>map hidden</tt>
: 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 <tt>map</tt> <tt>hidden</tt> <tt>= Yes</tt> (the default is <tt>No</tt>), Samba stores this bit using the world execute bit.
;<tt>map system</tt>
: 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 <tt>No</tt>, but if you set it to <tt>Yes</tt>, Samba stores this bit in the group execute bit.
;<tt>store dos attributes</tt>
: This share-level Boolean parameter defaults to <tt>No</tt>. When set to <tt>Yes</tt> and when the preceding three options are all set to <tt>No</tt>, <tt>store dos attributes</tt> 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 <tt>user_xattr</tt> 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 <tt>create mask</tt> parameter; if ''either'' <tt>create mask</tt> 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 <tt>map archive = No</tt> or by setting a <tt>create mask</tt> 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 <tt>hide dot files</tt> is set to <tt>Yes</tt>, 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 <tt>map hidden</tt> parameter are.

==== Using ACLs ====

ACLs provide a finer-grained method of access control than do Unix-style permissions. Windows NT has long supported ACLs on its New Technology File System (NTFS), and SMB/CIFS also supports ACLs. This support has only recently started to become common with Linux, though. In particular, the 2.6.x kernel series adds ACL support to most common Linux filesystems—as of the 2.6.7 kernel, ext2fs, ext3fs, JFS, and XFS all support ACLs. (With earlier kernels and most common Linux filesystems, you had to patch the kernel to add ACL support. Consult ''http://acl.bestbits.at'' for details.)

Samba has long supported the SMB/CIFS ACLs as a tool for accessing Unix-style permissions from Windows NT/200x/XP systems. If you use an ACL-enabled filesystem, this same support gives Windows users fuller access to the Linux filesystem's ACL features. This support is, however, a compile-time option. To determine whether your Samba binary includes ACL support, type <tt>'''smbd'''</tt> <tt>'''-b'''</tt> <tt>'''|'''</tt> <tt>'''grep'''</tt> <tt>'''-i'''</tt> <tt>'''HAVE.*ACL'''</tt>. The result is a list of the ACL features in the ''smbd'' binary. The following parameters control this support:

;<tt>inherit acls</tt>
: This Boolean share-level parameter is similar to <tt>inherit</tt> <tt>permissions</tt>, but it tells Samba to copy ACLs from a parent directory when creating new subdirectories. The default value is <tt>No</tt>.
;<tt>nt acl support</tt>
: This Boolean share-level parameter is the key ACL feature; setting it to <tt>Yes</tt> tells Samba to enable SMB/CIFS ACL support, mapping it to the server's Unix-style permissions and, if supported, local filesystem ACLs.
;<tt>security mask</tt>
: This share-level parameter tells Samba which Unix-style permissions should be accessible to clients. The default value (<tt>777</tt>) gives users access to all the Unix-style permission bits.
;<tt>directory security mask</tt>
: This share-level parameter works just like <tt>security mask</tt>, but it applies to directories rather than files.

<div class="tip">
'''Tip'''

Samba's ACL features require the client to know more about the underlying Linux accounts than is necessary for most other purposes. Samba can most easily provide this information in user- or domain-level security modes (set with the <tt>security</tt> parameter, as described in [[Linux in a Windows World/Sharing Files and Printers/Basic Samba Configuration|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.
</div>

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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-1|Figure 4-1]].

<div id="linuxwinworld-CHP-4-FIG-1">
'''Figure 4-1. Windows ACL access tools work on Samba shares once they've been appropriately enabled'''

[[Image:Linux in a Windows World_I_2_tt23.png|Windows ACL access tools work on Samba shares once they've been appropriately enabled]]
</div>

Precisely how you manipulate ACLs differs between Windows versions. [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-1|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; <tt>unix</tt> <tt>extensions</tt> 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 <tt>Yes</tt> 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 <tt>unix extensions</tt> 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 <tt>cifs</tt> filesystem type code for Linux's ''mount'' command. [[Linux in a Windows World/Sharing Files and Printers/Linux as an SMB/CIFS Client|Chapter 6]] describes how to use the Unix extensions from a Linux client computer.

<div class="tip">
'''Tip'''

Linux client-side Unix extensions support is still rather limited. Enabling it on the Samba server shouldn't do any harm, but for Linux-to-Linux (or Linux-to-Unix) file sharing, NFS still offers better support for Unix-style filesystem features than does Samba. This may change in the future as the Unix extensions support matures, both in Samba and in the Linux kernel.
</div>

== 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; ''http://www.cups.org'') 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Creating a Printer Share|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 <tt>-e</tt> parameter to ''rpm'' can uninstall the software: <tt>'''rpm'''</tt> <tt>'''-e'''</tt> <tt>'''lprng'''</tt> uninstalls the ''lprng'' package, if that's what your system uses. In Debian or its derivatives, the <tt>-r</tt> parameter to ''dpkg'' should do the job, as in <tt>'''dpkg'''</tt> <tt>'''-r lprng'''</tt>.

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 <tt>'''emerge'''</tt> <tt>'''cups'''</tt> 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 (''http://www.cs.wisc.edu/~ghost/'') 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, ''http://www.linuxprinting.org/printer_list.cgi''. 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Adding Printers to CUPS|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.
;Foomatic
: The Linux Printing site provides a series of CUPS printer definitions at ''http://www.linuxprinting.org/foomatic.html''. 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 ''http://gimp-print.sourceforge.net'' 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 ''http://www.easysw.com/printpro/'' 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.

<div class="sidebar">
'''Printer Definition Files'''

In the case of PostScript printers, you should be able to use a generic PostScript configuration. Pointing CUPS to a definition for your specific model can improve the ability of some Linux programs to use printer-specific features, such as duplexing or wide carriages. The printer definitions just described include appropriate files for many models. If you can find a PPD file (their filenames end in ppd or PPD) on a CD-ROM that shipped with the printer or on the printer manufacturer's web site, though, you can use it. CUPS PPD files reside in subdirectories of the ''/usr/share/ppd'' directory, so place the file in an appropriate subdirectory or create a new one. (Subdirectories are named for printer manufacturers.) The files should show up when you try to add a printer, as described shortly.

Non-PostScript printers require PPD files with a few extra features, such as a <tt>*cupsFilter</tt> line to specify the Ghostscript driver to be used. Thus, this approach is unlikely to work for non-PostScript printers, unless you can find a PPD file designed to use with CUPS and Ghostscript; that's what the printer description packages, such as Foomatic and GIMP Print, are designed to do. Some, but not all, ways of delivering drivers to Samba clients rely on the PPD files you install in CUPS, as described in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Delivering Printer Drivers to Windows Clients|Section 4.4]].
</div>

=== 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 <tt>'''root'''</tt> and the ''root'' password. The result should resemble [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-2|Figure 4-2]], although this figure shows a system with several printers already configured, and yours may show none set up.

<div id="linuxwinworld-CHP-4-FIG-2">
'''Figure 4-2. CUPS provides a web-based tool for managing printers'''

[[Image:Linux in a Windows World_I_2_tt24.png|CUPS provides a web-based tool for managing printers]]
</div>

<div class="tip">
'''Tip'''

CUPS can be configured to refuse all web-based administration features. Configuring CUPS access controls is covered in the section [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Adjusting CUPS Browsing and Security|Section 4.2.3]], so check there if you can't get into the CUPS web-based interface.
</div>

To add a local printer using the web-based interface, follow these steps from the printer administration screen shown in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-2|Figure 4-2]]:

# Click the Add Printer button at the bottom of the printer list. (This button is below the edge of the page shown in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-2|Figure 4-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.
# 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.
# 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.
# 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.
# CUPS should respond that the printer has been added. You can then click its name to bring up a control panel for the printer. [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-2|Figure 4-2]] shows these options for three printers.
# 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 <tt>Printer</tt> or <tt>DefaultPrinter</tt> (the latter is for the default printer; there should be only one of these) followed by the printer name and enclosed in angle brackets (<tt><></tt>). 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 <tt>State</tt>, 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
</Printer>

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 <tt>Browsing</tt> line, which will probably be about half-way through the file:

Browsing On

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

<div class="tip">
'''Tip'''

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

You may also want to adjust the <tt>BrowseAddress</tt> lines, which appear shortly after the <tt>Browsing</tt> option. This parameter specifies the network addresses to which browse lists should be broadcast. On a small LAN, a value of <tt>@LOCAL</tt> 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 192.168.17.255 to send broadcasts to the 192.168.17.0/24 network. In fact, you can include several <tt>BrowseAddress</tt> lines to specify multiple networks:

BrowseAddress @LOCAL
BrowseAddress 192.168.17.255

On the client side, the <tt>BrowseAllow</tt> and <tt>BrowseDeny</tt> 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 ''.example.com''), as IP addresses, as IP address/netmask pairs, or in various other forms. You can also use the same <tt>@LOCAL</tt> notation accepted by <tt>BrowseAddress</tt>. Typically, you'll set a CUPS client to accept browse packets from your local network, and perhaps from some others:

BrowseAllow @LOCAL
BrowseAllow 192.168.17.0/24

The default for <tt>BrowseAllow</tt> is <tt>All</tt>, 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 <tt>BrowseAllow</tt>.

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 <tt>Location</tt> directives. These begin with the keyword <tt>Location</tt> and a location name, surrounded by angle brackets (<tt><></tt>), and end with <tt></Location></tt>:

<Location /printers>
Order Deny,Allow
Deny From All
Allow from 127.0.0.1
Allow from 192.168.1.0/24
Allow from 172.24.21.0/24
Allow From @LOCAL
</Location>

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

<div class="tip">
'''Tip'''

If you can't access the CUPS administration web page, try examining the <tt>/admin</tt> location. Be sure that an <tt>Allow</tt> line grants access to the computer used to access the server. Frequently, this is set to <tt>127.0.0.1</tt>, 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.
</div>

== 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 <tt>[okidata]</tt> to create a printer share called ''OKIDATA''. In order to create a printer share, though, you must set one or more additional parameters:

;<tt>printable</tt>
: This share-level Boolean parameter, when set to <tt>Yes</tt> (the default is <tt>No</tt>), 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 <tt>writeable</tt> parameter and its synonyms; all printable shares are necessarily read/write. A synonym for this parameter is <tt>print ok</tt>.
;<tt>printing</tt>
: This parameter sets the printing system that Linux uses. Samba supports 11 values (<tt>BSD</tt>, <tt>AIX</tt>, <tt>LPRng</tt>, <tt>PLP</tt>, <tt>SysV</tt>, <tt>HPUX</tt>, <tt>QNX</tt>, <tt>SoftQ</tt>, <tt>CUPS</tt>, <tt>OS2</tt>, and <tt>NT</tt>), but only <tt>BSD</tt>, <tt>LPRng</tt>, and <tt>CUPS</tt> are common in Linux. (The <tt>SoftQ</tt> option was removed early in the 3.0.x series, while <tt>OS2</tt> and <tt>NT</tt> 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.
;<tt>print command</tt>
: This share-level parameter sets the command that's used to print a file. The default depends on the <tt>printing</tt> 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 <tt>%s</tt> variable).
;<tt>printer name</tt>
: 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 <tt>%p</tt> variable, which specifies the print queue in the <tt>print command</tt>.
;<tt>printcap name</tt>
: This parameter points Samba at a file that defines local printers. It's important only if you define a <tt>[printers]</tt> share, as described shortly. Ordinarily, this parameter points to ''/etc/printcap'', but if you set <tt>printing = CUPS</tt>, you can also set <tt>printcap</tt> <tt>name = CUPS</tt> 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 <tt>printing</tt> <tt>=</tt> <tt>CUPS</tt>, but Samba won't use the CUPS API, and you may need to set <tt>printcap name = /etc/printcap</tt>.
;<tt>load printers</tt>
: This global Boolean parameter tells Samba whether to load the printers specified in <tt>printcap name</tt> for browsing. This parameter defaults to <tt>Yes</tt>, and if you intend to use a <tt>[printers]</tt> share, you shouldn't change it.
;<tt>min print space</tt>
: 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 <tt>0</tt>, 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 <tt>directory</tt> or its synonym, <tt>path</tt>. These parameters tell Samba where to store the print job before it's submitted to the print queue. The default value of <tt>/tmp</tt> usually works, but you may want to change this to a Samba-specific directory, such as <tt>/var/spool/samba</tt>. 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 <tt>[printers]</tt>. If this share is present, Samba creates individual shares for all of the shares in ''/etc/printcap'' (or another file specified by <tt>printcap name</tt>). Using a <tt>[printers]</tt> 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:

[epson]
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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Delivering Printer Drivers to Windows Clients|Section 4.4]].)

<div class="tip">
'''Tip'''

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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Sharing Non-PostScript Printers|Section 4.3.3]], on the Samba server.
</div>

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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Adding Printers to CUPS|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 <tt>cups options = raw</tt> parameter if you set <tt>printing = CUPS</tt>. 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 <tt>if</tt> 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.

<div class="warning">
'''Warning'''

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 <tt>use</tt> <tt>client</tt> <tt>driver</tt> <tt>=</tt> <tt>Yes</tt>. However, you should ''not'' use this option if you configure Linux to deliver printer drivers to Windows NT/200x/XP clients.
</div>

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 (''http://www.adobe.com/support/downloads/)''. 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Installing drivers from Linux|Section 4.4.3.1]]. 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 <tt>[print$]</tt>. Ultimately, printer driver files will reside in this share, but for the moment you must simply create it. A typical <tt>[print$]</tt> share looks like this:

[print$]
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 (<tt>gutenberg</tt> 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 <tt>PRINT$</tt> share directory. You should also list these users on the <tt>printer</tt> <tt>admin</tt> line in the <tt>[global]</tt> 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 <tt>[printers]</tt> 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.

[printers]
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.

<div class="tip">
'''Tip'''

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

=== Installing the Driver on the Server ===

Once you've reconfigured Samba with the <tt>PRINT$</tt> 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 <tt>'''cupsaddsmb'''</tt> <tt>'''-a'''</tt> on the server system as the printer administrator. The system defaults to installing the CUPS drivers from ''localhost'' to ''localhost''. The <tt>-a</tt> 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 <tt>-v</tt> 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 ''http://www.cups.org/windows.php''. 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 ''http://www.adobe.com/support/downloads/''. 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 ''http://freshmeat.net/projects/cabextract/'' 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-TABLE-1|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.

<div id="linuxwinworld-CHP-4-TABLE-1">
'''Table 4-1. Adobe PostScript driver files'''

{| border="1"
|-
! Windows 9x/Me !! Windows NT/200x/XP
|-
| ADFONTS.MFM || ADOBEPS5.DLL
|-
| ADOBEPS4.DRV || ADOBEPSU.DLL
|-
| ADOBEPS4.HLP || ADOBEPSU.HLP
|-
| DEFPRTR2.PPD || -
|-
| ICONLIB.DLL || -
|-
| PSMON.DLL || -
|}
</div>

Once you've installed the CUPS or Adobe driver files, you can type <tt>'''cupsaddsmb'''</tt> <tt>'''-a'''</tt> 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Installing Drivers on Clients|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 <tt>-v</tt> parameter and check your Samba log files for clues to the cause of the problem.

<div class="tip">
'''Tip'''

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

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

<div class="tip">
'''Tip'''

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

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. [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-TABLE-2|Table 4-2]] summarizes the directories you must add.

<div id="linuxwinworld-CHP-4-TABLE-2">
'''Table 4-2. Windows driver directories in PRINT$ share'''

{| border="1"
|-
! 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''
|}
</div>

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:

<ol>
<li><div>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.
</div></li>

<li><div>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.
</div></li>

<li><div>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.
</div></li>

<li><div>Select the Advanced tab in the Properties dialog box.
</div></li>

<li><div>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.
</div></li>

<li><div>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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-3|Figure 4-3]].

<div id="linuxwinworld-CHP-4-FIG-3">
'''Figure 4-3. Windows ships with a large number of printer drivers'''

[[Image:Linux in a Windows World_I_2_tt36.png|Windows ships with a large number of printer drivers]]
</div>
</div></li>

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

<div class="tip">
'''Tip'''

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.
</div>
</div></li>

<li><div>The Wizard informs you that you're about to add drivers. Click Finish to do so.
</div></li>

</ol>

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.

<ol>
<li><div>Open the Properties dialog box for the printer in question, if necessary.
</div></li>

<li><div>Click the Sharing tab in the Properties dialogue box.
</div></li>

<li><div>Click the Additional Drivers button in the Sharing tab. This action brings up an Additional Drivers dialog box, as shown in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-4|Figure 4-4]].

<div id="linuxwinworld-CHP-4-FIG-4">
'''Figure 4-4. You can install drivers for additional Windows OSs'''

[[Image:Linux in a Windows World_I_2_tt37.png|You can install drivers for additional Windows OSs]]
</div>
</div></li>

<li><div>Check the box next to the Windows version for which you want to install drivers.
</div></li>

<li><div>Click OK. Windows will ask for the location of the drivers.
</div></li>

<li><div>Enter the path to the driver files or browse to them. The system will present a list of printers similar to that shown in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#linuxwinworld-CHP-4-FIG-3|Figure 4-3]].
</div></li>

<li><div>Select the printer and click OK. Windows should install the drivers.
</div></li>

</ol>

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

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

<div class="tip">
'''Tip'''

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

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 <tt>[homes]</tt> 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 <tt>[printers]</tt> 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: <tt>[homes]</tt>. 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 <tt>[homes]</tt> share definition can be quite short:

[homes]
comment = Home Directories
writeable = Yes
create mask = 644
browseable = No

The Samba default is to make shares read-only, but because the intended <tt>[homes]</tt> shares enable users to store files that they create, changing this default is particularly important for these shares. The <tt>create</tt> <tt>mask</tt> <tt>=</tt> <tt>644</tt> 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 <tt>browseable</tt> <tt>=</tt> <tt>No</tt> aren't visible in file browsers, but <tt>[homes]</tt> shares are exceptions to this rule. Specifically, the <tt>browseable</tt> parameter applies to the share called ''HOMES''; if you omit the <tt>browseable = No</tt> parameter or set it to <tt>Yes</tt>, a share called ''HOMES'' appears in clients' network browsers. Part of the definition of the <tt>[homes]</tt> 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 <tt>directory</tt> or <tt>path</tt>; it relies on the <tt>[homes]</tt> 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 <tt>%S</tt>, <tt>%u</tt>, or <tt>%U</tt>; 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 <tt>path</tt> like this:

path = /home/samba/%u

<div class="tip">
'''Tip'''

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 <tt>[homes]</tt> share will be invisible unless you set <tt>browseable =</tt> <tt>Yes</tt>. Such clients might also not work well if you use a <tt>%S</tt> (share name) variable in a <tt>[homes]</tt> share's <tt>path</tt> or <tt>directory</tt> parameter.
</div>

Many sample ''smb.conf'' files include <tt>[homes]</tt> 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 <tt>write</tt> <tt>list</tt> parameter provides an exception to the rule:

[programs]
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 <tt>write</tt> <tt>list</tt>, this example share includes <tt>force</tt> <tt>user</tt> and <tt>force</tt> <tt>group</tt> 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 <tt>force</tt> <tt>user</tt> parameter in conjunction with <tt>write</tt> <tt>list</tt> does ''not'' give all users write access to the share; <tt>write</tt> <tt>list</tt> applies to users' true logon usernames, not their identities as determined by <tt>force</tt> <tt>user</tt>.

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 <tt>create mask</tt> and <tt>directory mask</tt> parameters that deny world access (as in the example) and ensure that these users aren't in the group specified by <tt>force group</tt>.

=== File-Exchange Shares ===

A read-only share such as the <tt>[programs]</tt> 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 <tt>valid users</tt> or <tt>invalid users</tt> 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 <tt>create</tt> <tt>mask=666</tt> and <tt>directory mask=777</tt> or using <tt>force user</tt> 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 <tt>inherit</tt> <tt>permissions</tt> <tt>=</tt> <tt>Yes</tt> 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 (<tt>rwxrwxrwx</tt>) permissions, enabling anybody to read and write it, whereas another subdirectory might have 770 (<tt>rwxrwx---</tt>) 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:

[sanescientists]
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

[madscientists]
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' <tt>valid users</tt> 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 <tt>valid users</tt> line but use <tt>read</tt> <tt>list</tt> to restrict some users' access to the share.

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

[scientists]
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 (<tt>rwxrwxr-x</tt>) rather than 770 (<tt>rwxrwx---</tt>), 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 <tt>valid users</tt> 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.

<div class="tip">
'''Tip'''

Both examples omit the <tt>nt acl support</tt> parameter, which defaults to <tt>Yes</tt>. 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.
</div>

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 <tt>[printers]</tt> 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 <tt>[printers]</tt> share, be sure to set the following parameters in the <tt>[global]</tt> section of ''smb.conf'':

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

In this example, the <tt>printing</tt> and <tt>printcap name</tt> parameters are both set to <tt>CUPS</tt>, 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 <tt>printing</tt> <tt>=</tt> <tt>LPRng</tt> and <tt>printcap</tt> <tt>name</tt> <tt>=</tt> <tt>/etc/printcap</tt>.

<div class="tip">
'''Tip'''

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 <tt>printing</tt> <tt>=</tt> <tt>CUPS</tt> (Samba will use old-style printing commands rather than the CUPS API to submit print jobs). You may need to set <tt>printcap</tt> <tt>name</tt> <tt>=</tt> <tt>/etc/printcap</tt>, 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 <tt>printing</tt> <tt>=</tt> <tt>LPRng</tt>, <tt>printing</tt> <tt>=</tt> <tt>BSD</tt>, or certain other values.
</div>

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

The <tt>printer admin</tt> 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 <tt>guest</tt> <tt>ok</tt> <tt>=</tt> <tt>Yes</tt> 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 <tt>map to guest</tt> and <tt>guest</tt> <tt>account</tt> 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 <tt>[printers]</tt> share. This share is likely to be fairly uninteresting on the surface:

[printers]
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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Delivering Printer Drivers to Windows Clients|Section 4.4]].

Using a <tt>[printers]</tt> 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 <tt>[printers]</tt> 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 <tt>[printers]</tt> share.

The shares generated by <tt>[printers]</tt> 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 <tt>[printers]</tt> 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 <tt>print</tt> <tt>command</tt> 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 <tt>print command</tt>:

[makepdf]
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 <tt>%H</tt> is the user's home directory and <tt>%s</tt> 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 <tt>print command</tt> line ends with <tt>rm %s</tt>, which deletes the original print job, keeping it from cluttering the disk.

Of course, the <tt>[makepdf]</tt> share, as just presented, requires users to have access to their home directories, presumably through a <tt>[homes]</tt> 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 <tt>print command</tt> line, passing it whatever Samba variables you need, such as the print job filename (<tt>%s</tt>) and the username (<tt>%u</tt> or <tt>%U</tt>).

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.

<div class="tip">
'''Tip'''

You may want to install drivers in Samba for the share for automated delivery to clients, as described in [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Delivering Printer Drivers to Windows Clients|Section 4.4]]. You can do so from a Windows client, as described in the [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Installing drivers from Windows NT/200x/XP|Section 4.4.3.2]]. 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 [[Linux in a Windows World/Sharing Files and Printers/File and Printer Shares#Installing drivers from Linux|Section 4.4.3.1]]. 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.
</div>

== Summary ==

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.

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

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook