Authorizing Users in Samba

In this conclusion to a four-part series that covers authentication and authorization in Samba, you will learn about group mapping, user privilege management, and more. This article is excerpted from chapter five of Using Samba, Third Edition, written by Gerald Carter, Jay Ts and Robert Eckstein (O’Reilly, 2007; ISBN: 0596007698). Copyright © 2007 O’Reilly Media, Inc. All rights reserved. Used with permission from the publisher. Available from booksellers or direct from O’Reilly Media.

Group Mapping

Remember that Samba exports Unix objects in a means that is palatable to Windows clients. In keeping with this philosophy, Unix groups are handled in a very similar fashion to Unix users. The underlying Unix group must already exist. Samba then associates a SID and name with that group and displays it to Windows. This operation is referred to as group mapping. The additional attributes can be manipulated using the net groupmap command.

The group mapping functionality is provided as part of Samba’s passdb API and therefore shares the same storage mechanisms as user accounts. Both the smbpasswd and tdbsam passdb modules use the group_mapping.tdb file (stored in /usr/local/ samba/var/locks by default). The ldapsam backend stores mapping entries by adding the sambaGroupMapping auxiliary object class to an existing posixGroup entry in the directory service. For all three backends, the actual table entries can be managed using the same Samba command-line tools (as was the case with user accounts).

The group mapping interfaces and internal design have been given a new look starting with the 3.0.23 release. However, the basic concept is the same as in previous releases. Only the tools have changed. The new interface is a command set named net sam, which provides an interface to users, groups, and password policies. At the time of writing, the toolset is not yet complete.

A group mapping entry is primarily an association from a SID to a Unix gid. A current entry can be viewed using the net groupmap list command. Be aware that all of the net groupmap commands must be run as root, because they operate on the passdb storage service directly.

  root# net groupmap list verbose ntgroup="Printer Admins"
Printer Admins
SID       : S-1-5-21-391507597-2097566357-2340928898-3091
Unix group: prtadmin
Group type: Domain Group
Comment   : Domain Unix group

Printer Admins is the name that will be displayed to Windows clients. The membership of this group is handled by managing the prtadmin Unix group membership. Only those Unix groups that posses a valid group mapping entry are displayed, as illustrated by Figure 5-3. The same is true for users: only those users who have an account in the current passdb backend are displayed in the Windows object picker UI.

You can view a complete list of current group mappings by omitting the group name when entering net groupmap list. But groups mapped to a value of –1 are placeholder entries created by smbd and are ignored.

  root# net groupmap list
Printer Admins (S-1-5-21-391507597-2097566357-2340928898-3091) -> prtadmin
  Administrators (S-1-5-32-544) -> -1
  Domain Admins (S-1-5-21-391507597-2097566357-2340928898-512) -> -1
  Users (S-1-5-32-545) -> -1
  Domain Guests (S-1-5-21-391507597-2097566357-2340928898-514) -> -1
  Domain Users (S-1-5-21-391507597-2097566357-2340928898-513) -> -1

    remaining output deleted

The placeholder entries are not present when using an ldapsam passdb backend. Future versions of Samba will remove them from the remainng backends for the sake of consistency.

New maps can be added by executing net groupmap add and including the Unix group name and either a SID or simply a Windows group map. It is better to define the ntgroup name value and allow Samba to allocate a SID unless you have a specific group (e.g., Domain Admins) that you require.

  root# net groupmap add ntgroup="System Managers" unixgroup=sysadmin
No rid or sid specified, choosing algorithmic mapping
  Successfully added group Systems Managers to the mapping db

Figure 5-3.  Displaying users and groups in the windows object picker

The associated Unix group and group description can be changed with the modify subcommand:

  root# net groupmap modify ntgroup="System Managers" unixgroup=sysops comment="Server
  administrators group"

  Updated mapping entry for System Managers

The Unix gid is not stored in the map entry and is therefore unaffected by renaming a group in /etc/group. In this example, the sysops and sysadmins groups are entirely different groups on the Unix server.

Finally, you can remove entries using net groupmap delete:

  root# net groupmap delete ntgroup="Systems Managers"
  Successfully removed Systems Managers from the mapping db

Table 5-14 gives a brief overview of the net groupmap command-line arguments.

