Chapter 8. Advanced Disk Shares

dont descend

follow symlinks

This option controls whether Samba will follow a symbolic link in the Unix operating system to the target or if it should return an error to the client user. If the option is set to yes, the target of the link will be interpreted as the file. If set to no, an error will be generated if the symbolic link is accessed.

getwd cache

This global option specifies whether Samba should use a local cache for the Unix getwd( ) ( get current working directory) system call. You can override the default value of yes as follows:

[global]
    getwd cache = no

Setting this option to no can significantly increase the time it takes to resolve the working directory, especially if the wide links option is set to no. You should normally not need to alter this option.

wide links

This option specifies whether the client user can follow symbolic links that point outside the shared directory tree. This includes any files or directories at the other end of the link, as long as the permissions are correct for the user. The default value for this option is yes. Note that this option will not be honored if the follow symlinks options is set to no. Setting this option to no slows smbd considerably because it will have to check each link it encounters.

hide dot files

hide files

Each entry in the list must begin, end, or be separated from another entry with a slash (/) character, even if only one pattern is listed. This allows spaces to appear in the list. Asterisks can be used as a wildcard to represent zero or more characters. Questions marks can be used to represent exactly one character. For example:

hide files = /.jav*/README.???/

veto files

More stringent than the hidden files state is the state provided by the veto files configuration option. Samba won't even admit these files exist. You cannot list or open them from the client. This should not be used as a means of implementing security. It is actually a mechanism to keep PC programs from deleting special files, such as ones used to store the resource fork of a Macintosh file on a Unix filesystem. If both Windows and Macs are sharing the same files, this can prevent ill-advised power users from removing files the Mac users need.

The syntax of this option is identical to that of the hide files configuration option: each entry must begin, end, or be separated from another with a slash ( / ) character, even if only one pattern is listed. Asterisks can be used as a wildcard to represent zero or more characters. Question marks can be used to represent exactly one character. For example:

