How NSH connects with targets

Depending on how NSH is launched and from where it is launched, you might receive different results when using NSH to connect to an RSCD agent. This topic discusses several common methods for launching NSH and analyzes how the different connection methods work.

Method 1: Launching NSH through the BMC Server Automation Console

To launch NSH through the BMC Server Automation Console on your workstation, right-click the relevant server objects, and select the NSH Here custom command.

The following table analyzes the setup requirements and connection specifications of this method:

DetailsNSH proxy enabledWithout NSH proxy
Setup requirements
  •  The client's secure file must contain the appserver_protocol=ssoproxy entry in the default line.
  • When logging on to the BMC Server Automation Console, Save credential for this session must be selected, so that the session credential is cached.
  • The auth_profile setting in the secure file must match the profile used to log on to the Console. Alternatively the BL_AUTH_PROFILE_NAME environment variable can be set for the user's OS logon session.
  •  The client's secure file does NOT contain the appserver_protocol=ssoproxy entry. 
  • When logging on to the BMC Server Automation Console, Save credential for this session is NOT selected.
  • The client's secure file does NOT contain the auth_profile setting.
What credentials are used?

The credentials stored in the %APPDATA%\BladeLogic\bl_sesscc or $HOME/.bladelogic/bl_sesscc file. These credentials were stored in the session credential cache during logon.

The credentials used to start the Console are set as environment variables in the created session — NSH_ROLE_NAME, NSH_USER_NAME, and BL_RBAC_ROLE. These environment variables are used to establish the BMC Server Automation credentials.

How is the connection made?

NSH on the client makes a connection to the NSH Proxy URL stored in the BLSSO token, and the NSH proxy (an application server) makes a connection to the RSCD agent.

The NSH client establishes a connection directly with the target server.

Where is the activity logged?
  • In the appserver.log of the NSH proxy, you will see a message that indicates the user, role, client IP address, and target server. For example:
    [24 Jan 2017 15:26:12,460] [Nsh-Proxy-Thread-5] [INFO] [BLAdmin:BLAdmins:192.168.52.219] [BLSSOPROXY]
    Connecting to blapp.local


  • In the rscd.log on the target server that you selected, you will see a message that indicates the Application Server IP address, role, user, and command run. For example:
    3b3f8c4b5113c6f94180 0000000002 01/24/17 15:28:51.044 INFO
    rscd - ::ffff:192.168.52.203 4149 0/0 (BLAdmins:BLAdmin): nsh: nsh -D //blapp.local
  • Nothing is logged in appserver.log, since the connection is a direct connection to the target. 
  • In the rscd.log on the target server, you will see a message with information about a direct connection from the NSH client, including the role and user name. For example: 

    d46edee109c53d6e1baa 0000000003 01/24/17 15:31:16.775 INFO rscd - ::ffff:192.168.52.219 4165 0/0 (BLAdmins:BLAdmin): nsh: nsh -D //blapp.local
What if a SOCKS proxy is used for the target server?

The NSH client will connect to the NSH proxy and the NSH proxy (application server) will resolve the network routing rules that may apply to the target.

NSH Here will allow the network routing rule to be resolved. The connection will then come from the SOCKS proxy and not the local client.

Possible errors
  • If the session credential was not cached during logon to the Console, the NSH Here window will open and close quickly. You might notice an error such as "SSO Error: No credentials in credential cache file" or "Could not find a credential in cache file <cache file> that matches the current authentication profile."
  • If the Application Server does not return an NSH proxy URL, you will receive a message such as "Cannot find proxy service URL because <reason>." In this case you need to configure the Application Server to either function as an NSH proxy or to hand out an NSH proxy URL to an NSH proxy.

If the workstation cannot communicate with the target server on TCP port 4750, the NSH Here window will open and close quickly. This could be due to network access issues or because the exports file on the target prevents access from the workstation.

Method 2: Launching NSH through a command line on the Application Server host