There are more esoteric things that can be done with the net groupmap tool. Most of these are prone to error and are not recommend for nor mal use. The options covered in this section are the most common and the least likely to change in a future Samba release.

Table 5-14. net groupmap command-line options





{ntgroup=name,sid=sid_string} unixgroup=name

Add a new group mapping between a Unix group and a Windows group name or SID.






Remove an existing group mapping entry.


[verbose] [ntgroup=name,sid=sid_string]

List all or a specific group mapping record. The verbose option includes all map attributes.



Update an existing group mapping record.







{mospagebreak title=User Privilege Management}

The user privilege model was introduced in Samba 3.0.11 to alleviate the need to log on as root to perform certain administrative duties, such as joining client machines to a Samba domain or managing printer properties. A user privilege, sometimes called a user right, is the inherent capability to perform certain actions regardless of the access control settings. For example, a printer administrator should be able to manage printer settings irrespective of whether the printer’s security descriptor allows his user account administrative access. Currently Samba supports eight different privileges, which are described in Table 5-15, along with references to the chapter that fully covers each one.

Table 5-15. Samba user privileges

Privilege Description
SeAddUsersPrivilege Add, modify, and delete users, as well as group membership (Chapter 9).
SeBackupPrivilege Not currently used.
SeDiskOperatorPrivilege Create, modify, and remove file shares, as well as modify share ACLs (Chapter 9).
SePrintOperatorPrivilege Create, modify, and remove printers, print drivers, and forms (Chapter 7).
SeMachineAccountPrivilege Add and remove client machines from a Samba domain (Chapter 9).
SeRemoteShutdownPrivilege Issues requests to initiate and abort a shutdown of the Samba server (Chapter 9).
SeRestorePrivilege Set the ownership of a file or directory to an arbitrary user (Chapter 6).
SeTakeOwnershipPrivilege Take possession of a file or directory (Chapter 6).

The first thing that must be done to take advantage of this administration delegation model is to enable the feature in smb.conf:

      enable privileges = yes

Table 5-16 provides a short description of the enable privileges parameter, as well as its current default value.

Table 5-16. User-privilege-related parameters

Parameter Value Description Default Scope
enable privileges boolean

Controls whether smbd supports the assignment and honoring of user rights assignments. 

no a Global

Once this feature is enabled, the primary means of managing privilege assignments on a Samba server is the rpc rights subcommand of the net utility.

It is possible to manipulate user rights assignments with the Windows NT 4.0 User Manager for Domains utility, but only when run from a Windows NT 4.0 client. This specific functionality in usrmgr.exe does not work correctly when run from a Windows 2000 or later client, due to a bug in the application.

{mospagebreak title=The net Tool}

The net tool began as a variation of the net.exe command on Windows. The motivation was to be able to perform simple remote administration tasks, such as adding a user or enumerating the open files on a server. To that end, the tool initially supported three main subcommands: RAP, RPC, and ADS. Each of these network commands has a myriad of additional subcommands. This list has grown to include nonnetwork related activities, as is the case with the groupmap subcommand. Chapter 11 expands on the net command, as we examine some simple scripts that make use of Samba tools. All three of these remote administration protocols share a set of common command-line arguments specifying the server and connection credentials.

When using the commands, first ensure that Samba is running, because the net rpc commands make use of the network to communicate rather than directly accessing any local configuration files.

You can anonymously enumerate the available user privileges on a server by running:

  $ net -S localhost -U% rpc rights list
SeMachineAccountPrivilege  Add machines to domain
SeTakeOwnershipPrivilege  Take ownership of files or other objects
  <remaining output deleted>

The -S option specifies the server to query and the -U option specifies the username to use when making the connection. Like most Samba tools, these tools let you specify the full connection credentials in the -U option: a username followed by a % character and then the password. In this example, both the username and password are left empty.

It may be necessary in some circumstances, such as connecting to a server belonging to Active Directory, to define the domain for a username as well. This can be accom plished using the -W command-line flag. The following example connects to a server as the user ADAdministrator. If no % character is found in the username, net and other Samba client tools prompt for a password.

  $ net -S localhost -U Administrator -W AD rpc rights list
<enter password>

Once you are able to successfully enumerate available privileges, it is time to grant specific privileges to users. The capability to manage user rights assignments is implicitly granted to the root user. It is also implicitly granted to members of the Domain Admins group if the server is participating in a domain either as a domain controller or a member server. For now, this example relies on the presence of a root account that can connect to the server.

