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 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.

Platform

Name and location of secure file for first instance of BMC Server Automation

Name and location of secure file for additional instances

Solaris
Linux
AIX
HP-UX

/etc/rsc/secure

Not applicable

Windows

<WINDIR>\rsc\secure
For example, <WINDIR> can be \windows or \winnt.

<installDirectoryN>\NSHconf\secure
For example, the default location for the second instance of BMC Server Automation would be C:\Program Files\BMC Software\ BladeLogic2\NSH.

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 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 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  

 


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.

EntryDescription
Default

The secure file allows for a special host name called default. It defines connection parameters for servers that otherwise do not have an entry in the secure file. Creating a default entry is an easy way to define the same communication parameters for multiple servers without having to configure entries for each of those servers.

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 BMC Server Automation consoles, or the RSCD agent, a default entry is automatically created in the secure file.

The default entry:

  • Specifies that the client use protocol 5 and instructs clients and servers to communicate using the TLS protocol for secure communication.
  • Designates the default port as 4750.
  • That is automatically generated in a client's secure file reads as follows:
    default:port=4750:protocol=5:tls_mode=encryption_only:encryption=tls
RSCD

The secure file allows for another special host name called rscd. It defines standard connection parameters that are used for an RSCD agent on a server communicating with clients when those clients are not included in the list of host entries on the server's secure file. Creating an rscd entry is an easy way to define the same communication parameters for all of the servers in your system that are not otherwise configured in the secure file.

An rscd entry in the secure file uses the following format:

rscd:<option1:option2:option3...>

where optionN is a list of colon-separated fields. Each option in the list defines a parameter for communicating with all agents that do not have a host entry specifically defined for them. For a complete list of available options, see Options for secure file.

Note: If you change the RSCD agent port number in the secure file, you must restart both the Application Server as well as the RSCD agent on the system(s) where you changed the secure file for the change to take effect.

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).
<optionN> is a list of colon-separated fields. Each option defines a parameter for communicating with the host (or subnet) named in <hostName>. For a complete list of available options, see Options for secure file.

 

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.

Examples

  • 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 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 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

  • You are using protocol 5 and you want to specify TLS-style encryption between a client called host1 and two servers called host2 and host3, which are located behind a SOCKS proxy. Host2 runs on port 4750 (the default), and host3 runs on port 9999. You use secadmin to make the following additions to the secure file on host1:
    secadmin -a host2 -r 4750 - -T encryption_only -s
    secadmin -a host3 -r 9999 - -T encryption_only -s

    This results in the following entries in the secure file:
    host2:port=4750:protocol=5:tls_mode=encryption_only:encryption=tls:timeout=30:client_keepalive_time=0:behind_socks=yes
    host3:port=9999:protocol=5:tls_mode=encryption_only:encryption=tls:timeout=30:client_keepalive_time=0:behind_socks=yes

    If you later decide to remove host3, you would use the following secadmin command:
    secadmin -d host3 -s

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.
OptionApplicabilityDescription
appserver_protocol=<protocol>NSH clientSpecifies 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 clientSets 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 agentDetermines the type of data encryption that should be used. Set this field to tls, which specifies that BMC 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:

  • When applied to an rscd entry, the host= field determines the address to which the agent should listen for client connections. If a system has a single NIC card, you do not have to set this field because the agent automatically listens on the default system NIC card (address). The host= field should only be used for systems with multiple NIC cards (real or virtual) so you can select the NIC (address) to which the RSCD agent should listen.
  • When applied to a non-rscd entry, the host= field can be used to redirect data between hosts. If the remote daemon to which the data is being sent is not another RSCD daemon, then it is the responsibility of the remote daemon to forward the data to an RSCD daemon and also return any data it might return.

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 agentSpecifies 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).

Note: Due to an issue in the keepalive mechanism on Windows-based Application Servers (see defect QM001887054), do not use this option as your default for communication with all target servers. Use it only with small numbers of targets and relatively low levels of job workload.
lock=<value>RSCD agentDetermines 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.
port=<value>NSH client, RSCD agent

Redirects data to a port other than the default port of 4750. On most UNIX systems, access to port numbers under 1024 requires root permissions. When selecting an alternate port number, make sure it does not conflict with some other existing service. Also, when using this field, make sure that both the client and server machines are configured to use the same port number.

For your change in the port value to take effect on an RSCD agent, you must restart the Application Server.



protocol=<value>NSH client, RSCD agentDetermines the transport protocol used for communication between BMC 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 clientIdentifies 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.
auth_profiles_file=<filename>NSH clientProvides 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 clientSets 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 BMC 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:

  • encryption_only — Use the TLS protocol to autonegotiate an encryption type (that is, a cipher) and then use that cipher to communicate. Client-side authentication or certificates are not required.
  • encryption_and_auth — Use TLS for encryption and client-side authentication. This option requires a certificate. For more on certificates, see Implementing security - Application Server to agents or repeaters.
unlock=<value>RSCD agentWorks 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 agentTurns 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 agentDefines 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).

NEW IN 8.9.02priority=<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.

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
  • 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
Was this page helpful? Yes No Submitting... Thank you

Comments