veto files = /*config/*default?/

This option is primarily administrative and is not a substitute for good file permissions.

delete veto files

create mask

The argument for this option is an octal number indicating which permission flags can be set at file creation by a client in a share. The default is 0744, which means that the Unix owner can at most read, write, and optionally execute her own files, while members of the user's group and others can only read or execute them. If you need to change it for nonexecutable files, we recommend 0644, or rw-r--r--. Keep in mind that the execute bits can be used by the server to map certain DOS file attributes, as described earlier. If you're altering the create mask, those bits have to be part of the create mask as well.

directory mask

The argument for this option is an octal number indicating which permission flags can be set at directory creation by a client in a share. The default is 0744, which allows everyone on the Unix side to, at most, read and traverse the directories, but allows only you to modify them. We recommend the mask 0750, removing access by "the world."

force create mode

This option sets the permission bits that Samba will set when a file permission change is made. It's often used to force group permissions, as mentioned previously. It can also be used to preset any of the DOS attributes we mentioned: archive (0100), system (0010), or hidden (0001).

force directory mode

This option sets the permission bits that Samba will set when a directory permission change is made or a directory is created. It's often used to force group permissions, as mentioned previously. This option defaults to 0000 and can be used just like the force create mode to add group or other permissions if needed.

force group

This option, sometimes called group, assigns a static group ID that will be used on all connections to a share after the client has successfully authenticated. This assigns a specific group to each new file or directory created from an SMB client.

force user

delete readonly

This option allows a user to delete a directory containing a read-only file. By default, DOS and Windows will not allow such an operation. You probably will want to leave this option turned off unless a program (for example, an RCS program) needs this capability; many Windows users would be appalled to find that they'd accidentally deleted a file that they had set as read-only.

map archive

The DOS archive bit is used to flag a file that has been changed since it was last archived (e.g., backed up with the DOS archive program). Setting the Samba option map archive = yes maps the DOS archive flag to the Unix execute-by-owner (0100) bit. It's best to leave this option on if your Windows users are doing their own backups or are using programs that require the archive bit. Unix lacks the notion of an archive bit entirely. Backup programs typically keep a file that lists what files were backed up on what date, so comparing file-modification dates serves the same purpose.

Setting this option to yes causes an occasional surprise on Unix when a user notices that a datafile is marked as executable, but rarely causes harm. If a user tries to run it, he will normally get a string of error messages as the shell tries to execute the first few lines as commands. The reverse is also possible; an executable Unix program looks like it hasn't been backed up recently on Windows. But again, this is rare and usually harmless.

For map archive to work properly, the execute bit for owner must not be masked off with the create mask parameter.

map system

The DOS system attribute indicates files that are required by the operating system and should not be deleted, renamed, or moved without special effort. Set this option only if you need to store Windows system files on the Unix fileserver. Executable Unix programs will appear to be nonremovable, special Windows files when viewed from Windows clients. This might prove mildly inconvenient if you want to move or remove one. For most sites, however, this is fairly harmless.

For map archive to work properly, the execute bit for group must not be masked off with the create mask parameter.

map hidden

DOS uses the hidden attribute to indicate that a file should not ordinarily be visible in directory listings. Unix doesn't have such a facility; it's up to individual programs (notably, the shell) to decide what to display and what not to display. Normally, you won't have any DOS files that need to be hidden, so the best thing to do is to leave this option turned off.

Setting this option to yes causes the server to map the hidden flag onto the executable-by-others bit (0001). This feature can produce a rather startling effect. Any Unix program that is executable by world seems to vanish when you look for it from a Windows client. If this option is not set, however, and a Windows user attempts to mark a file hidden on a Samba share, it will not work—Samba has no place to store the hidden attribute!

For map archive to work properly, the execute bit for other must not be masked off with the create mask parameter.

inherit permissions

nt acl support

This parameter defaults to yes, which allows users on Windows NT/2000/XP clients to modify ACL settings for files on the Samba server. When set to no, files show up as owned by Everyone, with permissions appearing as "Full Control". However, actual ownership and permissions are enforced as whatever they are set to on the Samba server, and the user on the Windows client cannot view or modify them with the dialog boxes used for managing ACLs.

When enabled, support for Windows NT/2000/XP ACLs is limited to whatever ownerships and permissions can map into valid users and permissions on the Samba server. If the server supports ACLs (either "out of the box" or with an additional patch to enhance the filesystem), Samba's ACL support more closely matches that of a Windows NT/2000/XP server.

security mask

[data]
    security mask = 0777

the client can modify all the user/group/other permissions for the files in the share. This is the default. A value of 0 would deny clients from changing any of the permissions, and setting security mask as:

[data]
    security mask = 0666

would allow client users to modify the read and write permissions, but not the execute permissions.

Do not count on security mask for complete control because if the user can access the files on the Samba server through any other means (for example, by logging directly into the Unix host), he can modify the permissions using that method.

force security mode

Be careful to understand this properly. The mask given as the parameter's value is not necessarily equal to the resulting permissions on the file. The permissions that the client user attempts to modify are logically OR'd with the force security mode mask option, and any bits that are turned on will cause the file's corresponding permissions to be set. As an example, suppose force security mode is set in a share thusly:

[data]
    force security mode = 0440

(This sets the read bit for owner and group, but not other.) If a user on a Windows NT/2000/XP client modifies an ACL on a file in the [data] share and attempts to remove all read permissions, the read permission for other (Everyone) will be removed, but the read permission for the owner and group will remain. Note that this parameter cannot force a permission bit to be turned off.

As with the security mask option, if a user can access the files in the share through any means other than Samba, she can easily work around Samba's enforcement of this parameter.

The default value of force security mode is 0000, which allows users to remove any permission from files.

directory security mask

This option works exactly the same as the security mask option, except that it operates on directories rather than files. As with security mask, it has a default value of 0777, which allows Windows NT/2000/XP client users to modify all Unix permissions on directories in the share.

force directory security mode

Representing and resolving filenames with Samba

C:\> notepad readme.txt

the all-caps file is loaded into the editing program, even though you typed the name in lowercase letters.

This is because the Windows 95/98/Me and Windows NT/2000/XP families of operating systems resolve filenames in a case-insensitive manner, even though the files are represented in a case-sensitive manner. Unix-based operating systems, on the other hand, always resolve files in a case-sensitive manner; if you try to edit README.TXT with the command:

$ vi readme.txt

you will likely be editing the empty buffer of a new file.

case sensitive

This share-level option, which has the obtuse synonym casesignames, specifies whether Samba should preserve case when resolving filenames in a specific share. The default value for this option is no, which is how Windows handles file resolution. If clients are using an operating system that takes advantage of case-sensitive filenames, you can set this configuration option to yes as shown here:

[accounting]
    case sensitive = yes

Otherwise, we recommend that you leave this option set to its default.

default case

[global]
    default case = upper

If you specify this value, the names of newly created files are translated into uppercase and cannot be overridden in a program. We recommend that you use the default value unless you are dealing with a Windows for Workgroups or other 8.3 client, in which case it should be upper.

preserve case

This option specifies whether a file created by Samba on behalf of the client is created with the case provided by the client operating system or the case specified by the earlier default case configuration option. The default value is yes, which uses the case provided by the client operating system. If it is set to no, the value of the default case option (upper or lower) is used.

Note that this option does not handle 8.3 file requests sent from the client—see the upcoming short preserve case option. You might want to set this option to yes, for example, if applications that create files on the Samba server demand the file be all uppercase. If instead you want Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, yes.

short preserve case

This option specifies whether an 8.3 filename created by Samba on behalf of the client is created with the default case of the client operating system or the case specified by the default case configuration option. The default value is yes, which uses the case provided by the client operating system. You can let Samba choose the case through the default case option by setting it as follows:

[global]
    short preserve case = no

If you want to force Samba to mimic the behavior of a Windows NT filesystem, you can leave this option set to its default, yes.

mangled names

This share-level option specifies whether Samba will mangle filenames for 8.3 clients. If the option is set to no, Samba will not mangle the names, and (depending on the client) they will either be invisible or appear truncated to those using 8.3 operating systems. The default value is yes. You can override it per share as follows:

[data]
    mangled names = no

mangle case

This option tells Samba whether it should mangle filenames that are not composed entirely of the case specified using the default case configuration option. The default for this option is no. If you set it to yes, you should be sure that all clients can handle the mangled filenames that result. You can override it per share as follows:

[data]
    mangle case = yes

We recommend that you leave this option alone unless you have a well-justified need to change it.

mangling char

This share-level option specifies the mangling character used when Samba mangles filenames into the 8.3 format. The default character used is a tilde (~). You can reset it to whatever character you wish. For instance:

[data]
    mangling char = #

mangled stack

Samba maintains a local stack of recently mangled 8.3 filenames; this stack can be used to reverse-map mangled filenames back to their original state. This is often needed by applications that create and save a file, close it, and need to modify it later. The default number of long filename/mangled filename pairs stored on this stack is 50. However, if you want to cut down on the amount of processor time used to mangle filenames, you can increase the size of the stack to whatever you wish, at the expense of memory and slightly slower file access:

[global]
    mangled stack = 100

mangled map

If the default behavior of name mangling is not sufficient, you can give Samba further instructions on how to behave using the mangled map option. This option allows you to specify mapping patterns that can be used in place of name mangling performed by Samba. For example:

[data]
    mangled map =(*.database *.db) (*.class *.cls)

locking

This option can be specified per share as follows:

[accounting]
    locking = yes

If the locking option is set to yes, the requestor is delayed until the holder of either type of lock releases it (or crashes). If, however, the option is set to no, no byte-range locks are kept for the files, although requests to lock and unlock files will appear to succeed. The option is set to yes by default; however, you can turn this option off if you have read-only media.

strict locking

This option checks every file access for a byte-range lock on the range of bytes being accessed. This is typically not needed if a client adheres to all the locking mechanisms in place. This option is set to no by default; however, you can reset it per share as follows:

[accounting]
    strict locking = yes

If this option is set to yes, mandatory locks are enforced on any file with byte-range locks.

posix locking

On systems that support POSIX locking, Samba automatically maps oplocks to POSIX locks. This behavior can be disabled by setting posix locking = no. You should never need to change the default behavior, which is posix locking = yes.

oplocks

This option enables or disables support for oplocks on the client. The option is enabled by default. However, you can disable it with the following command:

[data]
    oplocks = no

If you are in an extremely unstable network environment or have many clients that cannot take advantage of opportunistic locking, it might be better to shut this Samba feature off. If the host operating system does not support kernel oplocks, oplocks should be disabled if users are accessing the same files from both Unix applications (such as vi) and SMB clients.

kernel oplocks

If a Unix application on the Samba host system (that is not part of the Samba suite) tries to open a file for writing that Samba has oplocked to a Windows client, it is likely to succeed (depending on the operating system), and both Samba and the client are never aware of it.

Some versions of Unix have support for oplocks in the kernel that can work along with Samba's oplocks. In this case, the Unix process trying to open the file is suspended while Samba directs the client to write its copy back. After that has happened, the operating system allows the open to complete. At the time of this writing, this feature is supported only by SGI Irix and Linux.

level2 oplocks

Windows NT/2000/XP clients can downgrade their read-write oplocks to read-only oplocks when another client opens the same file. This can result in significant improvements in performance on files that are written infrequently or not at all—especially executables—because all clients can then maintain a read-ahead cache for the file. By default, level2 oplocks is set to yes, and you probably won't need to change it.

Currently, Samba cannot support level 2 oplocks along with kernel oplocks and automatically disables level 2 oplocks when kernel oplocks are in use. (This might change in future releases as improved support for oplocks is added by the Samba developers.) If you are running Samba on a host system that supports kernel oplocks, you must set kernel oplocks = no to enable support for level 2 oplocks.

Disabling oplocks with oplocks = no also disables level 2 oplocks.

Samba can automatically detect its Unix host's support of kernel oplocks and will set the value of kernel oplocks automatically. You should never need to set this option in your Samba configuration file.

fake oplocks

When this option is set to yes, Samba pretends to allow oplocks rather than actually supporting them. If this option is enabled on a read-only share (such as a shared CD-ROM drive), all clients are told that the files are available for opportunistic locking and never warned of simultaneous access. As a result, Windows clients cache more of the file's data and obtain much better performance.

This option was added to Samba before opportunistic-locking support was available, and it is now generally considered better to use real oplocks. Do not ever enable fake oplocks on a read/write share.

blocking locks

Samba also supports blocking locks, a minor variant of range locks. Here, if the range of bytes is not available, the client specifies an amount of time that it's willing to wait. The server then caches the lock request, periodically checking to see if the file is available. If it is, it notifies the client; however, if time expires, Samba will tell the client that the request has failed. This strategy prevents the client from continually polling to see if the lock is available.

You can disable this option per share as follows:

[accounting]
    blocking locks = no

When set to yes, blocking locks are enforced on the file. If this option is set to no, Samba behaves as if normal locking mechanisms are in place on the file. The default is yes.

veto oplock files

You can provide a list of filenames that are never granted opportunistic locks with the veto oplock files option. This option can be set either globally or on a per-share basis. For example:

veto oplock files = /*.bat/*.htm/

The value of this option is a series of patterns. Each pattern entry must begin, end, or be separated from another with a slash ( / ) character, even if only one pattern is listed. Asterisks can be used as a wildcard to represent zero or more characters. Questions marks can be used to represent exactly one character.

We recommend that you disable oplocks on any files that are meant to be updated by Unix or are intended for simultaneous sharing by several processes.

lock directory

This option (sometimes called lock dir) specifies the location of a directory where Samba will store SMB deny-mode lock files. Samba stores other files in this directory as well, such as browse lists and its shared memory file. If WINS is enabled, the WINS database is written to this directory as well. The default for this option is specified in the Samba makefile; it is typically /usr/local/samba/var/locks. You can override this location as follows:

[global]
    lock directory = /usr/local/samba/locks

root preexec

This option specifies as its value a Unix command to be run as the root user before any connection to a share is completed. You should use this option specifically for performing actions that require root privilege.

To ensure security, users should never be able to modify the target of the root preexec command. In addition, unless you explicitly redirect it, any information the command sends to standard output will be discarded. If you intend to use any preexec or postexec script, you should ensure that it will run correctly before having Samba invoke it.

root preexec close

Sometimes you might want the share to disconnect if the root preexec script fails, giving the client an error rather than allowing it to connect. For example, if you are using root preexec to mount a CD-ROM or filesystem, it would make no sense to connect the client to it in the event that the mount fails. If you specify root preexec close = yes, the share will fail to connect if the root preexec script returns a nonzero exit status.

preexec

Sometimes just called exec, this option defines an ordinary unprivileged command run by Samba as the user specified by the variable %u. For example, a common use of this option is to perform logging, such as the following:

[homes]
    preexec = echo "%u connected from %m (%I)\" >>/tmp/.log

You must redirect the standard output of the command if you want to use it. Otherwise, it is discarded. This warning also applies to the command's standard error output. If you intend to use a preexec script, you should ensure that it will run correctly before having Samba invoke it.

preexec close

This is similar to root preexec close, except that it goes with the preexec option. By setting preexec close = yes, a preexec script that returns nonzero will cause the share to disconnect immediately.

postexec

Once the user disconnects from the share, the command specified with postexec is run as the user on the Samba server to do any necessary cleanup. This option is essentially the same as the preexec option. Again, remember that the command is run as the user represented by %u, and any information sent to standard output will be ignored.

root postexec

Setting up the Dfs root

First we need to create a directory to act as the Dfs root:

# mkdir /usr/local/samba/dfs

This can be any directory, but it is important that it be owned by root and given the proper permissions:

# chown root:root /usr/local/samba/dfs
# chmod 755 /usr/local/samba/dfs

The Dfs directory tree can have subdirectories and files, just like any other shared directory. These will function just as they would in any other share, allowing clients to access the directories and files on the Samba server. The whole idea of Dfs, though, is to gather together shares on other servers by making references to them in the Dfs tree. The way this is implemented with Samba involves a clever use of symbolic links, which can be in the Dfs root directory or any subdirectory in the Dfs tree.

You are probably familiar with using symbolic links to create references to files that exist on the same system, and perhaps crossing a local filesystem boundary (which ordinary Unix links cannot do). But maybe you didn't know that symbolic links have a more general functionality. Although we can't display its contents directly, as we could with a text or binary file, a symbolic link "contains" an ASCII text string naming what the link points to. For example, take a look at the listing for these symbolic links:

$ ls -l wrdlnk alnk
lrwxrwxrwx    1 jay      jay            15 Mar 14 06:50 wrdlnk -> /usr/dict/words
lrwxrwxrwx    1 jay      jay             9 Mar 14 06:53 alnk -> dreamtime

As you can infer from the size of the wrdlnk link (15 bytes), the string /usr/dict/words is encoded into it. The size of alnk (9 bytes) is smaller, corresponding to the shorter name of dreamtime.

Now let's create a link in our Dfs root for an SMB share:

# cd /usr/local/samba/dfs
# ln -s 'msdfs:maya\e' maya-e
# ls -l maya-e
lrwxrwxrwx    1 root     root           12 Mar 13 17:34 maya-e -> msdfs:maya\e

This link might appear as a "broken" link in a directory listing because it points to something that isn't a file on the local system. For example, the file command will report:

$ file maya-e
maya-e: broken symbolic link to msdfs:maya\e

However, maya-e is a valid reference to the \\maya\e share when used with Samba's Dfs support. When Samba encounters this file, it sees the leading msdfs: and interprets the rest as the name of a remote share. The client is then redirected to the remote share.

When creating links in the Dfs root directory, simply follow the same format, which in general is msdfs:server\share. Note that this is similar to a UNC appended onto the msdfs: string, except that in this case, the two backslashes preceding the server's name are omitted.

TIP

The names for the symbolic links in Dfs shares must be in all lowercase.

Load balancing

# ln -s 'msdfs:toltec\data,msdfs:mixtec\data' lb-data

That is, simply use a list of shares separated by commas as the reference. Remember, it is up to you to make sure the shared folders remain identical. Set up permissions on the servers to make the shares read-only to users.

The last thing we need to do is to modify the smb.conf file to define the Dfs root share and add Dfs support. The Dfs root is added as a share definition:

[dfs]
    path = /usr/local/samba/dfs
    msdfs root = yes

You can use any name you like for the share. The path is set to the Dfs root directory we just set up, and the parameter msdfs root = yes tells Samba that this share is a Dfs root.

To enable support for Dfs in the server, we need to add one line to the [global] section:

[global]
    host msdfs = yes

TIP

If you previously had a share by the same name as your Dfs share, you might need to reboot Windows clients before they can access the share as a Dfs share.

nis homedir, homedir map

The nis homedir option indicates that the home-directory server for the user needs to be looked up in NIS. The homedir map option tells Samba in which NIS map to look for the server that has the user's home directory. The server needs to be a Samba server so that the client can do an SMB connect to it, and the other Samba servers need to have NIS installed so that they can do the lookup.

For example, if user joe asks for a share called [joe], and the nis homedir option is set to yes, Samba will look in the file specified by homedir map for a home directory for joe. If it finds one, Samba will return the associated system name to the client. The client will then try to connect to that machine and get the share from there. Enabling NIS lookups looks like the following:

[globals]
    nis homedir = yes
    homedir map = amd.map