In this example, assume that there is a Unix user named lizard and that the server’s name is RAIN. We can grant this user the SeDiskOperatorPrivilege by running:

  $ net -S localhost -U root -W RAIN rpc rights
        grant ‘RAINlizard’ SeDiskOperatorPrivilege
  Password: <enter password for root>  
  Successfully granted rights.

If you receive an error indicating that the named privilege does not exist, ensure that you have spelled the privilege name correctly and that enable privileges = yes is correctly specified in smb.conf.

Privileges can be assigned to any name that can be resolved to a SID. This means that the account being granted a right need not be a local user or group. In fact, a com mon configuration is grant domain groups certain rights on the Samba host in order to leverage the existing domain infrastructure rather than duplicating it locally. (Future chapters expand on this idea.)

It is possible to view specific privilege assignments by using a variant of the net rpc rights list that was discussed earlier. The following command enumerates all accounts stored in Samba’s privilege database (account_policy.tdb) and any rights associated with that user or group:

  $ net -S localhost -U% rpc rights list accounts
BUILTINPrint Operators
  No privileges assigned

This command lists all users and groups stored in Samba’s privilege database. If you prefer to list only the rights assigned to a specific name, you can alternatively run this command:

  $ net -S localhost -U% rpc rights list accounts ‘RAINlizard’ 

Or, if you wish to find all owners of a particular privilege, run:

  $ net -S localhost -U% rpc rights list privileges 

At times it is necessary to remove a privilege assignment from a user or group. The net rpc rights revoke command performs the inverse function to the grant subcom mand. Here the SeDiskOperatorPrivilege previously assigned to lizard is removed:

  $ net -S localhost -U root -W RAIN rpc rights revoke ‘RAINlizard’
Password: <enter password for root>
  Successfully revoked rights.

In all of these examples, it is possible to list multiple privilege names when listing, granting, or revoking rights. Table 5-17 collects the various options to the net rpc rights command covered in this section.

Table 5-17. net rpc rights commands



list[{accounts,privileges} [name]]

Enumerate supported privileges or assigned rights.

grant nameright [right]

Assign a list of user privileges to a user or group.

revoke name right [right]

Remove a list of assigned privileges from a user or group.

{mospagebreak title=Controlling Authorization for File Shares}

We began this chapter discussing authentication, and we now end it with a discussion about authorization. Authorization under Unix relies upon the user’s uid and a list of group gids. Samba can use this same information to perform preliminary access checks to to control whether the user or group should be allowed to modify any files within a share. For example, perhaps you would like to export a set of files as read-only to students but allow modification by teachers. There are several ways to accomplish this goal. The final access granted to a file or directory for a user is the most restrictive permission set allowed after passing the user credentials through the share’s:

  1. Security descriptor
  2. Access controls in the share’s definition in smb.conf
  3. Filesystem permissions

The initial access check is performed by comparing against the share’s security descriptor. These share permissions are maintained separately from the server’s configuration file and are stored by default in /usr/local/samba/var/locks/share_info.tdb. All shares initially have a neutral ACL that grants Everyone full control of the share.

Figure 5-4 shows the share permissions for [public] viewed from the Computer Management MMC plug-in connected to a Samba host. Expand the Systems Tools -> Share Folders -> Share hierarchy to list the available file shares. Finally, select an individual share and right-click to navigate to the Properties menu option. The security tab in the dialog box that appears provides access to the share ACL settings. Note that you will not be able to modify the security descriptor unless you are connected as root or possess the SeDiskOperatorPrivilege .

Figure 5-4.  Share permissions for \RAINpublic

Next, we focus on the category of smb.conf authorization options that make use of a list of names. Consider the admin users option as a first example. This option accepts a list of users or group members that should be mapped to the root account when they access resources on a given share. Assume that we want to allow the users rose and lily to be able to manipulate files regardless of the filesystem permissions. A basic way to achieve this is to add the admin users list to the share definition in smb.conf:

path = /data/docs
read only = no
admin users = rose, lily

When a user connects, Samba determines whether that user is a contained within the list rose, lily. Evaluating user names is straightforward. A single string comparison returns success or failure depending on whether the login names match.

