Configuring the secure file
This topic explains the purpose of the secure file, describes the available options, and details how to configure it. This topic includes the following sections:
About the secure file
The secure file defines how TrueSight 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, TrueSight 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 TrueSight 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 TrueSight 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 TrueSight 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.
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 TrueSight 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.
Name and location of secure file for first instance of TrueSight Server Automation
Name and location of secure file for additional instances
The following sections provide more information about configuring the secure file.
Clients, servers, and the secure file
When a TrueSight 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 for the following:
- whether the connection should be redirected
- 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
defaultto determine how the connection to the remote host should be made.
- If the secure file does not include an entry for the remote host or a
defaultentry, the attempt to establish a connection is aborted.
(For more information about configuring entries in the secure file, see To configure the secure file.)
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 To configure 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
Protocol 5, the TrueSight Server Automation default communication protocol, establishes rules for communication between TrueSight 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. TrueSight Server Automation clients and RSCD agents use the TLS_RSA_WITH_AES_256_CBC_SHA and SSL_RSA_WITH_3DES_EDE_CBC_SHA cipher suites. For a description of the capabilities of this suite, see Session layer security.
To configure the secure file
When configuring the secure file, you can make three types of entries:
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.
The secure file allows for a special host name called
When you initially install Network Shell, the TrueSight Server Automation consoles, or the RSCD agent, a
When you initially install an RSCD agent on a server, an
|Host|| Host entries in the secure file on a server set connection parameters that define how that server communicates with individual clients. Host entries in the secure file on a client set connection parameters that define how that client communicates with individual servers. You must make corresponding entries in the secure file on both the client and server to establish a connection between client and server.|
To configure host entries in the secure file, create entries that define parameters for a connection with a particular host. Use the following format for each entry:
Using the secadmin utility
secadmin utility, you can create, modify, or delete entries in a secure file. You can also create, modify, or delete
rscd entries in the secure file. Additionally, the
secadmin utility lets you modify entries in the securecert file.
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
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 TrueSight 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.
|NSH client||Specifies the authentication protocol used when communicating with a Network Shell proxy server. For more on Network Shell Proxy Servers, see Setting up a Network Shell proxy server. You can set |
|NSH client||Sets a data compression level. By default, data is not compressed. If you want to use data compression, set |
|NSH client, RSCD agent||Determines the type of data encryption that should be used. Set this field to |
|NSH client, RSCD agent|
Use depends on whether a secure file entry defines the special host name
You can specify the IP address in IPv4 or IPv6 format. However when specifying an IPv6 address, ensure that the server address is enclosed in square brackets.
|RSCD agent||Specifies whether the agent should send TCP keep-alive messages to the other side of a connection. If keep-alive messages are sent, the connecting system notices the death of a connection or a machine crash. If TCP keep-alives are not sent, sessions might hang indefinitely leaving hung processes or threads on the agent. Possible values for this field are yes or no. The default value, if unset, is yes.|
Specifies the frequency at which the client should send a keepalive message to the target server, to ensure that the NSH to RSCD connection remains alive and is not killed due to a connection timeout. This setting is required only on the client side (and not required at the remote target that runs the RSCD Agent). The value must be an integer (the interval length in seconds) or zero (no keepalive messages sent). The default value is zero.
Note: For Windows-based Application Servers, the value that you set for this option will apply to the connection between the NSH client and the RSCD Agent. If the RSCD Agent is behind a SOCKS proxy, the value will apply only to the connection between the Application Server and the SOCKS proxy, and will not apply to the connection between the SOCKS proxy and the RSCD Agent. Note that this is true even if the Windows-based Application Server itself is a SOCKS proxy.
For Unix/Linux-based Application Servers, the value that you set for this option will apply end to end to the connection between the NSH client and the RSCD Agent. Even if the RSCD Agent is behind a SOCKS proxy, or there is an NSH proxy, the value is sent end to end from NSH client to RSCD Agent.
|RSCD agent||Determines the maximum number of times a bad connection is allowed from a source address before the address is locked. A bad connection can happen if encryption is not set up properly or a particular host is not granted access. The address is locked for a period of time as defined by the |
|NSH client, RSCD agent|
When set in the default or host lines, this setting defines the port that NSH and the Application Server will use to communicate to RSCD agents. When set in the rscd line, this setting defines the port that the agent lists on. Also, when using this field, make sure that both the NSH client and RSCD agent are configured to use the same port number.
You must restart the Application Server and the RSCD agent for your change to take effect.
Indicates that the specified target host is running behind a SOCKS proxy. The value for this option is either
After setting this option, you must restart the Application Server for your change to take effect.
|NSH client, RSCD agent||Determines the transport protocol used for communication between TrueSight Server Automation applications and the RSCD agent. Protocol 5, the default protocol, uses the TLS protocol (TLS is the successor to SSL) for communication between client and server.|
|NSH client||Identifies the authentication profile that should be used to provide session credentials to Network Shell when communicating with a Network Shell proxy server. If you need to use multiple Network Shell proxy servers, you can set up a different secure file entry for each profile. Using the BL_AUTH_PROFILE_NAME environment variable, you can override the value defined with this field. For more on Network Shell proxy servers, see Setting up a Network Shell proxy server.|
|NSH client||Provides the Network Shell path to the file containing authentication profile definitions, which are necessary when Network Shell communicates with a Network Shell proxy server. Using the BL_AUTH_PROFILES_FILE, you can override the value defined with this option. For more on Network Shell proxy server, see Setting up a Network Shell proxy server.|
|NSH client||Sets the maximum number of seconds that a client waits when first contacting a remote server before giving up. The default value is 30 seconds. Without this option, the TCP protocol might continue to contact an offline or unavailable server for several minutes before finally giving up and reporting that a server is unavailable. This timeout mechanism is implemented within the TrueSight Server Automation code and does not in any way alter any system wide TCP parameters. If the operating system has an effective TCP timeout less than the value defined here, the OS value takes precedence.|
|NSH client, RSCD agent|
Specifies one of the following values when using protocol 5:
|RSCD agent||Works in conjunction with the |
|RSCD agent||Turns off X11 forwarding. By default this field is set to on and X11 forwarding is enabled for this agent. For more information about X11 forwarding, see Using X11 forwarding to run programs remotely via NSH.|
|RSCD agent||Defines an offset from 6000, and together these values specify the port that the agent binds to for X11 forwarding. By default, X11 forwarding starts at port 6010 (6000 plus an offset of 10). Any new connections afterwards increment the offset by one (that is, 6011, 6012, and so forth).|
(Optional) Sets the Unix process priority for the RSCD listener service. This is applicable for file server RSCD (Unix/Linux only) to handle a high number of concurrent requests. This is not applicable to the RSCD Agent on Windows. The default value for priority is 0. The range of the value is -20 to 19 with -20 being the highest priority for the RSCD process and 19 being the lowest priority for the RSCD process. Increasing the priority (eg, setting it towards -20) will improve the responsiveness of the RSCD agent. This setting requires a restart of the RSCD service to take effect.
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 TrueSight Server Automation clients:
- A subnet in an entry:
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:
- 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:
And the following entry should be in the secure file of host2:
- To instruct the RSCD agent to listen on a specific address for client connections:
- If you have two systems named host2 and host3 running behind a SOCKS Proxy AND the Resolve host name is set on that proxy AND the RSCD on these systems is running on a custom port you should add lines like the below to the secure file on all application servers.
If the entry does not specify the port behind the SOCKS proxy, port 4750 (the standard default) is used.
In a MAS environment, an entry for a host behind a SOCKS proxy must be entered in the secure file on all Application Servers.