Starting version 8.9.03, BMC Server Automation is renamed to TrueSight Server Automation. This space contains information about BMC Server Automation 8.9.02 and previous versions. For TrueSight Server Automation 8.9.03 and later releases, see TrueSight Server Automation 8.9.

Controlling server access with agent ACLs

This topic discusses how you can use agent access control lists (ACLs) to control access to a server. It includes the following sections:

Understanding server access

When you define permissions for a server, you are controlling access to the server within the BMC Server Automation system. The BMC Server Automation Application Server enforces these permissions. However, you can also manage servers using Network Shell and the BLCLI. To completely control access to a server, you must modify configuration files on each server's RSCD agent. If you are using Microsoft Windows user mapping to grant user permissions on Windows servers, see Windows user mapping and agent ACLs.

Several methods exist to control access using agent configuration files. For detailed information about creating the configuration files, see Setting up configuration files.

Typically, you control agent access by letting BMC Server Automation automatically translate the permissions you have defined for a server in the BMC Server Automation Console into a users configuration file on the agent. You accomplish this by running an ACL Push Job on a server, which overwrites the users file for that server's RSCD agent (see Creating or modifying ACL Push Jobs). Before you push agent ACLs to a server by running the ACL Push Job, you can preview the entries to be created in the users file (see Previewing and pushing agent ACLs). When you define permissions for a server while adding the server, you can also preview agent ACLs (see Add New Server - Permissions). After you have pushed ACLs, the users file settings control all incoming connections to that agent.

When BMC Server Automation generates entries for a users file, it creates an entry for each user associated with each role that has access to the server. BMC Server Automation does not generate an entry for disabled users. An entry is formed by pairing a role and a user using the format role:user. In the example users file shown below, DBAdmins is the role and george and betty are users assigned to the DBAdmins role.

In addition to generating role:user entries, BMC Server Automation also creates another type of users file entry for Network Shell users. Because Network Shell does not recognize roles, the RBAC Manager folder asks you specify a role that functions as the default Network Shell role for each user (see User - Role Selection). Using this information, BMC Server Automation generates a users file entry that does not include role information for each user. A users file entry is not generated for disabled users.

For example, in the users file shown above, the users george and betty have their default Network Shell role set to DBAdmins. In addition to the role:user entries for george and betty, BMC Server Automation generates entries for george and betty that are not paired with any role but are based on the same information as the DBAdmins role. These entries are default Network Shell roles, and they let george and betty access the server using Network Shell.

The users file that BMC Server Automation pushes to an agent can also include a nouser entry. Including this entry instructs a server to allow a connection from a user only when that user has been explicitly defined in the users configuration file. BMC Server Automation places a nouser entry in the users file of a particular server if the server property called PUSH_ACL_NO_USERS_FLAG is set to true.

Administrators can create a users.local file on agents to create a set of user permissions that are more fine-grained than is possible with the users file entries that BMC Server Automation automatically generates. For example, with RBAC you cannot specify some users as read only and others as read/write, but you can easily accomplish that by manually editing the users.local file. The RSCD agent reads the users.local file before it reads the users file, and the users.local settings supersede any corresponding settings in the users file. If the users file includes entries that are not superseded, those entries still apply.


BMC recommends adding an entry for RBACAdmins:RBACAdmin and BLAdmins:BLAdmin to the users.local file for every server. Because these roles cannot be deleted, they provide a way to access a server in case you accidentally revoke everyone else's permissions for that server. If you choose to rename the RBACAdmins or BLAdmins roles, the entries you make in the users.local file should reflect those naming decisions.

Windows user mapping and agent ACLs

If you are granting user permissions on Windows servers through Windows user mapping, all permissions on the server are derived from the local or domain user to which a role is mapped.

However, configuration files on a managed server can control other capabilities besides user permissions. Because of that, when you change role or user information, you should always run an ACL Push Job, even to servers where you are using Windows user mapping.

Previewing and pushing agent ACLs

You can preview agent access control lists (ACLs) before pushing them to a server.

You can view the ACLs that BMC Server Automation will write into a users configuration file on the agent of a remote server when you run an ACL Push Job on that server (see Creating or modifying ACL Push Jobs). 

After you preview ACLs, this procedure gives you the option of pushing ACLs immediately to the server. This option provides a quick alternative to pushing agent ACLs by launching an ACL Push Job.

To preview and push agent ACLs

  1. In the Servers folder, select a server.
  2. Right-click and select Administration Task > Agent ACLs from the pop-up menu. 
    A window displays the entries that appear in the users file on that server after you push ACLs to the server.
  3. Do one of the following:
    • To push ACLs to the selected server without running an ACL Push Job, click Push. A dialog box asks you to confirm. Click OK. A progress bar shows the progress of the ACL push. A dialog box announces that the push was successful, or it lists any failures.
    • To create an ACL Push Job to push the ACLs you are previewing to a server, click Schedule Job. The New ACL Push Job wizard opens. For information about using this wizard, see Creating or modifying ACL Push Jobs.
    • To close the window, click Cancel.
Was this page helpful? Yes No Submitting... Thank you


  1. Jim Wilson
    On this page:

    It states:
    The ACL Push Job and Agent ACL Preview resolve the ACLs that are necessary to grant users access to the server object based on the authorizations explicitly associated with the server object and any associated ACL policies, as well as the authorizations and ACL policies associated with any components linked to the server object.

    This Controlling server access with agent ACLs page needs to also mention this factor, else customers can be surprised by what they see in the users file
    May 08, 2017 04:37
  2. Moiz Nalwalla

    Sure, I'll wok on this Jim.

    May 08, 2017 04:39