Through a command line on the Application Server host, you execute NSH and change directory (cd) to a target server.

The following table analyzes the setup requirements and connection specifications of this method:

DetailsNSH proxy enabledWithout NSH proxy
Setup requirements
  • To establish credentials, blcred must be run. 
  •  The client's secure file must contain the appserver_protocol=ssoproxy entry in the default line. 
  • When logging on to the BMC Server Automation Console, Save credential for this session must be selected, so that the session credential is cached.  
  • The auth_profile setting in the secure file must match the profile used to log on to the Console. Alternatively the BL_AUTH_PROFILE_NAME environment variable can be set for the user's OS logon session.
  • The client's secure file does NOT contain the appserver_protocol=ssoproxy entry. 
  • When logging on to the BMC Server Automation Console, Save credential for this session is NOT selected.
  • The client's secure file does NOT contain the auth_profile setting.
What credentials are used?

The credentials stored in the %APPDATA%\BladeLogic\bl_sesscc or $HOME/.bladelogic/bl_sesscc file. These credentials were stored in the session credential cache during logon.

NSH without the NSH proxy cannot use the BLSSO token. Therefore, the OS user name that was used to start NSH is sent over to the target. Unless there is a mapping entry for the OS user name on the target, you will receive the error messsage "No authorization to access host." This error is expected because the mappings should be for Server Automation role:user names.  However, this does indicate that the NSH client is able to connect to the RSCD agent.

How is the connection made?

NSH on the client makes a connection to the NSH Proxy URL stored in the BLSSO token, and the NSH proxy (an application server) makes a connection to the RSCD agent.

The name passed to the nsh command must match the server object name registered in BMC Server Automation. For example, if you have server1.example.com registered in BMC Server Automation, you must use the following NSH command for the NSH proxy to connect to the target:
agentinfo server1.example.com

The NSH client establishes a connection directly with the target server.

Where is the activity logged?
  • In the appserver.log of the NSH proxy, you will see a message that indicates the user, role, IP address of the Application Server (which serves as the NSH client), and target server. For example:
    [24 Jan 2017 15:26:12,460] [Nsh-Proxy-Thread-5] [INFO] [BLAdmin:BLAdmins:192.168.52.219] [BLSSOPROXY]
    Connecting to blapp.local
  • In the rscd.log on the target server that you selected, you will see a message that indicates the Application Server IP address, role, user, and command run. For example:
    3b3f8c4b5113c6f94180 0000000002 01/24/17 15:28:51.044 INFO
    rscd - ::ffff:192.168.52.203 4149 0/0 (BLAdmins:BLAdmin): nsh: nsh -D //blapp.local

In the rscd.log on the target server, you will see a message such as the following: 
 

464e5c2a971b36154744 0000000007 01/24/17 15:38:58.202 INFO rscd - ::ffff:192.168.52.203 4273 0/0 (root): agentinfo: agentinfo blapp.local

This message shows that the connection is established as root, because the NSH client was started as root and was mapped to root (0/0) by the RSCD agent based on the exports setting.

What if a SOCKS proxy is used for the target server?

The NSH client will connect to the NSH proxy and the NSH proxy (application server) will resolve the network routing rules that may apply to the target.

 Without the connection through the Application Server to resolve the network routing rule, the NSH client will be unable to communicate with the target.

Possible errors
  • If the session credential was not cached during logon to the Console, an error such as the following is displayed in the Console: "SSO Error: No credentials in credential cache file" or "Could not find a credential in cache file <cache file> that matches the current authentication profile."
  • If the Application Server does not return an NSH proxy URL, you will receive a message such as "Cannot find proxy service URL because <reason>." In this case you need to configure the Application Server to either function as an NSH proxy or to hand out an NSH proxy URL to an NSH proxy.

 The Application Server should be able to connect to the target. However, since there are no BMC Server Automation credentials available, the connection will be denied without a mapping entry. This is typically the desired situation.