Authorization lists such as admin users can accept group names as well. The next example expands the [documents] share to add the Unix group named staff as a member of the admin users list:

path = /data/docs
read only = no
admin users = rose, lily, +staff

When a name is prefixed by the plus sign ( + ), Samba resolves that name as a Unix group by querying the operating system for its membership. Once the list of user names is expanded, the login name comparison continues until a match is found or until all the members in the list have been checked.

Any files or directories created by a user contained in the admin users list will be owned by root, not the actual user.

In most cases, the + character is all that is needed. There are two other available characters to inform Samba of the properties of a name:

  Attempt to resolve the name as an NIS netgroup,
      and fall back to evaluating it as a Unix group in 
      case of failure.

  Attempt to resolve the name as an NIS netgroup, 
      with no fallback mechanism in the case of failure.

It is very likely that Samba’s support for NIS will be deprecated at some point, so don’t rely upon the @ and & characters unless you actually use netgroups. Doing so prevents you from having to update your smb.conf, should support for descriptive characters other than + be removed.

Other parameters that make use of the user and group list syntax are frequently found in pairs. For example, the valid users and invalid users options allow and restrict specific users or groups from accessing a specific share. Although these parameters are not mutually exclusive, the configuration is much easier to understand when only one is present. If one parameter is defined—for example, valid users=+staff —everyone who does not belong to that list is considered to be invalid and is not allowed access to that share. This is a simple method to either disallow everyone and specify a few exceptions ( valid users ), or to authorize all users and then reject a few particular ones ( invalid users ). If both parameters are defined, a user must not appear in the invalid users list, but must match the valid users list.

Similarly, the read list and write list options provide a means of deviating from the read only setting for a user or group. A share may be marked as read only with the exception of a few users or groups. The following [administration] share is read only for those who do not belong to the pcadmins Unix group:

path = /data/administration
read only = yes
write list = +pcadmins

In a complementary fashion, a share named [documents] is defined here to be modifiable by all users except those in the guest group:

path = /data/documents
read only = no
read list = +guest

Finally, a share can be restricted to a maximum number of simultaneous connections across all user sessions by specifying a nonzero max connections parameter. This approach provides a crude mechanism for metering network software installations. For instance, if you have only 10 licenses for an application, you can install it in a dedicated Samba file share and have the clients run the software from there. To help illustrate the use of the option, the following example configures a share named [cad] that allows only 10 connections at any given time:

comment = CAD software for Engineering Department
path = /data/applications/cad
read only = yes
max connections = 10

Note that this example restricts only the number of connections to the share. It does not track how many users are currently running an application. A user who has the share open in a Windows Explorer window is consuming one of the connections, even without accessing any files contained in the share.

Table 5-18 concludes this chapter with an overview of the authorization parameters discussed in this section. In the next chapter, we examine many more configuration options and advanced capabilities of Samba’s file serving functionality.

Table 5-18. File share authorization-related parameters






admin users

user/group list

List of users or members of a group who are mapped to the rootuser for all access to this share.



invalid users

user/group list

List of users or members of a group who are denied access this share.



max connections


Defines the maximum number of concurrent con-nections to this share across all user sessions. A value of 0 indicates that access should not be restricted.



read list

user/group list

List of users or members of a group who are restricted to read only access to this share.



valid users

user/group list

List of users or members of a group who are granted access to this share, if permitted by the other autho-rization checks as well.



write list

user/group list

List of users or members of a group who are granted write access to this share, if permitted by the other access checks on the share and filesystem permis-sions as well.



* The term security level refers to the capabilities of the SMB/CIFS protocol and the term security mode describes Samba’s various implementations of the SMB/CIFS security levels.

* Details of NTLM and other authentication protocols used by CIFS can be found at Chris Hertel’s site

* Samba 2.2 did support both the LDAP and TDB storage backends. But it was only with the Samba 3.0 releases that developers considered these to be first-class citizens when managing user accounts.

* This is the posixGroup from the original RFC2307 schema and not the auxiliary version defined in the RFC2307bis extensions.

* In any discussion of Unix utilities, it is admittedly hard to remember which password-related options and files are called “password” and which are called “passwd.”

a Future versions of Samba will enable this feature by default. Be sure to check the current smb.conf(5) manpage for your version.

Google+ Comments

Google+ Comments