9.2 Controlling Access to Shares

Often you will need to restrict the users who can access a specific share for security reasons. This is very easy to do with Samba because it contains a wealth of options for creating practically any security configuration. Let's introduce a few configurations that you might want to use in your own Samba setup.

We've seen what happens when you specify valid users. However, you are also allowed to specify a list of invalid users ”users who should never be allowed access to Samba or its shares. This is done with the invalid users option. We hinted at one frequent use of this option earlier: a global default with the [ homes ] section to ensure that various system users and superusers cannot be forged for access. For example:

 [global]     invalid users = root bin daemon adm sync shutdown \                         halt mail news uucp operator     auto services = dave peter bob [homes]     browsable = no     writable = yes 

The invalid users option, like valid users , can take group names , preceded by an at sign ( @ ), as well as usernames. In the event that a user or group appears in both lists, the invalid users option takes precedence, and the user or group is denied access to the share.

At the other end of the spectrum, you can explicitly specify users who will be allowed superuser (root) access to a share with the admin users option. An example follows :

 [sales]         path = /home/sales         comment = Sedona Real Estate Sales Data         writable = yes         valid users = sofie shelby adilia         admin users = mike 

This option takes both group names and usernames. In addition, you can specify NIS netgroups by preceding them with an @ as well; if the netgroup is not found, Samba will assume that you are referring to a standard Unix group.

Be careful if you assign administrative privileges to a share for an entire group. The Samba Team highly recommends you avoid using this option, as it essentially gives root access to the specified users or groups for that share.

If you wish to force read-only or read/write access on users who access a share, you can do so with the read list and write list options, respectively. These options can be used on a per-share basis to restrict a writable share or to grant write access to specific users in a read-only share, respectively. For example:

 [sales]         path = /home/sales         comment = Sedona Real Estate Sales Data         read only = yes         write list = sofie shelby 

The write list option cannot override Unix permissions. If you've created the share without giving the write-list user write permission on the Unix system, she will be denied write access regardless of the setting of write list .

9.2.1 Guest Access

As mentioned earlier, you can configure a share using guest ok = yes to allow access to guest users. This works only when using share-level security, which we will cover later in this chapter. When a user connects as a guest, authenticating with a username and password is unnecessary, but Samba still needs a way to map the connected client to a user on the local system. The guest account parameter can be used in the share to specify the Unix account that guest users should be assigned when connecting to the Samba server. The default value for this is set during compilation and is typically nobody , which works well with most Unix versions. However, on some systems the nobody account is not allowed to access some services (e.g., printing), and you might need to set the guest user to ftp or some other account instead.

If you wish to restrict access in a share only to guests ”in other words, all clients connect as the guest account when accessing the share ”you can use the guest only option in conjunction with the guest ok option, as shown in the following example:

 [sales]         path = /home/sales         comment = Sedona Real Estate Sales Data         writable = yes         guest ok = yes         guest account = ftp         guest only = yes 

Make sure you specify yes for both guest only and guest ok ; otherwise , Samba will not use the guest account that you specify.

9.2.2 Access Control Options

Table 9-1 summarizes the options that you can use to control access to shares.

Table 9-1. Share-level access options

Option	Parameters	Function	Default	Scope
admin users	string (list of usernames)	Users who can perform operations as root	None	Share
valid users	string (list of usernames)	Users who can connect to a share	None	Share
invalid users	string (list of usernames)	Users who will be denied access to a share	None	Share
read list	string (list of usernames)	Users who have read-only access to a writable share	None	Share
write list	string (list of usernames)	Users who have read/write access to a read-only share	None	Share
max connections	numeric	Maximum number of connections for a share at a given time		Share
guest only (only guest)	Boolean	If yes , allows only guest access	no	Share
guest account	string ( name of account)	Unix account that will be used for guest access	nobody	Share

9.2.2.1 admin users

This option specifies a list of users that perform file operations as if they were root . This means that they can modify or destroy any other user's files, regardless of the permissions. Any files that they create will have root ownership and will use the default group of the admin user. The admin users option allows PC users to act as administrators for particular shares. Be very careful when using this option, and make sure good password and other security policies are in place.

9.2.2.2 valid users, invalid users

These two options let you enumerate the users and groups who are granted or denied access to a particular share. You can enter a list of user and/or group names. If a name is prefixed by an at sign ( @ ), it is interpreted as a group name ”with NIS groups searched before Unix groups. If the name is prefixed by a plus sign ( + ), it is interpreted as the name of a Unix group, and NIS is not searched. If the name is prefixed by an ampersand ( & ), it is interpreted as an NIS group name rather than as a Unix group name. The plus sign and ampersand can be used together to specify whether NIS or Unix groups are searched first. For example:

 [database]     valid users = mary ellen sue &sales +marketing @dbadmin     invalid users = gavin syd dana &techies +&helpdesk 