Method 3: Launching NSH through a command line on the workstation

Through a command line on the workstation where the BMC Server Automation Console is installed, you execute NSH and change directory (cd) to a target server.

The following table analyzes the setup requirements and connection specifications of this method:

DetailsNSH proxy enabledWithout NSH proxy
Setup requirements
  • To establish credentials, blcred must be run.
     
  • The client's secure file must contain the appserver_protocol=ssoproxy entry in the default line. 
  • When logging on to the BMC Server Automation Console, Save credential for this session must be selected, so that the session credential is cached.  
  • The auth_profile setting in the secure file must match the profile used to log on to the Console. Alternatively the BL_AUTH_PROFILE_NAME environment variable can be set for the user's OS logon session.
  •  The client's secure file does NOT contain the appserver_protocol=ssoproxy entry. 
  • When logging on to the BMC Server Automation Console, Save credential for this session is NOT selected.
  • The client's secure file does NOT contain the auth_profile setting.
What credentials are used?

The credentials stored in the %APPDATA%\BladeLogic\bl_sesscc or $HOME/.bladelogic/bl_sesscc file. These credentials were stored in the session credential cache during logon.

NSH without the NSH proxy cannot use the BLSSO token. Therefore, the OS user name that was used to start NSH is sent over to the target. Unless there is a mapping entry for the OS user name on the target, you will receive the error messsage "No authorization to access host." This error is expected because the mappings should be for Server Automation role:user names.  However, this does indicate that the NSH client is able to connect to the RSCD agent.

How is the connection made?

NSH on the client makes a connection to the NSH Proxy URL stored in the BLSSO token, and the NSH proxy (an application server) makes a connection to the RSCD agent.

The name passed to the nsh command must match the server object name registered in BMC Server Automation. For example, if you have server1.example.com registered in BMC Server Automation, you must use the following NSH command for the NSH proxy to connect to the target:
agentinfo server1.example.com

The NSH client establishes a connection directly with the target server.

Where is the activity logged?
  • In the appserver.log of the NSH proxy, you will see a message that indicates the user, role, client IP address, and target server. For example:
    [24 Jan 2017 15:26:12,460] [Nsh-Proxy-Thread-5] [INFO] [BLAdmin:BLAdmins:192.168.52.219] [BLSSOPROXY]
    Connecting to blapp.local


  • In the rscd.log on the target server that you selected, you will see a message that indicates the Application Server IP address, role, user, and command run. For example:
    3b3f8c4b5113c6f94180 0000000002 01/24/17 15:28:51.044 INFO
    rscd - ::ffff:192.168.52.203 4149 0/0 (BLAdmins:BLAdmin): nsh: nsh -D //blapp.local

In the rscd.log on the target server, you will see a message such as the following: 
 

464e5c2a971b36154744 0000000007 01/24/17 15:38:58.202 INFO rscd - ::ffff:192.168.52.203 4273 0/0 (root): agentinfo: agentinfo blapp.local

This message shows that the connection is established as root, because the NSH client was started as root and was mapped to root (0/0) by the RSCD agent based on the exports setting.

The incoming IP is that of the NSH client (the workstation IP) and the user name sent is whatever name was used to log on to the workstation.

What if a SOCKS proxy is used for the target server?

The NSH client will connect to the NSH proxy and the NSH proxy (application server) will resolve the network routing rules that may apply to the target.

 Without the connection through the Application Server to resolve the network routing rule, the NSH client will be unable to communicate with the target.

Possible errors
  • If the session credential was not cached during logon to the Console, an error such as the following is displayed in the Console: "SSO Error: No credentials in credential cache file" or "Could not find a credential in cache file <cache file> that matches the current authentication profile."
  • If the Application Server does not return an NSH proxy URL, you will receive a message such as "Cannot find proxy service URL because <reason>." In this case you need to configure the Application Server to either function as an NSH proxy or to hand out an NSH proxy URL to an NSH proxy.
  • If the workstation cannot communicate with the target server on TCP port 4750, the NSH Here window will open and close quickly. This could be due to network access issues or because the exports file on the target prevents access from the workstation. 
  • Since there are no BMC Server Automation credentials available, the connection will be denied without a mapping entry. This is typically the desired situation.

