Configuring the secure file

About the secure file

The secure file defines how BMC Server Automation applications for a client installation and the RSCD agent on a server communicate with each other. In this discussion, a client application can be a Network Shell client, BMC Server Automation Application Server, or Network Shell proxy server that communicates directly with an RSCD agent or repeater.

The secure file for a client application defines parameters that BMC Server Automation applications use to communicate with the RSCD agent on a server. The secure file on the server defines parameters that the RSCD agent uses to communicate with BMC Server Automation applications on clients. The exports, users, and users.local files control user access to servers (see Configuring the exports file and Configuring the users or users.local files).

By default, client and server processes communicate using TCP/IP port 4750 with the server process listening on all configured NIC (Network Interface Card) addresses. The port number can be set with an entry in the Internet services databases (for example, /etc/services ).

For simpler security installations, you need only modify the secure file to establish how data is communicated between clients and servers. Stronger security requires additional modifications to a system. See Security planning for a full description of all the procedures needed to implement security in a BMC Server Automation system.

Always use the secadmin utility to modify the secure file. Using the secadmin utility ensures that the secure file is formatted correctly. For more information, see Using the secadmin utility.

The secure file resides in different locations in Windows and UNIX systems, as described in the following table. On Windows, you can have multiple instances of BMC Server Automation client applications, each with their own secure file. The following table shows how the location of the secure file on Windows varies between the first instance and all subsequent instances.

The following sections provide more information about configuring the secure file.

_{Back to top}

Clients, servers, and the secure file

When a BMC Server Automation application on a client attempts to connect to an RSCD daemon on a server, the application first checks the secure file for a client to see how the connection should be established. If an entry for the target server exists in the secure file, the application checks the secure file to see if and how the connection should be redirected and whether data should be encoded, encrypted, or sent as clear text. If an entry for the remote host is not found, the application searches for an entry called default to determine how the connection to the remote host should be made. (For more on configuring entries in the secure file, see To configure the secure file.) If the secure file does not include an entry for the remote host or a default entry, the attempt to establish a connection is aborted.

TCP is a bi-directional virtual circuit protocol. As such, when a client establishes a connection to an RSCD daemon on a server, that connection is used to both send and receive data.

To determine where to listen for connection requests, the RSCD daemon consults the secure file on the server. It looks for an entry for a host named rscd. If an entry is not found, the daemon listens by default to port 4750 (or as otherwise defined in the Internet services databases). If an rscd entry is found, the software treats it as a special entry used by the RSCD daemon. The rscd entry can specify which port and address to listen to for connection requests and it can specify default communication parameters. (For more information about configuring the rscd entry, see To configure the secure file.) The RSCD daemon can listen on a specified port on all available NICs or a particular NIC (specified using the host= field, as described in Options for the secure file). The RSCD daemon cannot listen to a port on a list of specified NICs. In other words, it can only listen on one NIC or all NICs.

When a client establishes a connection, the RSCD daemon again refers to the secure file to determine what data encoding/encryption it should expect from the client host. The RSCD first checks for an entry for the connecting host. If such an entry exists, the agent uses the connection parameters defined in that entry. If no entry for the connecting host is found, the daemon uses the default values from the rscd entry.

Communication protocol

Protocol 5, the BMC Server Automation default communication protocol, establishes rules for communication between BMC Server Automation clients and Application Servers and the RSCD agent. By default, protocol 5 uses Transport Layer Security (TLS), the successor to SSL, which automatically negotiates the strongest form of encryption that clients and servers can support. BMC Server Automation clients and RSCD agents use the TLS_RSA_WITH_AES_128_CBC_SHA cipher suite. For a description of the capabilities of this suite, see Session layer security.

_{Back to top}

To configure the secure file

When configuring the secure file, you can make three types of entries:

• default
• rscd
• host

Always use the secadmin utility to configure the secure file. The secadmin utility encrypts any keys needed for data encryption and guarantees that the secure file is formatted correctly. For more information, see Using the secadmin utility.

_{Back to top}

Using the secadmin utility

With the secadmin utility, you can create, modify, or delete entries in a secure file. You can also create, modify, or delete default or rscd entries in the secure file. Additionally, the secadmin utility lets you modify entries in the securecert file.

Example

If you are using protocol 5 and you want to specify TLS-style encryption between a client called host1 and three servers called host2, host3, and host4, you would use secadmin to make the following additions to the secure file on host1:

secadmin -a host2 -p 5 -T encryption_only -e tls
secadmin -a host3 -p 5 -T encryption_only -e tls
secadmin -a host4 -p 5 -T encryption_only -e tls

Next, you must use secadmin to modify the secure file on host2, host3, and host4 by entering the following command on each of those servers:

secadmin -m host1 -p 5 -T encryption_only -e tls

If you are using secadmin on a server where Network Shell is not installed, you must include the full path to the secadmin utility when running a secadmin command. By default, you can find secadmin in the following locations:

• UNIX: /opt/bmc/bladelogic/NSH/secadmin
• Windows: C:\Program Files\BMC Software\BladeLogic\RSCD\secadmin

For a complete description of the secadmin utility, see the man page for secadmin.

Options for the secure file

The following table lists the fields that you can include in entries in the secure file.

For each of the listed field options, the Applicability column specifies whether the option applies to RSCD agents, to NSH clients (such as the Network Shell, the BMC Server Automation Console, and the Application Server), or to both RSCD agents and NSH clients. An option's applicability determines the types of entries in which it can be included:

• Options that apply to RSCD agents can be included in the rscd entry in the secure file.
• Options that apply to NSH clients can be included in the default entry or in a host entry.

_{Back to top}

Secure configuration file examples

The following examples serve as sample uses of the fields available in a secure file. To generate entries in a secure file like those shown below, use the secadmin utility. Using the secadmin utility ensures that the secure file is formatted correctly. For more information, see Using the secadmin utility.

• A typical default entry for BMC Server Automation clients: 
  default:port=4750:protocol=5:encryption=tls 
• A subnet in an entry: 
  @192.168.12.13/24:protocol=5:encryption=tls 

• Instructs a Network Shell client to communicate with a Network Shell proxy server using an authentication profile called QAProfile. The authentication profile is stored in the default location for the authentication profile file:

  default:protocol=5:encryption=tls:appserver_protocol=ssoproxy:auth_profile=QAProfile:
  auth_profiles_file=/opt/bmc/bladelogic/NSH/br/authenticationProfiles.xml

• Shows how to use a port other than the default port of 4750. If you use host1 as the client host and host2 as the remote host, the following entry should be in the secure file of host1 
  host2:port=987 
  while the following entry should be in the secure file of host2: 
  host1:port=987 
• Shows how to instruct the RSCD agent to listen on a specific address for client connections: 
  rscd:host=192.168.10.20