In the valid users parameter, users mary , ellen , and sue are allowed access to the [database] share, as are the members of the Unix group marketing and NIS/Unix group dbadmin . The invalid users parameter denies access to the share by users gavin , syd , and dana , as well as members of the NIS group techies and Unix/NIS group helpdesk . In this last case, the list of Unix groups is searched first for the helpdesk group, and if it is not found there, the list of NIS groups is searched.

The important rule to remember with these options is that any name or group in the invalid users list will always be denied access, even if it is included (in any form) in the valid users list.

9.2.2.3 read list, write list

Like the valid users and invalid users options, this pair of options specifies which users have read-only access to a writable share and read/write access to a read-only share, respectively. The value of either options is a list of users. The read list parameter overrides any other Samba permissions granted ”as well as Unix file permissions on the server system ”to deny users write access. The write list parameter overrides other Samba permissions to grant write access, but cannot grant write access if the user lacks write permissions for the file on the Unix system. You can specify NIS or Unix group names by prefixing the name with an at sign (such as @users ). Neither configuration option has a default value associated with it.

9.2.2.4 max connections

This option specifies the maximum number of client connections that a share can have at any given time. Any connections that are attempted after the maximum is reached will be rejected. The default value is , which is a special case that allows an unlimited number of connections. You can override it per share as follows:

 [accounting]     max connections = 30 

This option is useful in the event that you need to limit the number of users who are accessing a licensed program or piece of data concurrently.

9.2.2.5 guest only

This share-level option (also called only guest ) forces a connection to a share to be performed with the user specified by the guest account option. The share to which this is applied must explicitly specify guest ok = yes for this option to be recognized by Samba. The default value for this option is no .

9.2.2.6 guest account

This option specifies the name of the account to be used for guest access to shares in Samba. The default for this option varies from system to system, but it is often set to nobody . Some default user accounts have trouble connecting as guest users. If that occurs on your system, the Samba Team recommends using the ftp account as the guest user.

9.2.3 Username Options

Table 9-2 shows two additional options that Samba can use to correct for incompatibilities in usernames between Windows and Unix.

Table 9-2. Username options

Option	Parameters	Function	Default	Scope
username map	string (filename)	Sets the name of the username mapping file	None	Global
username level	numeric	Indicates the number of capital letters to use when trying to match a username		Global

9.2.3.1 username map

Client usernames on an SMB network can be relatively long (up to 255 characters), while usernames on a Unix network often cannot be longer than eight characters. This means that an individual user can have one username on a client and another (shorter) one on the Samba server. You can get past this issue by mapping a free-form client username to a Unix username of eight or fewer characters . It is placed in a standard text file, using a format that we'll describe shortly. You can then specify the pathname to Samba with the global username map option. Be sure to restrict access to this file; make the root user the file's owner and deny write access to others (with octal permissions of 744 or 644). Otherwise, an untrusted user with access to the file can easily map his client username to the root user of the Samba server.

You can specify this option as follows:

 [global]     username map = /usr/local/samba/private/usermap.txt 

Each entry in the username map file should be listed as follows: the Unix username, followed by an equal sign ( = ), followed by one or more whitespace-separated SMB client usernames. Note that unless instructed otherwise (i.e., a guest connection), Samba will expect both the client and the server user to have the same password. You can also map NT groups to one or more specific Unix groups using the @ sign. Here are some examples:

 jarwin = JosephArwin manderso = MarkAnderson users = @account 

You can also use the asterisk to specify a wildcard that matches any free-form client username as an entry in the username map file:

 nobody = * 

Comments can be placed in the file by starting the line with a hash mark ( # ) or a semicolon ( ; ).

Note that you can also use this file to redirect one Unix user to another user. Be careful, though, as Samba and your client might not notify the user that the mapping has been made and Samba might be expecting a different password.

9.2.3.2 username level

SMB clients (such as Windows) will often send usernames in SMB connection requests entirely in capital letters; in other words, client usernames are not necessarily case-sensitive. On a Unix server, however, usernames are case-sensitive: the user ANDY is different from the user andy . By default, Samba attacks this problem by doing the following:

1. Checking for a user account with the exact name sent by the client

2. Testing the username in all lowercase letters

3. Testing the username in lowercase letters with only the first letter capitalized

If you wish to have Samba attempt more combinations of upper- and lowercase letters, you can use the username level global configuration option. This option takes an integer value that specifies how many letters in the username should be capitalized when attempting to connect to a share. You can specify this option as follows:

 [global]     username level = 3 

In this case, Samba attempts all possible permutations of usernames having three capital letters. The larger the number, the more computations Samba has to perform to match the username, and the longer the authentication will take.