Configuration files overview

About the configuration files

BMC Server Automation provides the following configuration files:

• exports
• users
• users.local
• secure
• securecert

The exports, users, users.local, secure, and securecert files reside on each server (that is, each machine where an RSCD agent is installed). The secure and securecert files are also installed for each client installation, even if there are multiple client installations on the same machine. The secure files on both the client and server configure how clients communicate with servers.

The configuration files function as follows:

• exports — Sets access permissions for client machines that communicate with a server. With the exports file you can also establish global user permissions.
• users and users.local — Set access permissions for individual users that communicate with a server. Typically, the values specified in the users file are automatically generated to implement decisions made in RBAC. (For more information about RBAC, see Managing access.) You can use the users.local file to override any permissions defined in the users file. Permissions set in either the users and users.local files override any global user permissions defined in the exports file.
• secure — Sets communication parameters that define how client and server machines communicate. RSCD agents, Application Servers, and client installations each have their own secure file. (On Windows, a single machine can have multiple client installations.) A client's secure file specifies how the client communicates with agents. A server's secure file specifies how an agent communicates with clients. An Application Server secure file specifies how the Application Server communicates with agents and how the file server (typically created on the same host as the Application Server) communicates with clients. The secure file also determines whether a Network Shell client communicates with servers using a Network Shell proxy server. A utility called secadmin allows you to configure the secure file on a particular machine. Although you can edit the secure file manually, BMC recommends that you always use secadmin.
• securecert — Stores passphrases used to encrypt the private keys for X.509 certificates. Strong security for communication requires X.509 certificates. Storing passphrases lets BMC Server Automation access private keys without any need for user interaction.

The following graphic illustrates how the secure, exports, and users configuration files work together to control access to a server. 

User privilege mapping and Microsoft Windows user mapping

When a client connects to a server, the client user can be granted permissions on the server using two approaches: through configuration files on the agent (a process called user privilege mapping) or through Windows user mapping.

In BMC Server Automation, the standard approach to granting user permission on managed servers is user privilege mapping. It uses a combination of the exports, users, and users.local configuration files. Together, these files define what permissions apply during the connection. This approach should always be used in situations when a user:

• Is accessing any UNIX server.
• Is accessing a Windows server and the user's role is not mapped to a Windows user through an automation principal.
• Runs a Network Shell client to connect directly to a server.
• Is using a Network Shell client to connect to servers using a stand-alone Network Shell proxy server.
• Is running a Network Shell script defined to use the first and second script types and the appserver_protocol setting in the secure file is not set to ssoproxy. For more information about configuring clients to use a Network Shell proxy server, see Setting up a Network Shell client to run in proxy mode.

The alternative to user privilege mapping is to implement Windows user mapping. Using this technique, you can grant permissions to roles that are mapped to local or domain users who are authorized for a Windows server. For information about implementing Windows user mapping, see Windows user mapping and agent ACLs.

When you are using Windows user mapping to grant permissions to roles, you must still create entries for the users, users.local, or exports files. The information in these entries defines whether users can access a server. Any user mapping information in these entries is ignored for roles that employ Windows user mapping through automation principals. Consequently, even if you are using Windows user mapping, you should still push agent ACLs to servers when you add or modify user or role information in the BMC Server Automation Console.

Disabling user privilege mapping

BMC Server Automation provides a mechanism for disabling user privilege mapping on Windows servers. For more information, see the man page for the chapw command.

Subnet designations in configuration files

When designating a host in the configuration files, you can use a resolvable host name, an IP address, or a subnet. A subnet represents a range of IP addresses. In the configuration files, a subnet designation uses the following format:

@<IP address or hostname>/mask

The @ symbol indicates that a subnet is being defined. After the IP address or host name, provide the number of bits in the mask. For example, a subnet with a subnet mask of 255.255.255.0 might look like the following:

@192.168.10.0/24

The following are sample subnet mask definitions:

255.255.255.000 @192.168.100.0/24
255.255.255.128 @192.168.100.129/25
255.255.255.192 @192.168.100.193/26
255.255.255.224 @192.168.100.225/27
255.255.255.240 @192.168.100.241/28
255.255.255.248 @192.168.100.249/29

How BMC Server Automation grants access to RSCD agents

When a client contacts an RSCD agent, BMC Server Automation uses the following algorithm to determine whether a user has permissions for accessing the agent:

1. Every client installation (on Windows there can be multiple clients) and the RSCD agent each have their own secure file.
   • First, the client reads its secure file to determine whether it includes an entry for a particular server.
   • If an entry for that server exists, the client uses the information in the entry to establish a connection with the server.
   • Then, the RSCD agent on the server reads its secure file to determine if it has an entry for the incoming client.
   • If there is no entry for that client in the secure file of the server, access to the agent is denied.
   • If there is an entry and the communication parameters in the secure file on the server match those in the secure file on the client, a connection is established. 
     Depending on the type of authentication and encryption specified in the secure file, additional measures might be required before a connection can be successfully established between clients and servers. For a description of how to set up communication security for a BMC Server Automation system, see Administering security. For more information about using on the secure file, see Configuring the secure file.
2. Assuming the conditions described below are satisfied, if you are using Windows user mapping, the incoming role is granted the permissions of a local or domain user on the server and the process if complete. If any of the following conditions are not satisfied, the algorithm continues to step 3.
   • The agent being contacted must be running on a Windows server.
   • The agent being contacted must be running on a server that has already been added to the BMC Server Automation system.
   • The agent must be running BMC Server Automation 8.1 or later.
   • A Network Shell client must be communicating through a Network Shell proxy server. To take advantage of Windows user mapping, Network Shell cannot contact an agent directly or communicate through a stand-alone Network Shell proxy server.
   • Any job acting on a target server must be running in an Application Server environment that meets the following criteria:
     • The Application Server must be running a Network Shell Proxy Service or the ProxyServiceURL value in the Application Server profile must point to a valid Network Shell proxy server.
     • The secure file on the Application Server must be defined so the appserver_protocol option is set to ssoproxy.
3.  After a connection is established between the client and server, the system checks the exports configuration file, where the user= field can map users connecting from specified machines to a particular user on the server. For example, with the user= field, you can map users to root on UNIX systems or Administrator on Windows. 
   On Windows, incoming users can only be mapped to local users. On Windows domain controllers, however, all users are domain users and therefore the mapping will be to a domain user, and the syntax of the mapping entry remains the same: map=WindowsUser and not map=domain\WindowsUser.
   If a role is mapped to a Windows user through an automation principal, the exports file produces no user mapping. For more about the exports file, see Configuring the exports file.
4. The system checks the users.local and users configuration files to determine if these files include any map= entries that supersede definitions set in the exports file. Using the map= field, you can map a user on a client to a user on a server. Typically, the users file is used to implement the permissions that are defined and granted to users on a system-wide basis through RBAC Management. The users.local file is used for granting user permissions on a per-agent basis rather than granting system-wide user privileges. If the same users have entries in both users.local and users, entries in the users.local file take precedence. 
   If a role is mapped to a Windows user through an automation principal, the users.local and users files produce no user mapping. For more on the users and users.local files, see Configuring the users or users.local files.
5.  If there is no user mapping defined in the exports, users.local, or users files, the system attempts to match the user ID of the incoming user to a user ID defined on the server where the RSCD agent is installed. If there is a match, the user is assigned that user's permissions. 
   Note that, by default, user "root" on a UNIX client is not allowed to map to its equivalent user "root" on a UNIX server. Similarly, on Windows, any client user found to be a member of the Administrators group cannot be mapped by default to an equivalent user on the server.
6. If none of the previous steps succeed, the system maps the incoming user to a default user. On UNIX systems, users are granted the permissions of user "nobody." On Windows systems, if the role is not mapped to an automation principal, users are granted the permissions of user "Anonymous."
   • On UNIX, users coming in as root are, by default, mapped to nobody unless a corresponding entry for the root= field is found. If a root= field is found, then root equivalence is allowed. Similarly, on Windows, if an incoming user is not mapped to an automation principal and that user is a member of the Administrators group, then that user is, by default, mapped to Anonymous unless a corresponding entry for the root= field is found. 
     In UNIX systems, you can use the anon= field to specify how to deal with anonymous users, including rejecting them with anon=-1. The anon= field is not supported for Windows. Also, on Windows, be aware that the validusers= option is treated the same as the allowed= option.
   • On Windows, if you are not using Windows user mapping, a mapping exists in the exports or users file, and the user that is being mapped to does not exist, access to the agent is denied. For example, if an entry in the users file says 
     betty map=WindowsUser 
     then any user named betty that tries to make a connection to this machine is mapped to the local user named WindowsUser. If there is no user named WindowsUser, access is denied.