Command Options
This section describes the options commonly available for most command-line client commands.
Assigning hosts to back-end groups (-b <tags>, --backend-tags=<tags>)
When using the add-hosts command to add hosts, you can immediately associate the specified hosts with back-end tags. Hosts with back-end tags are only managed by the Key Manager back ends that have one or more similar tags.
When specifying multiple back-end tags, separate each back-end tag with a comma (,). Back-end tags cannot contain spaces. All specified back-end tags must already exist in the Key Manager system.
Example:
$ ssh-mgr-client add-hosts -f newhosts.csv -b apac_backend
$ ssh-mgr-client add-hosts -f newhosts.csv -b apac_backend,emea_backend
Batch mode (-B, --batch-mode)
When batch mode is used with a list command (such as list-hosts or list-jobs), the information-listing task is performed under a dedicated Key Manager job process. The advantage of batch mode is that it allows you to retrieve much larger amounts of data without memory or timeout issues.
The output data of batch-mode list jobs is also stored in the job records. This stored output data can later be reviewed and purged via the Key Manager GUI, in the details panel of the associated listing-job type job.
For other commands, batch mode prevents the shell from returning until the jobs started by the command are completed. Batch mode can be useful in sequencing execution, where you want to ensure that jobs started by the current command are completed before jobs for the next command are run.
Specifying output columns (-C <columns>, --columns=<columns>)
By default, commands that output list data output list items with some column values. The default output may include columns that are irrelevant, or may not display columns that are necessary. In such cases, you can use the -C option to specify what columns are displayed.
For example, to display the ip, and the ID of the hosts in the managed environment:
$ ssh-mgr-client list-hosts -C "ip,id"
Specifying input data (-d <data>, --data=<data>)
When specifying multiple arguments, separate them with a comma. Do not add spaces next to delimiters. If a value contains spaces, it must be surrounded with quotes ''.
For example, specifying input data when adding authorized-key options:
$ ssh-mgr-client add-authorized-key-options -i 79 \
-d no-agent-forwarding,no-port-forwarding
Sometimes, you need to specify values for arguments. In such cases, provide the relevant data in the argument=value format. Additionally, values containing spaces must be quoted.
For example:
$ ssh-mgr-client create-host-group -d name=Group_01,description='Database servers'
All terminal input is subject to shell interpretation. For this reason we recommend using strong quotes around complex values to ensure that they are passed verbatim to the command-line client. For example, when passing values in JSON format:
$ ssh-mgr-client set-global-setting -d category=backend,name=socks_proxy,value='\
{"rules": [{"to": "192.168.0.0/24", "via": "proxy.example.com:1080"}]}'
Equal-sign characters (=) in data values must be escaped regardless of whether the value is surrounded in quotes or not. For example, the following command sets the host-group description to TEST=EVAL:
$ ssh-mgr-client create-host-group -d name=Group_01,description='TEST\=EVAL'
Note that equal-sign characters may be present in SSH key data. When providing SSH key data as input data, be sure to escape all equal signs before they are passed to the command-line client.
When providing multiple values for an argument, put commas between individual values:
$ ssh-mgr-client tag-hosts -d tags=tag1,tag2
Data can also be provided from a text file, which can be convenient when dealing with complex data attributes. The target text file is to be specified using the following syntax:
-d @file=path/to/file.txt;
-d @file_trimmed=path/to/file.txt;
In the previous examples, @file=path/to/file.txt; is substituted with the contents of the text
file path/to/file.txt when the command is run. The latter form strips any leading and trailing
whitespaces from the substitution.
For example, assuming the following content in the file data.txt:
allow-from="192.0.2.*",no-agent-forwarding
Running the following command:
$ ssh-mgr-client set-authorized-key-options -i 99 \
-d 'deny-from="192.0.2.101",@file=data.txt;'
Is equivalent to running this command:
$ ssh-mgr-client set-authorized-key-options -i 99 \
-d 'deny-from="192.0.2.101",allow-from="192.0.2.*",no-agent-forwarding'
Specifying custom delimiters for CSV output (-E <delimiter>, --delimiter=<delimiter>)
When choosing to output data in CSV format, you can use the -E option to specify a custom free-text
delimiter used for separating fields in the CSV output. This option can be used with all list commands
when output format is set to CSV.
By default, list commands output CSV data where individual values are separated using commas. For example, when listing the name, IP address, and the state of each host:
$ ssh-mgr-client list-hosts -C hostname,ip,state
server01.example.com,192.0.2.101,monitored
server02.example.com,192.0.2.102,managed
server03.example.com,192.0.2.103,managed
...
You can add the -E option to specify a custom delimiter. For example:
$ ssh-mgr-client list-hosts -C hostname,ip,state -E " "
server01.example.com 192.0.2.101 monitored
server02.example.com 192.0.2.102 managed
server03.example.com 192.0.2.103 managed
...
You can also specify custom delimiters that are longer than one character:
$ ssh-mgr-client list-hosts -C hostname,ip,state -E "+DELIM+"
server01.example.com+DELIM+192.0.2.101+DELIM+monitored
server02.example.com+DELIM+192.0.2.102+DELIM+managed
server03.example.com+DELIM+192.0.2.103+DELIM+managed
...
Note that in order to get output in Tab-Separated-Values (TSV) format, you need to use the -o option
with the tsv argument.
$ ssh-mgr-client -o tsv <command>
Specifying input data from a file (-f <filename>, --file=<filename>)
When using the command-line client to add elements (such as hosts or keys) to the managed
environment, it is often possible to specify data from a text file using the -f option. Compared to the
-d option, text files allow you to specify multiple elements simultaneously, which offers an efficient
way for performing actions on many objects with a single command.
The following conventions apply to the format of text files:
-
Values are comma-delimited by default.
-
The first line in the text file is used to define what attributes are provided on subsequent lines. See the documentation sections for specific commands as to what attributes are required by each command. Values on subsequent lines must be specified in the same order as on the first line.
-
Each line after the first one specifies one individual element. The attributes (specified on the first line).
As an example, the contents of a text file (for adding hosts) could look like this:
hostname,username,password
sap1.example.com,username,password
sap2.example.com,username,password
dbeast.example.com,username,password
dbwest.example.com,username,password
logistics.example.com,username,password
billing.example.com,username,password
Another example file with values that contain spaces (for adding host groups):
description,name
Office workstations,Workstations
Admin machines,ADM Group
Operations performed with text file data are fail-fast processes. If there is an error on even one of the rows in the file, none of the rows in the file are processed.
The command-line client does not support substituting your home directory using tilde (~). However, you can use the $HOME environment variable as an alternative shorthand notation.
Filtering (-F, --filter)
The -F option is used to filter output for listing commands. The option is also used for some
commands to specify the items for which the command is to be performed.
Specify filter criteria in the column=value format. Surround the entire filter string with quotes. The
wildcard * can be used in the beginning and/or the end of a value to substitute for any string in a value.
For example, if you want to list all the hosts, the name of which contains server, you can apply a
filter to the list-hosts command:
$ ssh-mgr-client list-hosts -F "hostname=*server*"
You can specify more than one value for most columns. To do this, surround the possible values with brackets and delimit the values with a comma. For example, to list all the hosts that are either in the monitored or the managed state:
$ ssh-mgr-client list-hosts -F "state=[monitored,managed]"
You can specify multiple columns, delimited with && or %%. Do not add spaces next to delimiters.
Both of the next example commands lists the hosts, the name of which starts with exampledomain
and the state of which is managed.
$ ssh-mgr-client list-hosts -F "hostname=exampledomain*&&state=managed"
$ ssh-mgr-client list-hosts -F "hostname=exampledomain*%%state=managed"
If a value contains spaces or special characters, you must surround it with additional quotes. In such cases, any wildcards should be placed outside the single quotes. The additional quotes must be different from the quotes used for the entire filter string. For example, if you quoted the entire filter string with double quotes, use single quotes to surround the value that contains spaces:
$ ssh-mgr-client list-host-groups -F "hostgroup='Host Group 01'*"
Filter criteria can also be provided from a text file, which can be convenient when dealing with complex data attributes. The target text file is to be specified using the following syntax:
-F @file=path/to/file.txt;
-F @file_trimmed=path/to/file.txt
In the previous examples, @file=path/to/file.txt; is substituted with the contents of the text
file path/to/file.txt when the command is run. The latter form strips any leading and trailing
whitespaces from the substitution.
For example, assuming the following content in the file data.txt:
state=managed&&os=Linux
Running the following command:
$ ssh-mgr-client list-hosts -F 99 \
-F "hostname=*.example.com&&@file=data.txt;"
Is equivalent to running this command:
$ ssh-mgr-client list-hosts -F 99 \
-F "hostname=*.example.com&&state=managed&&os=Linux"
Regular filters can also be used in conjunction with exclude filters (-X). When used in conjunction with regular filters, exclude filters take precedence. For example, to list all the hosts in a certain domain that do not have a certain tag:
$ ssh-mgr-client list-hosts -F "hostname=*.example.com" -X "tags=example_tag"
The available attributes for filtering by any item type are listed in the list-<item> commands.
For filtering by time ranges, you can use operators such as < and > to definite the beginning and/or the end of a time range. For more information about filtering by time ranges, see Filtering by Modified Date.
When filtering by some timestamp fields, you can use relative dates for filtering. For more information about filtering by relative dates, see Filtering by Relative Time Ranges.
When filtering by timestamp fields other than date_modified, note that you must provide the
timestamp in the format specified by the Key Manager Database. For examples about filtering by
timestamps, see Filtering by Timestamp Fields.
Printing header line for list output (-H, --print-header)
For list commands, you can use this option to print a header line in the beginning of the list output. The header line displays the names of the printed attributes in order.
To use this option, output-data format must be csv (which is the default output format for most commands).
For example, using the -H option with the list-hosts command.
$ ssh-mgr-client list-hosts -H
state,status,hostname,os_release,ssh_version_string
managed,ok,server01.example.com,SunOS 5.11 11.1,SSH-2.0-Sun_SSH_2.0
managed,ok,server02.example.com,SunOS 5.11 11.1,SSH-2.0-Sun_SSH_2.0
managed,ok,server03.example.com,SunOS 5.11 11.1,SSH-2.0-Sun_SSH_2.0
Filtering by ID (-i, --id)
The -i option is shorthand for -F id=<value>. For example, the following two commands are equivalent (they display the host with the ID of 1):
$ ssh-mgr-client list-hosts -F "id=1"
$ ssh-mgr-client list-hosts -i 1
Specifying an object using identifiers (-I)
The -I option is used for specifying a single object using the attributes of the object.
When using this option, you must specify the identifying attributes so that only one object is matched. Attributes that match zero or multiple objects cause an error.
This option supports the same syntax as filtering (-F), such as the * wildcard, matching by multiple attributes with &&, and file substitutions.
For example, when listing the effective settings of a host group, this host group can be selected using the attributes of the host group, such as the name of the host group:
$ ssh-mgr-client set-host-group-setting -I 'hostgroup=Example_Group' \
-d category=host,name=scan_interval,value=1800
Ignoring strong cipher requirements (--insecure)
You can add this option to perform commands on machines that are unable to enforce strong SSL ciphers.
When the --insecure is used, information transferred by the command-line client may not be sufficiently secured against eavesdropping and tampering. Usage of this option should be limited to secure network environments only!
In all cases, it is preferable to run the command-line client on machines that are able to enforce strong SSL ciphers, which makes this option unnecessary.
For performing commands, the command-line client connects to Key Manager Servers using SSL- protected connections. Some machines (such as those using older, unsupported versions of Python) may not be able to enforce strong ciphers to securely transfer data. Normally, using the command- line client on such machines prevents the command-line client from establishing a connection to any Key Manager Server, and therefore causes commands to fail.
Limiting the number of returned elements (-M <number>, --max-results=<number>)
You can use this option to limit the maximum number of elements returned by list commands (excluding the list-authorizations command). When this option is specified, only the specified number of elements are returned.
For example, to only return 50 host entries:
$ ssh-mgr-client list-hosts -M 50
In large managed environments, unfiltered list commands may return overwhelming amounts of data, and the operation is likely to be very resource-intensive. This option can be useful in situations where it is sufficient to retrieve a snapshot of the available elements.
You can use the -M option in conjunction with the sort option -O to return the first entries from a sorted list. For example:
$ ssh-mgr-client list-hosts -M 50 -O id
Allow connections without certificate-host-name verification (--no-check-hostname)
The --no-check-hostname option can be used to allow client connections even when the server name in the client certificates fails to match the target server.
When the --no-check-hostname option is used, the command-line client is unable to guarantee that it is connected with the intended Key Manager front end. For production environments, you should set up valid certificates on the target Key Manager front end instead of using this option.
Changing output format (-o, --data-format)
Commands can output data in JSON, text, CSV, and TSV format. To specify the output format, use the -o option like the following:
$ ssh-mgr-client -o json <command>
$ ssh-mgr-client -o csv <command>
$ ssh-mgr-client -o text <command>
$ ssh-mgr-client -o tsv <command>
Sorting lists (-O <column,column,...>, --sort-order=<column,column,...>)
Sort list-command (excluding the list-authorizations command) output in ascending order according to the specified columns.
For example, to list the hosts in the managed environment according to ID:
$ ssh-mgr-client list-hosts -O id
To sort the list in descending order, add a - in front of the column name:
$ ssh-mgr-client list-hosts -O -id
You can specify more than one column for sorting. If there are multiple elements that share the same value in a column, the next specified columns are used to determine the order among such elements. For example, to sort the alerts primarily by alert type, and secondarily by the host where the alert occurred.
$ list-alerts -O alert_type,host
Setting job priority (-p <number>)
Some command-line client commands generate jobs for performing key-management actions on hosts in the managed environment. When issuing such commands, you can set the priority of the jobs that are generated by the command.
For example, starting a high-priority authorized-key-restoration job:
$ ssh-mgr-client restore-authorized-keys -F id=999 -p 1
Starting a lower-priority scan job:
$ ssh-mgr-client scan-hosts -F hostname=server01.example.com -p 20
Start displaying data from the given row (-S, --start-from)
You can use the -S option to hide a specified number of elements from the beginning of a list. For
example, to display all the hosts in the managed environment, except for the first 50 hosts in the list:
$ ssh-mgr-client list-hosts -S 50
Use the -S option in conjunction with the sort option -O to specify a sort order before
excluding elements. For example:
$ ssh-mgr-client list-hosts -S 50 -O id
Tagging targets (-t <tags>)
When using the command-line client to add hosts or modify user keys, you can use the -t option to
immediately tag the items involved in the command. For example, tags can be used for describing
the actions that were performed on the target items. Tagging also allows you to find these items more
easily at a later date.
When specifying multiple tags, separate each tag with a comma (,). Tags cannot contain spaces. If you specify a tag that has not yet been created in the Key Manager system, the tag is created automatically.
Example:
$ ssh-mgr-client add-authorizations -f newauths.txt \
-t new_authorization,needs_approval
Timeout for batch mode (-T, --timeout=<seconds>)
When using batch mode (-B or --batch-mode), you can use this option to specify the maximum
time after which the shell returns.
For example, you can run a host scan in batch mode with a maximum wait time of 60 seconds, by running one of the following commands:
$ ssh-mgr-client scan-hosts -i 1 -B -T 60
$ ssh-mgr-client scan-hosts -1 1 -B --timeout=60
Note that this timeout only forces the shell to return within a given timespan. Timeouts specified using these options do not affect job execution. Job timeouts are controlled using Key Manager system settings (described in Key Manager System Settings.
Providing API URL (-U)
By default, the command-line client reads the API location from the SSHMGR_URL environment
variable. You can also specify the API location using the -U option:
$ ssh-mgr-client -U https://example.frontend.com/api/v2/ <command>
We recommend specifying the API location in the SSHMGR_URL environment variable to minimize
typing.
Enabling verbose mode (-v, --verbose, -vvv)
Using verbose mode causes some of the client commands to print additional information, which can be useful, for example, in debugging scenarios.
Exclusive filtering (-X, --exclude-filter=<exclude-filter>)
Exclude filters omit matching items from the results. The syntax is identical to that used for regular
filtering (-F).
For example, to list the hosts that do not have a certain tag:
$ ssh-mgr-client list-hosts -X "tags=example_tag"
When used in conjunction with regular filters, exclude filters take precedence. For example, to list all the hosts in a certain domain that do not have a certain tag:
$ ssh-mgr-client list-hosts -F "hostname=*.example.com" -X "tags=example_tag"