ssh-broker-ctl

ssh-broker-ctl — SSH Tectia Connection Broker control utility

Synopsis

ssh-broker-ctl command
[options...]

	Note
	The information presented here is also valid for the ssh-socks-proxy-ctl command. Running ssh-socks-proxy-ctl is otherwise equal to running ssh-broker-ctl, but the command controls the ssh-socks-proxy process instead of the ssh-broker-g3 process. ssh-socks-proxy-ctl locates automatically the Connection Broker address that the ssh-socks-proxy process is using.

Description

ssh-broker-ctl is a control utility for Connection Broker (ssh-broker-g3). It can be used, for example, to view the status of Connection Broker, to reconfigure or stop the Connection Broker, or to load private keys to memory.

Options

The following general options are available:

-a, --broker-address ADDRESS

Defines an address to a separate SSH Tectia Connection Broker process to which a connection is made.

The same effect can be achieved by defining a Connection Broker address with environment variable SSH_SECSH_BROKER.

Tip

	Tip
If you are running ssh-broker-ctl using a userID other than that of the ssh-broker-g3 process owner, the `-a` option must be given so that ssh-broker-ctl knows where to connect. In this case, you must also run ssh-broker-ctl as a privileged user (root). For example, when user `SSHBRKR` owns the ssh-broker-g3 process, run the ssh-broker-ctl with commands: # ssh-broker-ctl -a /tmp/ssh-SSHBRKR/ssh-broker status -s # ssh-broker-ctl -a /tmp/ssh-SSHBRKR/ssh-broker status --pid # ssh-broker-ctl -a /tmp/ssh-SSHBRKR/ssh-broker list-connections

If you are running ssh-broker-ctl using a userID other than that of the ssh-broker-g3 process owner, the -a option must be given so that ssh-broker-ctl knows where to connect. In this case, you must also run ssh-broker-ctl as a privileged user (root).

For example, when user SSHBRKR owns the ssh-broker-g3 process, run the ssh-broker-ctl with commands:

# ssh-broker-ctl -a /tmp/ssh-SSHBRKR/ssh-broker status -s
# ssh-broker-ctl -a /tmp/ssh-SSHBRKR/ssh-broker status --pid
# ssh-broker-ctl -a /tmp/ssh-SSHBRKR/ssh-broker list-connections

-D, --debug LEVEL

Defines the debug level.

-e, --charset=CS

Defines the character set to be used in the output. The supported character sets are utf8, iso-8895-1, latin1, iso-8859-15, latin9, and ascii.

-q, --quiet

Defines that little or no output is to be displayed, depending on the command.

-s, --short

Defines that a shorter, more machine readable, output format is to be used.

--time-format=FMT

Defines the time format to be used in the output. The default depends on the system locale settings.

-v, --verbose

Defines that more information, if available, is to be output.

-V, --version

Prints the version string.

-w, --wide

Defines that the output will not not be truncated, even if it means long lines.

-h, --help

Displays a context-sensitive help text on command-line options. Help is available also on specific commands. For example, to get help on the status command, run:

ssh-broker-ctl status --help

Commands

ssh-broker-ctl accepts the following commands:

add-key

Adds a new private key.

close-channel channel-id ...

Closes the defined channel. You can also enter multiple channel-IDs to close several channels.

close-connection connection-id ...

Closes the defined connection. You can also enter multiple connection-IDs to close several connections.

connection-status [--show-channels] [--write-hostkey=FILE] connection-ID

Displays a detailed connection status for the connection ID (the numeric identifier shown by command list-connections).

Options:

--show-channels: Displays channel information.
--write-hostkey=FILE: Writes the host key (public-key or x509 certificate) to the defined file.

debug [--append] [--clear] [--log-file=FILE] [--monitor] [debug-level]

Sets the Connection Broker debug level to the defined level. If no debug-level parameter is given here, the current debug level is not changed.

Options:

--append: Opens the log file in append mode.
--clear: Clears the debug settings. Closes any open log files and sets the debug level to 0.
--log-file=FILE: Writes all debug messages to the defined file.
--monitor: Monitors the Connection Broker debug output in stderr.

key-passphrase [--all] [--clear] [--passphrase-file= FILE] [--passphrase-string= passphrase] key-id | key-hash

Prompts the user private key passphrase or PIN code.

Options:

--all: Prompts passphrase for all known keys that require it.
--clear: Clears cached private key data and possible cached authentication code for the key.
--passphrase-file=FILE: Instead of prompting, read the passphrase from the defined file.
--passphrase-string=passphrase: Instead of prompting for passphrase, use the passphrase provided on command-line.

list-channels [-s, --short]

Displays a list of the currently open connection channels, together with channel type and traffic statistics. Displays also the channel ID which is used by other commands to identify the connection.

Options:

-s, --short: Displays a one-line description per channel.

list-connections [-s, --short] [--show-channels]

Displays a list of the currently open connections, together with connection parameters and traffic statistics. Displays also the connection ID which is used by other commands to identify the connection.

Options:

-s, --short: Displays a one-line description per connection.
--show-channel: Displays a short description for each open channel.

list-keys [-s, --short]

Displays a list of the user private keys, together with the basic key attributes such as the key type, size, and possible file name or key provider information. Outputs also the fingerprint and the identifier of the key. The identifier is used by other Connection Broker commands to identify the private key.

Options:

-s, --short: Displays a one-line description per user private key.

reload

Rereads the Connection Broker configuration file.

stop

Stops the Connection Broker.

status [-s, --short] [-q, --quiet] [--pid]

Without parameters, displays short statistics and a configuration summary for the currently running Connection Broker process.

Options:

-s, --short: Displays a one-line output with the Connection Broker PID.
-q: Outputs nothing; the exit status is 0 if the Connection Broker connection succeeded, and 1 if the connection failed.
--pid: Displays the PID, only.

view-key [-s, --short] [-v, --verbose] [--clear] [--write-key FILE] key-id

Displays information on the defined key. If the key has certificates, a short summary of them is also shown.

Options:

--clear: Clears cached private key data and cached authentication code for the key.
-s, --short: Displays a one-line description per key.
-v, --verbose: Displays more detailed information on the key or certificate.
--write-key=FILE: Writes the public-key or the certificate to the defined file.

Environment Variables

In order to run ssh-broker-ctl the following environment variables must be set:

LIBPATH=/opt/tectia/lib:$LIBPATH: ssh-broker-ctl uses DLLs that come as part of SSH Tectia installation. LIBPATH is used for setting the search path for DLLs. If this variable is not set correctly ssh-broker-ctl fails to start.
_BPXK_AUTOCVT=ON: If this variable is not set correctly ssh-broker-ctl fails to start.
_CEE_RUNOPTS='FILETAG(AUTOCVT,NOAUTOTAG),TRAP(ON)': If this variable is not set correctly ssh-broker-ctl fails to start.