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.
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 default to 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 default entry, 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 rscd entry.
Communication protocol
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:
- 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.
Entry | Description |
|---|---|
Default | The secure file allows for a special host name called default. It defines connection parameters used by the NSH client and Application Server that otherwise do not have an entry in the in the secure file. A default entry in the secure file uses the following format: default:<option1:option2:option3...> where optionN is a list of colon-separated fields. Each option in the list defines a parameter for communicating with all servers that do not have a host entry specifically defined for them. For a list of options, see Options for secure file. When you initially install Network Shell, the TrueSight Server Automation consoles, or the RSCD agent, a default entry is automatically created in the secure file. The default entry:
|
RSCD | The rscd entry in the secure file is used to configure the RSCD agent on the system. It provides parameters that define how the RSCD agent operates on the system. An rscd entry in the secure file uses the following format: rscd:<option1:option2:option3...> where optionN is a list of colon-separated fields. For a complete list of available options, see Options for secure file. When you initially install an RSCD agent on a server, an rscd entry is automatically created in the secure file. The rscd entry specifies that the RSCD agent use protocol 5 and instructs clients and servers to communicate using the TLS protocol for secure communication. The rscd entry also designates the default port as 4750. The rscd entry that is automatically generated in the secure file on a server reads as follows: rscd:port=4750:protocol=5:tls_mode=encryption_only:encryption=tls |
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: <hostName>:<option1:option2:option3...> where, <hostName> is the host with which the client or server is communicating. <hostName> can be a resolvable host name, IP address, or subnet designation. Subnet designations are used to define a range of addresses (see Subnet designations in configuration files). |
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.
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 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.
Option | Applicability | Description |
|---|---|---|
appserver_protocol=<protocol> | 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 <protocol> to ssoproxy, which specifies that single sign-on functionality should be used when communicating with the Network Shell proxy server. ssoproxy is the default value for appserver_protocol. |
compression=<value> | NSH client | Sets a data compression level. By default, data is not compressed. If you want to use data compression, set <value> to a number between 1 and 9, where a greater number calls for better compression. Be aware, however, that better compression is more CPU intensive. Typically you should use compression when communicating through a thin pipe. In a LAN environment the overhead required for compressing and uncompressing data is usually greater than the time saved transferring compressed data. |
encryption=<type> | NSH client, RSCD agent | Determines the type of data encryption that should be used. Set this field to tls, which specifies that TrueSight Server Automation should automatically negotiate an encryption method (usually AES). |
host=<value> | NSH client, RSCD agent | Use depends on whether a secure file entry defines the special host name rscd:
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. |
keepalive=<value> | 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. |
client_keepalive_time=<value in seconds> | NSH client | 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. |
lock=<value> | 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 unlock= field (see below). <value> should be a non-zero positive number. |
{{id name="Configuringthesecurefile-port"/}}port=<value> | 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. |
behind_socks=<value> | NSH client | Indicates that the specified target host is running behind a SOCKS proxy. The value for this option is either yes or no, with a default of no. This option is relevant only for host entries. This option is required when all of the following three conditions are met: you have a RSCD agent behind a SOCKS Proxy, the RSCD agent listens on a non-default port (not 4750), and the Resolve host name option is set to true on the SOCKS proxy the RSCD agent is behind. After setting this option, you must restart the Application Server for your change to take effect. |
protocol=<value> | 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. |
auth_profile=<profile> | 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. 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. |
auth_profiles_file=<filename> | 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. |
timeout=<secs> | 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. |
tls_mode=<value> | NSH client, RSCD agent | Specifies one of the following values when using protocol 5:
|
unlock=<value> | RSCD agent | Works in conjunction with the lock= field, which allows you to lock out IP addresses that repeatedly fail to connect to the (RSCD agent) server. These failures are limited to encryption misconfigurations and host authorization errors. With the unlock= field, you can specify how many minutes the IP address should be locked before allowing connection attempts to resume. If <value> is a negative number, the IP address is locked until the RSCD agent is restarted. The default value for unlock= is 1 minute. |
x11_fwd=<on | off> | 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. |
x11_port_offset=<value> | 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). |
{{status colour="Green" title="New in 8.9.02"/}} priority=<value> | RSCD agent | (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:
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- 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
And the following entry should be in the secure file of host2:
host1:port=987 - To instruct the RSCD agent to listen on a specific address for client connections:
rscd:host=192.168.10.20
- 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.
host2:port=5750:behind_socks=yes:protocol=5:tls_mode=encryption_only:encryption=tls
host3:port=9999:behind_socks=yes:protocol=5:tls_mode=encryption_only:encryption=tls
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.