Method 4: Submitting an NSH script

You submit an NSH Script Job to perform actions against the same target server.

The following table analyzes the setup requirements and connection specifications of this method:

DetailsNSH proxy enabledWithout NSH proxy
Setup requirements

 The secure file on the Application Server must contain the appserver_protocol=ssoproxy entry in the default line.

 The secure file on the Application Server does NOT contain the appserver_protocol=ssoproxy entry. 

What credentials are used?

The CLI_SSO_CREDS environment variable is set with the RBAC role:user that runs the job. The credentials from the environment variable override anything set in the secure file.

The application server provides the credentials of the role:user running the job.

How is the connection made?

The BLSSO token generated by the Application Server uses the value of the ProxyServiceURLs setting from the Application Server instance that runs the WorkItemThread for the job for the particular target to determine what NSH proxy to connect to. If the setting is blank and the instance has a ProxySvcPort set, it will generate a ProxyServiceURL that points to itself.

The Application Server that runs the job makes a direct connection to the target server.

Where is the activity logged?
  • In the appserver.log of the NSH proxy, you will see a message that indicates the user, role, client IP address, and target server. For example:
    [24 Jan 2017 15:26:12,460] [Nsh-Proxy-Thread-5] [INFO] [BLAdmin:BLAdmins:192.168.52.219] [BLSSOPROXY]
    Connecting to blapp.local


  • In the rscd.log on the target server that you selected, you will see a message that indicates the Application Server IP address, role, user, and command run. For example:
    3b3f8c4b5113c6f94180 0000000002 01/24/17 15:28:51.044 INFO
    rscd - ::ffff:192.168.52.203 4149 0/0 (BLAdmins:BLAdmin): nsh: nsh -D //blapp.local

In the rscd.log on the target, a message shows that the connection comes from the Application Server and indicates the role and user name that ran the job.


What if a SOCKS proxy is used for the target server?

The NSH client will connect to the NSH proxy and the NSH proxy (application server) will resolve the network routing rules that may apply to the target.

The Application Server will set a BLSSOPROXY environment variable that will indicate what proxy should be used to communicate with the target.

Possible errors
  • If the ProxySvcPort is not set, the Job Run Log will show errors about being unable to connect to the NSH proxy.  
  • If the NSH proxy cannot handle the number of connections needed by the Job, the Job Run Log will show errors about the NSH proxy not being available.

 Typically, the only issues encountered here are with network connectivity to the target.

Additional notes

  • You do not need to use an NSH proxy for jobs when using SOCKS.  The only reason to do so is if you you are running a script and it needs to copy files between servers in different proxy zones. For example, an extended object needs to be copied from the file server or along the following path of servers: SOCKS 1 > Server 1 > SOCKS 2 > Server 2.  For the case of a file server, if the SOCKS proxy can talk to the file server on port 4750, you should not need an NSH proxy.
  • You can enable the proxy (or any other setting) for specific servers in the secure file. Instead of default, specify hostname:port=xxx:etc.
  • The appserver_protocol is only set on the default line (or host override line), not on the rscd line
  • If you want to use an Automation Principal for RSCD access (and not use an Agent Installer Job), NSH must use an NSH proxy.
  • The server name that you provide to NSH must match what is registered in BMC Server Automation, to ensure that the NSH proxy can be used to talk to the target.
  • There is no reason to have a default line on an RSCD agent. Therefore, the NSH proxy configuration is done on the NSH client and not on the RSCD agent.
Was this page helpful? Yes No Submitting... Thank you

Comments