User-Key Commands

This section describes the command-line client commands that can be used for managing user keys.

add-request

Syntax:

ssh-mgr-client add-request [options] \
-d <data> [-vvv] [-U <url>] [-o <format>]

Add key request to the Key Manager system.

In input data (-d), you must provide the type of the request, in addition to any data required by the selected request type:

note

This command is used by User Portal to generate requests.

Required data:

request_type

Must be one of the following:

accept_keys
authorization_request
provide_passphrase
remove_keys
renew_keys
restore_keys
rollback_keys
set_key_options
set_notes
set_passphrase
show_passphrase

Possible data for request_type authorization_request:

command

(Optional). The command restriction (forced command) that is to be set for the requested authorizations. By default, no command restriction is set.

comment

(Optional). Comment of the requestor, which should generally describe where the user needs access to, and why. This comment is shown verbatim to the Key Manager administrator approving or denying the request.

dst

List of destination specifiers for the request. Each destination can specify a managed user account in {"ukm_user_id": <user_id>} format, an external user account in {"contact": <email>} format, or a provisioned host-group in {"provisioned": <bool>, "customer": <customer_name>, "username": <dst_account_name>, "application": <application_name>, "group": <host_group_name>} format.

extra_data

(Optional). Extra JSON data from the requestor. This data is displayed to the Key Manager administrator approving or denying the request.

from_stanza

(Optional). A list of source addresses from which the authorizations can be used. If unset, the authorizations can be used from any address.

key_alg

(Optional). The algorithm used for generating new keys. Possible values are rsa, dss, ecdsa, and ed25519. Defaults to the algorithm set as default in the global setting Public key algorithm, minimum size and default size policy; for more information about setting the default algorithm, see Global Settings.

For more information about the key_alg option, see Specifying the Key Algorithm.

key_size

(Optional). The length of the key in bits. Default defined by global setting Public key algorithm, minimum size and default size policy; for more information about setting the default key size, see Global Settings.

owner

Email of the application owner managing this request.

passphrase

(Optional). The passphrase that is to be set for the authorizations. Set to random to set a randomly generated passphrase for the authorizations. Note that passphrases. Default: none

reuse

(Optional). If set to True, a suitable existing private key is used for authorization. To be considered suitable, the key must be of the requested algorithm and size. If set to False, a new private key is used for authorization, regardless of whether a suitable private key already exists. Defaults to True.

src

Array of source specifiers for the request. Source can specify a user account in {"ukm_user_id": <user_id>} format, or an authorized key in {"contact": <email>} format.

tags

Optional). List of tags to add to newly-created keys. Default: none.

validity

(Optional). String specifying the validity period for the authorization in [begin]..[end] format. Defaults to unlimited.

Possible data for request_type rollback_keys:

auth_key_filter

A filter matching authorized keys to roll back. Follows the same filter syntax as used in the listauthorized-keys command.

auth_key_ids

Array listing the IDs of the authorized keys to roll back.

private_key_filter

A filter matching private keys to roll back. Follows the same filter syntax as used in the listprivate-keys command.

private_key_ids

Array listing the IDs of the private keys to roll back.

timepoint

The point in time to which the target keys are to be rolled back. The timepoint must be specified in database-timestamp format. For example: 2018-12-19T16:26:27Z

Common data for request types (excluding authorization_request):

application

The name of the target application. The approval policy of this application is used for this request. If left blank, the default approval policy (defined by the global setting request_approval_policy) is applied to this request.

execution_window

Optional). String specifying when the jobs associated to this request can be run. Specified in [begin]..[end] format. Defaults to unlimited.

key_args

Optional). Mapping from key ids to per-key arguments for the action, in JSON format.

key_ids

Comma-separated list of target-key IDs.

key_type

Either auth_key or private_key

owner

Optional). Email of the application owner managing this request.

Example for adding a key request:

$ ssh-mgr-client add-request -d 'request_type=accept_keys,\
key_type=auth_key,key_ids=[11,12],application="Example App 01",owner=alice@example.com'

Example for adding an access request:

$ ssh-mgr-client add-request -d 'request_type=authorization_request,\
src=[{"ukm_user_id": 1}],dst=[{"ukm_user_id": 2}],owner=alice@example.com'

add-authorizations

Syntax:

ssh-mgr-client add-authorizations [options] \
(-d <data> | -f <file>) [-vvv] [-U <url>] [-o <format>] \
[-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Add authorizations between the accounts in the managed environment. The source and target accounts must be on hosts that are in the managed state.

To add authorizations using this command, you must identify the source and the destination accounts of the authorization. Identify the accounts using the username@hostname format. Similar to the syntax used with the ssh command.

note

When specifying hostname, use the hostname shown in Key Manager. Note that the hostname shown in Key Manager may not always match the FQDN or the IP address of the host.

You can get the hostnames as shown in Key Manager using the list-hosts command (described in list-hosts).

You must at least specify the sources and destinations for which you want authorizations. You can specify sources using the following data attributes:

from

Source account(s) in username@hostname format.

from_keyids

IDs of private keys that are authorized to destinations.

from_userids

IDs of users that are authorized to destinations.

And destinations with the following:

to

Destination account(s) in username@hostname format.

to_extuserids

IDs of external user accounts.

to_keyids

IDs of destination keys.

to_userids

IDs of destination user accounts.

note

Source specification is unnecessary with key_data

You can optionally provide the following data:

add_to_config

If set to True, the private keys used for the authorizations are automatically added to the SSH configuration (if they are not already in configuration). If set to False, SSH configurations are not altered in any way. Defaults to True.

Note that a private key must be in the SSH client configuration (either the host-specific, or the user-specific client configuration) for it to be usable for authorization. Also, note that configurations must be in the managed state before Key Manager is able to modify them.

command

If set, the authorization is restricted to performing this command. When the authorization is used successfully, it performs the specified command on the destination host, then disconnects.

contact

Contact email for key_data

from_stanza

If set to True, restrictions are added to the generated authorized keys so that they can only be used to authorize users from the specified source (from) addresses. True by default.

key_alg

The algorithm that is to be used for generating the private key for the authorization. Possible values are rsa, dsa, ecdsa, and ed25519. Defaults to the algorithm set as default in the global setting Public key algorithm, minimum size and default size policy; for more information about setting the default algorithm, see Global Settings.

For more information about the key_alg option, see Specifying the Key Algorithm.

key_data

Public key (file content) to authorize to destinations.

key_path

The file path of the private keys. If key_path is unspecified, key_path is set according to applicable paths acquired from the SSH client configuration. Any relative paths are assumed to be relative to the users' SSH directories, typically located at ~/.ssh/.

key_size

The size of the key in bits. Default defined by global setting Public key algorithm, minimum size and default size policy; for more information about setting the default key size, see Global Settings.

passphrase

The passphrase that is to be set for the private keys of the resulting authorizations. If unspecified, the private keys are not passphrase-protected. If set to random, the new private keys are given random passphrases.

reason

A free-text message that is set into the audit event that logs the creation of the authorization.

reuse

If True, the command uses existing private keys to establish the authorization. If False, the command generates a new private key for the authorization. The default is True.

note

When setting reuse to False, note that on OpenSSH hosts the OpenSSH client configuration specifies a finite number of private keys that are usable for authorization. If the source user account already possesses all the usable private keys specified by the OpenSSH configuration no new private keys can be created and the command fails.

tags

List of tags to add to newly-created keys. Default: none.

validity

String specifying the validity period for the authorization in [begin]..[end] format. Defaults to unlimited.

The command launches a add-authorization job for adding the new authorizations. The new authorizations are added and ready for use as soon as this job finishes.

For example, to add an authorization from the sourceuser account at source.host.com to the destinationuser account at destination.host.com:

$ ssh-mgr-client add-authorizations -d \
from=sourceuser@source.host.com,to=destinationuser@destination.host.com

You can add authorizations from multiple source accounts to multiple destination accounts. Authorizations are added from each source account to each destination account:

$ ssh-mgr-client add-authorizations -d \
'from=user@[host1,host2],to=user@[host3,host4]'

You can provide the information from a text file as well, using the -f option. It is possible to add multiple authorizations with a single command when using this approach:

$ ssh-mgr-client add-authorizations -f newauths.txt

An example of what the contents of newauths.txt could look like:

from,to
username01@bastion01.example.com,username01@pdserver03.example.com
username02@pdserver02.example.com,username02@dbwest.example.com
username01@bastion01.example.com,username02@tserver01.example.com

add-authorized-key-options

Syntax:

ssh-mgr-client add-authorized-key-options -d <data> [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-o <format>] [-B] \
[-T <timeout>] [-t <tags>] [-p <priority>]

Add options to selected authorized keys. This command does not modify existing options. However, be mindful that options you set with this command may invalidate existing options.

Select the authorized keys using filters (-F). Alternatively, you can select a single authorized key using its ID (-i). For filtering, you can use the same filter criteria that are available for the list-authorizedkeys command (described in Section add-authorizations).

Specify key options as input data (-d). Key options can be provided in OpenSSH and/or Tectia format. The following list describes the OpenSSH and Tectia key options that are supported by most SSH products. For a complete list of supported key options, please consult the documentation of your SSH product.

command

The forced command for this authorized key.

When a forced command is specified for an authorized key, successful authorization using that key causes the forced command to be run on the destination host as the destination user, after which the connection is automatically disconnected. When no forced commands are specified, the user is typically given shell access to the destination host as the destination user.

allow-from

An IP addresses, or a network, where the authorized keys can be used from.

deny-from

An IP addresses, or a network, from which using the authorized keys is denied.

from

A list of IP addresses and/or networks that defines where the authorized key can be used from. Used for specifying both allowed and denied addresses.

The command launches set-authorized-key-options jobs to modify the options of the selected keys. The new options are set as soon as the jobs finish.

caution

Ensure that the authorized-key options you specify are supported by the SSH Product that is responsible for the selected keys. Incorrect options may cause the selected keys to become unusable.

For example, to add deny-from option to a single authorized key:

$ ssh-mgr-client add-authorized-key-options -d \
deny-from="server03.example.com" -i 110

As another example, to allow access from multiple addresses to all authorized keys on a certain host, while disabling agent forwarding:

$ ssh-mgr-client add-authorized-key-options -d \
allow-from='192.0.2.100',allow-from='192.0.2.14*',no-agent-forwarding -F \
"hostname=server01.example.com"

When specifying a from stanza containing multiple addresses, be mindful that the comma-separated addresses must be surrounded using quotes. To prevent the shell from interpreting the quotes, surround your options string using single quotes. For example:

$ ssh-mgr-client add-authorized-key-options -d \
'from="192.0.2.100,192.0.2.101,!192.0.2.102",no-agent-forwarding' -i 110

Be mindful that command strings must be surrounded using double quotes, which is a requirement imposed by SSH products. Once again, we recommend surrounding the options string with single quotes to prevent shell interpretation:

$ ssh-mgr-client add-authorized-key-options -d \
'command="ls /some/directory"' -i 110

If you need to specify double quotes inside the command restriction, these must be escaped. For example, to specify the command restriction echo "Hello world":

$ ssh-mgr-client add-authorized-key-options -d \
command='"echo \"Hello world\""' -i 110

approve-authorized-keys

Syntax:

ssh-mgr-client approve-authorized-keys [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>]

Approve authorized key(s). Specify the authorized key(s) using filters, or by providing its ID. Filtering can be done using the attributes accepted by the list-authorized-keys command (see list-authorized-keys).

For example, approving the keys with the ID values 85, 130, and 428:

$ ssh-mgr-client approve-authorized-keys -F id=[85,130,428]

approve-private-keys

Syntax:

ssh-mgr-client approve-private-keys [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>]

Approve private key(s). Specify the private key(s) using filters, or by providing its ID. Filtering can be done using the attributes accepted by the list-private-keys command (see list-private-keys).

For example, approving the keys with the ID values 85, 130, and 428:

$ ssh-mgr-client approve-private-keys -F id=[85,130,428]

approve-requests

Syntax:

ssh-mgr-client approve-requests [options] (-F <filter> | -i <id>) \
[-d <data] [-vvv] [-U <url>] [-B] [-T <timeout>]

Submit an approval for the selected requests.

Select a request by specifying its ID (-i). Alternatively, you can select multiple requests using filters (-F). For filtering, you can use the same attributes that are available for the list-requests command (described in list-requests).

Optional data:

owner

The application owner who submits the request. Defaults to admin.

approval_options

Approval data in JSON format.

Example for approving a request by ID:

$ ssh-mgr-client approve-requests -i 99

blacklist-authorized-keys

Syntax:

ssh-mgr-client blacklist-authorized-keys [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-B] \
[-T <timeout>] [-t <tags>] [-p <priority>

Blacklists the specified authorized keys. Blacklisting an authorized key removes the key itself. Also, all those keys in the managed environment that have the same fingerprint as the selected key are also blacklisted and removed. Copies of blacklisted keys that appear in the future are also removed upon detection.

You can use filters or the key id to specify the authorized key(s) that are to be blacklisted. For filtering, you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

The command launches a blacklist-keys job to blacklist and delete the target keys. The keys are blacklisted and deleted as soon as the jobs finish.

Examples:

$ ssh-mgr-client blacklist-authorized-keys -i 12

$ ssh-mgr-client blacklist-authorized-keys -F id=[12,33]

For more information about blacklisting keys, see

cancel-requests

Syntax:

ssh-mgr-client cancel-requests [options] (-F <filter> | -i <id>) \
[-d <data] [-vvv] [-U <url>] [-B] [-T <timeout>]

Cancel the selected requests.

Select a request by specifying its ID (-i). Alternatively, you can use filters (-F) to select multiple requests. For filtering, you can use the same attributes that are available for the list-requests command (see list-requests).

note

You can only cancel requests that are still pending processing.

For example, to cancel a request by its ID:

$ ssh-mgr-client cancel-requests -i 999

continue-key-relocation

Syntax:

ssh-mgr-client [global_options] continue-key-relocation (-F <filter> | -i <id>) \
(-d <data>) [-o <format>] [-B] [-T <timeout>] [-p <priority>] \
[--allow-actions-on-shared-keys

Continue key relocation on hosts where at least one key-relocation stage has already been performed. Nothing is performed on hosts where no key relocation has ever been performed, nor on hosts with missing key-relocation stages. Also, this action only performs the relocation stages that have yet to be performed on the selected host(s). For example, if you perform this action while only opting to remove old keys, the stage 3 of relocation, operations are performed only on hosts that are at Key relocation stage 2.

The command launches a relocate-user-keys job to relocate the keys on the selected hosts. The requested key-relocation stages are completed when the job finishes.

Example, updating the SSH-server configuration on hosts where keys have already been copied to auth_keys_dir (applicable for hosts in key_relocation_stage 1):

$ ssh-mgr-client continue-key-relocation -F "hostname=example.server*" -d \
"update_configs=True"

As another example, performing all the remaining key-relocation stages (applicable for hosts in key_relocation_stage 1 and 2):

$ ssh-mgr-client continue-key-relocation -F "hostname=example.server*" -d \
"update_configs=True,remove_old_keys=True"

note

To start key relocation on hosts, use the relocate-user-keys command instead (described in relocate-user-keys).

count-authorized-keys

Syntax:

ssh-mgr-client count-authorized-keys [options] [-F <filter>] [-vvv] [-U <url>]

Returns the number of authorized keys in the Key Manager system.

You can use filters to display the number of authorized keys that match the given filters. For filtering, you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

Example:

$ ssh-mgr-client count-authorized-keys
107503

Example for finding all the authorized keys that are on a specific host:

$ ssh-mgr-client count-authorized-keys -F "hostname=example.server.com"
250

count-private-keys

Syntax:

ssh-mgr-client count-private-keys [options] [-F <filter>] [-vvv] [-U <url>]

Returns the number of private keys that match the given filter criteria. For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

When given no filter criteria, the command returns the number of private keys in the Key Manager system.

$ ssh-mgr-client count-private-keys
15730

Example for returning the number of private keys on Linux hosts:

$ ssh-mgr-client count-private-keys -F \
"from_ip=10.10.5.121"
7350

edit-authorized-keys

Syntax:

ssh-mgr-client edit-authorized-keys [options] \
(-F <id-filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Set the custom-data fields of the selected authorized keys.

In input data (-d), specify the fields and their new values in columnname=value format. Any existing values for the specified fields are overwritten using the new values. Select the authorized keys using their ID (-i), or using matching ID filters (-F). For ID filtering, you can use the same attributes that are available for the list-authorized-keys command (described in list-authorized-keys).

Names of the fields that can be modified with this command:

notes
custom1
custom2
custom3

For example, setting custom1 to Example value, and setting custom2 to value,value2 for authorized keys on host example.server.com:

$ ssh-mgr-client edit-authorized-keys -d \
"custom1=Example value,custom2=value,value2" -F "hostname=example.server.com"

edit-private-keys

Syntax:

ssh-mgr-client edit-private-key [options] \
(-F <id-filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Set the custom-data fields of the selected private keys.

In input data (-d), specify the fields and their new values in columnname=value format. Any existing values for the specified fields are overwritten using the new values. Select the private keys using their ID (-i), or using matching ID filters (-F). For ID filtering, you can use the same attributes that are available for the list-private-keys command (described in list-private-keys).

Names of the fields that can be modified with this command:

notes
custom1
custom2
custom3

For example, setting custom1 to Example value, and setting custom2 to value,value2 for private keys on host example.server.com:

$ ssh-mgr-client edit-private-keys -d \
"custom1=Example value,custom2=value,value2" -F "hostname=example.server.com"

forget-private-key-passphrase

Syntax:

ssh-mgr-client forget-private-key-passphrase [options] -i <id> [-vvv] \
[-U <url>] [-o <format>] [-t <tags>]

Remove the passphrase of the selected private key from the Key Manager system.

Select a private key using its ID (-i).

note

This command only removes the passphrase stored in Key Manager. Passphrases are not cleared from the private keys themselves, and users must still input the passphrase to authenticate using them. After you run this command, you can no longer useKey Manager to show the passphrases of the affected keys. Also, you cannot retain the passphrase when performing key renewal on the affected keys.

Usage examples:

$ ssh-mgr-client forget-private-key-passphrase -i 99

decide-requests

Syntax:

ssh-mgr-client decide-requests [options] \
(-F <filter> | -i <id>) -a <action> [-d <data>] [-vvv] [-U <url>] [-B] [-o <format>]

Approve or deny requests. Used for handling both action requests and authorization requests.

Select a request using its ID (-i). Alternatively, you can select multiple requests using filters (-F). For filtering (-F), you can use the same attributes that are available for the list-requests command (see list-requests).

Specify the decision with the option -a. Available decisions for authorization requests are: deny and authorize. Available decisions for action requests are: deny and approve.

Also provide the required data using -d. The required and optional data depends on the decision as follows:

Optional data for all decisions:

send-email

Whether to send a notification email to the requestor when the request has been completed. Set to True to send a notifcation, False to refrain from sending a notification. Defaults to True.

message

Message to include in the notification email.

Required data for decision authorize:

to

The account(s) to which the requestor is to be authorized. The syntax is the same as that used for specifying destination accounts for the add-authorizations command (described in add-authorizations).

Optional data for decision authorize:

allow-from

An IP addresses, or a network, where the authorized keys can be used from. When allow-from addresses are provided, access from other addresses is denied.

command

The forced command for this authorized key.

tags

Comma-separated list of tags that are applied to the authorized keys created by this command.

When an action request is approved using this command, Key Manager launches jobs to modify the keys as required for the action request. The exact type of the jobs depends on the types of the action requests.

Example for denying an authorization request

$ ssh-mgr-client decide-requests -i 67 -a deny \
-d message="No destinations specified in comment."

Example for approving a signoff request:

$ ssh-mgr-client decide-requests \
-i 68 -a approve

Example for authorizing to multiple accounts:

$ ssh-mgr-client decide-requests \
-i 68 -a authorize -d to=alice@[server01.example.com,server02.example.com]

generate-user-private-keys

Syntax:

ssh-mgr-client [global_options] generate-user-private-keys \
(-F <filter> | -i <id>) [-d <data>] [-o <format>] [-B] [-T <timeout>]

Create new private key(s) for the selected user(s). This command can also be used for adding existing private keys to the appropriate SSH configurations, ensuring that they can be used for authorization.

Select a user by specifying their ID (-i). Alternatively, you can select multiple users by using filters (F). For filtering, you can use the same filter criteria that are available for the list-users command (described in list-users).

note

New private keys generated by this command are not authorized to any remote locations, but can later be used for authorizing the selected users to remote destination, for example, by using the add-authorizations command with reuse=True and key_path specified to the path of the generated private key.

Optional data:

add_to_config

If set to True, add the newly-generated and the reused private keys to the SSH configuration (if they are not already in configuration). If set to False, SSH configurations are not altered in any way. Defaults to False.

Note that a private key must be in the SSH client configuration (either the host-specific, or the userspecific client configuration) for it to be usable for authorization. Also, note that configurations must be in the managed state before Key Manager is able to modify them.

comment

The key comment that is set for the generated keys. Defaults to no comment.

key_alg

The algorithm used for generating new keys. Possible values are rsa, dsa, ecdsa, and ed25519. Defaults to the algorithm set as default in the global setting Public key algorithm, minimum size and default size policy; for more information about setting the default algorithm, see Global Settings.

For more information about the key_alg option, see Specifying the Key Algorithm.

key_path

key_size

The size of the private keys, specified in numbers of bits. Default defined by global setting Public key algorithm, minimum size and default size policy; for more information about setting the default key size, see Global Settings.

passphrase

The passphrase set for newly-generated private keys. If unspecified, no passphrase is set for newlygenerated private keys.

reuse

If set to True, and if a selected user already has a private key that matches the specified attributes (key_alg, key_size, key_path if specified), no new private key is generated for the user. If set to False, a new private key is generated for the user unless key_path is specified and if key_path points to an existing private-key file. Defaults to False.

A simple example for generating new private keys for users:

$ ssh-mgr-client generate-user-private-keys -F username=[alice,bob]

On OpenSSH hosts, the number of IdentityFile locations is limited. If all the available IdentityFile locations are already occupied, newly generated private keys will fall outside the configuration, and will be unavailable for authorization purposes. Set add_to_config to True to ensure that newly-generated private keys are automatically added to the SSH configuration:

$ ssh-mgr-client generate-user-private-keys -F username=[alice,bob] \
-d 'add_to_config=True'

You can also use this command to add existing private keys to the SSH configuration:

$ ssh-mgr-client generate-user-private-keys -F username=[alice,bob] \
-d 'add_to_config=True,reuse=True,key_path=/path/to/existing/keyfile'

deny-requests

Syntax:

ssh-mgr-client deny-requests [options] (-F <filter> | -i <id>) \
[-d <data] [-vvv] [-U <url>] [-B] [-T <timeout>]

Deny the selected requests.

Select a request by specifying its ID (-i). Alternatively, you can select multiple requests using filters (- F). For filtering, you can use the same attributes that are available for the list-requests command (described in list-requests).

Optional data:

owner

The application owner who submits the request. Defaults to admin.

approval_options

Approval data in JSON format.

Example for approving a request by ID:

$ ssh-mgr-client deny-requests -i 99

label-authorized-keys

Syntax:

ssh-mgr-client label-authorized-keys [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Label all the keys that have the same fingerprint as any of the selected authorized keys.

Specify the label by providing the label attribute (-d). You can select an authorized key by providing its ID (-i). Alternatively, you can select authorized keys using filters (-F). For filtering, you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys.

Required data:

label

The text that is used for labeling the authorized key(s).

For example, assigning a key, and any other keys that have the same fingerprint, with a label:

$ ssh-mgr-client label-authorized-keys -i 81 -d label="example_label"

As another example, assigning all keys on a certain host, and any other keys that have the same fingerprints, with a label:

$ ssh-mgr-client label-authorized-keys -F "hostname=example.server.com" \
-d label="example_label"

label-fingerprints

Syntax:

ssh-mgr-client label-fingerprints [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Assigns a specified label to all the keys belonging to the selected fingerprint. Since all the keys that belong to a common authorization have the same fingerprint, this command effectively labels all the keys belonging to the selected fingerprints.

Specify the label in input data (-d). You can specify an authorization using its ID (-i). Alternatively, you can select authorizations using filters (-F). For filtering, you can use the same attributes that are available for the list-authorizations command (see list-authorizations).

Required data:

label

The text that is used for labeling the public key(s).

For example, assigning a key with a label:

$ ssh-mgr-client label-fingerprints -i 81 -d label="example_label"

As another example, labeling all public keys, the private key of which exists on a certain host:

$ ssh-mgr-client label-fingerprints -F "pk_hostname=example.server.com" \
-d label="example_label"

label-private-keys

Syntax:

ssh-mgr-client label-private-keys \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Label all the keys that have the same fingerprint as any of the selected private keys.

Specify the label by providing the label attribute (-d). You can select a private key by providing its ID (-i). Alternatively, you can select private keys using filters (-F). For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

Required data:

label

The text that is used for labeling the private key(s).

For example, assigning a key, and any other keys with the same fingerprint, with a label:

$ ssh-mgr-client label-private-keys -i 82 -d label="example_label"

As another example, assigning all keys on a certain host, and any other keys with the same fingerprints, with a label:

$ ssh-mgr-client label-private-keys -F "hostname=example.server.com" \
-d label="example_label"

list-authorizations

Syntax:

ssh-mgr-client list-authorizations [options] \
[-F <filter>] [-vvv] [-U <url>] [-o <format>] [-C <columns>] [-H]

$ ssh-mgr-client list-authorizations

The following columns can be used for filtering (-F) and output formatting (-C):

ak_applications

List of application instances the authorized key is associated with

ak_audit_ids

List of audit event id:s for the authorized key. Only usable for output formatting (-C).

ak_custom1

Custom field 1 for the authorized key

ak_custom2

Custom field 2 for the authorized key

ak_custom3

Custom field 3 for the authorized key

ak_date_created

Date when the authorized key was created or first seen on a host

ak_date_modified

Date when a modification to any authorized key of an authorization was made. Only usable for filtering (-F).

ak_external_key_owner_id

PrivX Key Manager id of the external user owning the authorized key

ak_host_classification

Classification of the host of the authorized key

ak_host_id

Id of the host the key is authorized to

ak_host_management_state

Management state of the host of the authorized key

ak_host_tags

Tags attached to the host of the authorized key

ak_hostgroup

Name of host group that the authorized key is on. Only usable for filtering (-F).

ak_hostgroupid

Id of host group that the authorized key is on. Only usable for filtering (-F).

ak_hostname

Hostname of the host the key is authorized to

ak_id

Unique internal PrivX Key Manager id for authorized key

ak_is_external

Is the authorized key an external key? (i.e. not scanned by PKM)

ak_is_in_config

Authorized key is in SSH configuration

ak_is_internal_key

True if the authorized key is used internally by Key Manager for establishing agentless connections

ak_is_on_host

Authorized key is on a host

ak_job_id

Id of the job which acted on authorized key. Only usable for filtering (-F).

ak_key_age

Age of the authorized key

ak_key_comment

Comment field in SSH authorized key

ak_key_format

Format of the authorized key. One of openssh, secsh2, or ssh1

ak_key_location

Full path to file the authorized key is in

ak_key_options

Options for the authorized key. Only usable for output formatting (-C).

ak_key_owner_id

Internal id of the user owning the authorized key

ak_must_be_on_host

Authorized key must be on a host

ak_notes

Notes for the authorized key

ak_parent_job_id

Id of the parent job whose child job acted on authorized key. Only usable for filtering (-F).

ak_pending_key_operation

Pending authorized key operation

ak_product

Product of authorized key

ak_reason

Authorization reason specified by the user when the authorization was created

ak_signoff_date

Date when the authorized key's latest sign-off was done.

ak_signoff_identity

Identity of the party signing off the authorized key

ak_signoff_state

Sign-off state of the authorized key

ak_status

Status of the authorized key

ak_tags

Tags attached to the authorized key

ak_user_os_uid

OS uid of the account that owns the authorized key

ak_username

Username of the authorized key owner

authorized_key

Authorized key. Only usable for output formatting (-C).

black_listed

Key is black listed

date_modified

Date when a modification to any key of an authorization was made. Only usable for filtering (-F).

fingerprint_babble

Fingerprint of key in Bubble Babble format

fingerprint_openssh

Fingerprint of key in OpenSSH format

fingerprint_sha256

Fingerprint of key in OpenSSH SHA256 format

fingerprint_ssh1

Fingerprint of key in SSH1 format

id

The unique ID of the fingerprint

key_algorithm

Public key Algorithm

key_label

User defined label for authorization

key_size

Key length in bits

management_state

Management state of the fingerprint. Only usable for filtering (-F).

pk_applications

List of application instances the private key is associated with

pk_audit_ids

List of audit event id:s for the private key. Only usable for output formatting (-C).

pk_checksum

Checksum of the private key file of the private key

pk_custom1

Custom field 1 for the private key

pk_custom2

Custom field 2 for the private key

pk_custom3

Custom field 3 for the private key

pk_date_created

Date when the private key was created or first seen on a host

pk_date_modified

Date when a modification to any private key of an authorization was made. Only usable for filtering (-F).

pk_external_key_owner_id

PrivX Key Manager id of the external user owning the private key

pk_host_classification

Classification of the host of the private key

pk_host_id

Id of the host the private key is on

pk_host_management_state

Management state of the host of the private key

pk_host_tags

Tags attached to the host of the private key

pk_hostgroup

Name of host group that the private key is on. Only usable for filtering (-F).

pk_hostgroupid

Id of host group that the private key is on. Only usable for filtering (-F).

pk_hostname

Hostname of the host the private key is on

pk_id

Unique internal PrivX Key Manager id for private key

pk_is_external

Is the private key an external key? (i.e. not scanned by PKM)

pk_is_in_config

Key is in SSH configuration

pk_is_on_host

Private key is on a host

pk_job_id

Id of the job which acted on private key. Only usable for filtering (-F).

pk_key_age

Age of the private key

pk_key_comment

Comment field in SSH key

pk_key_format

Format of the private key. One of openssh, secsh2, or ssh1

pk_key_owner_id

Internal id of the user owning the private key

pk_must_be_on_host

Private key must be on a host

pk_notes

Notes for the private key

pk_parent_job_id

Id of the parent job whose child job acted on private key. Only usable for filtering (-F).

pk_passphrase_protected

Flag to specify whether the private key file of the private key is passphrase protected

pk_pending_key_operation

Pending key operation

pk_private_key_location

Full path to file the private key is in

pk_product

Product of authorized key

pk_signoff_date

Date when the private key's latest sign-off was done.

pk_signoff_identity

Identity of the party signing off the private key

pk_signoff_state

Sign-off state of the private key

pk_status

Status of the key

pk_tags

Tags attached to the private key

pk_user_os_uid

OS uid of the account that owns the private key

pk_username

Username of the private key owner

private_key

Private key. Only usable for output formatting (-C).

The following example displays all authorizations from server01.example.com to server02.example.com

$ ssh-mgr-client list-authorizations -F \
"pk_hostname=server01.example.com&&ak_hostname=server02.example.com"

To display all the authorizations from the hosts belonging to Test Hosts host group, to the hosts belonging to Production Hosts host group:

$ ssh-mgr-client list-authorizations -F \
"pk_hostgroup='Test Hosts'&&ak_hostgroup='Production Hosts'"

Note that to display the authorizations going in the opposite direction, you must switch the source and destination filter values:

$ ssh-mgr-client list-authorizations -F \
"pk_hostgroup='Production Hosts'&&ak_hostgroup='Test Hosts'"

Listing authorizations that were modified in October 2014:

$ ssh-mgr-client list-authorizations -F 'date_modified=2014-10'

To list authorizations that were modified later than 2014-10-10T12:00:00 (in the time zone of the command-line client user):

$ ssh-mgr-client list-authorizations -F 'date_modified>2014-10-10T12:00:00'

Listing authorizations that were modified during the time from the beginning of September to the end of November 2014 (UTC):

$ ssh-mgr-client list-authorizations -F \
'date_modified=2014-09T00:00:00+00:00..2014-11T23:59:59+00:00'

note

The list-authorizations command typically lists only the active authorizations. However, when filtering with date_modified, all authorizations from the given time range are displayed.

When filtering with date_modified, you can display the key statuses of the authorizations by enabling ak_status and pk_status in the output:

$ ssh-mgr-client list-authorizations -F 'date_modified>2014-10-10T12:00:00' \
-C ak_status,pk_status,...

For more information about filtering by time ranges, see Filtering by Modified Date.

list-authorized-keys

Syntax:

ssh-mgr-client list-authorized-keys [options] [-F <filter>] [-vvv] [-U <url>] [-o <format>] \
[-C <columns>] [-H] [-O <sort-order>] [-S <start-from>] [-M <max-results>] [-E <delim>] [-B]

The default command lists all the authorized keys in the managed environment:

$ ssh-mgr-client list-authorized-keys

The following columns can be used for filtering (-F) and output formatting (-C).

active_pk_count

Number of active private keys sharing the same fingerprint. Only usable for filtering (-F).

active_request

Active request for this key. Only usable for output formatting (-C).

application_id

Application instance id the key is associated with. Only usable for output formatting (-C).

applications

List of application instances the key is associated with

audit_ids

List of audit event id:s for this key. Only usable for output formatting (-C).

authorization_file_attrs

Attributes of the authorization file. Only usable for output formatting (-C).

authorization_file_location

Location of the authorization file

authorization_file_sharing

Sharing status of the authorization file

black_listed

Key is black listed

changes_on_host

List of changes on host for this key. Only usable for output formatting (-C).

custom1

Custom 1 field for the key

custom2

Custom 2 field for the key

custom3

Custom 3 field for the key

date_audit_ids

Date filter for audit events id:s for this key. Only usable for filtering (-F).

date_created

Date when the key was created or first seen by PrivX Key Manager

date_last_used

Date the key was last used to log in

date_modified

Date when a modification to an authorized key was made. Only usable for filtering (-F).

external_key_owner_id

PrivX Key Manager id of the external user owning the key

fingerprint_babble

Fingerprint of key in Bubble Babble format

fingerprint_id

The unique ID of the fingerprint

fingerprint_openssh

Fingerprint of key in OpenSSH format

fingerprint_sha256

Fingerprint of key in OpenSSH SHA256 format

fingerprint_ssh1

Fingerprint of key in SSH1 format

has_key_options

Are there options used with the authorized key. Only usable for filtering (-F).

host_classification

Classification of the host

host_id

Id of the host where the authorized key is located

host_management_state

Management state of the host

changes_on_host

List of changes on host for this key. Only usable for output formatting (-C).

custom1

Custom 1 field for the key

custom2

Custom 2 field for the key

custom3

Custom 3 field for the key

host_tags

Tags attached to the host of the key

hostgroup

Name of host group that the authorized key is on. Only usable for filtering (-F).

hostgroupid

Id of host group that the authorized key is on. Only usable for filtering (-F).

hostname

Host where the authorized key is located

id

Internal PrivX Key Manager id for authorized key

is_external

Is this an external key? (i.e. not scanned by PKM)

is_in_config

Key is in SSH configuration

is_internal_key

True if the key is used internally by Key Manager for establishing agentless connections

is_on_host

Key is on a host

is_requestless

There are no requests entered for this key. Only usable for filtering (-F).

job_id

Id of the job which acted on the key. Only usable for filtering (-F).

key_age

Age of the key

key_algorithm

Cryptographic algorithm of the key

key_comment

Comment field in SSH key

key_data

Public part of the key in OpenSSH format

key_file_attrs

Attributes of the authorized key file. Only usable for output formatting (-C).

key_format

Format of the key. One of openssh, secsh2, or ssh1

key_label

Label given to the key

key_location

Location of the authorized key file

key_options

Options used with the authorized key. Only usable for output formatting (-C).

key_owner

Human readable account that owns the key. Only usable for output formatting (-C).

key_owner_id

Internal PrivX Key Manager id of the user owning the key

key_owner_state

Key owner account state on the host

key_sharing

Sharing status of the authorized key file

key_size

Size of key in bits (e.g 768, 1024, 2048)

last_used

Time since the key was last used to log in

latest_request

Latest completed request for this key. Only usable for output formatting (-C).

management_state

Management state of the key's fingerprint

must_be_on_host

Key must be on a host

not_after

End of the validity period of the key

not_before

Start of the validity period of the key

notes

Notes for the key

openssh_key_options

Options used with the authorized key in OpenSSH format. Only usable for output formatting (-C).

parent_job_id

Id of the parent job whose child job acted on the key. Only usable for filtering (-F).

pending_key_operation

Pending key operation

policy_violation_id

List of policy rule ids this key is currently violating. Only usable for filtering (-F).

policy_violation_score

Combined numeric severities of the policies this key is currently violating

policy_violations

List of policy rules this key is currently violating

product

Product of key

reason

Reason for authorization

request_state

Request state for this key. Only usable for filtering (-F).

requests

Requests entered for this key by id. Only usable for filtering (-F).

signoff_date

Date when the latest sign-off was done.

signoff_identity

Identity of the party signing off the key

signoff_state

Sign-off state of the authorized key

status

Status of the key

tags

Tags attached to the key

user_os_uid

OS uid of the account that owns the key

username

OS username of the account that owns the key

For example, to list all the authorized keys that are on the host example.server.com:

$ ssh-mgr-client list-authorized-keys -F "hostname=example.server.com"

To display all the authorized keys with no matching private keys in the managed environment:

$ list-authorized-keys -F active_pk_count=0

As another example, to display the user name, status, and key size for authorized keys that are on example.server.com:

$ ssh-mgr-client list-authorized-keys -C "username,status,key_size" -F \
"hostname=example.server.com"

To list all the authorized keys that were created or otherwise modified by a certain job or its child jobs:

$ ssh-mgr-client list-authorized-keys -F parent_job_id=60760

list-private-keys

Syntax:

ssh-mgr-client list-private-keys [options] [-F <filter>] [-vvv] [-U <url>] [-o <format>] \
[-C <columns>] [-H] [-O <sort-order>] [-S <start-from>] [-M <max-results>] [-E <delim>] [-B]

The default command lists the private keys in the managed environment:

$ ssh-mgr-client list-private-keys

The following columns can be used for filtering (-F) and output formatting (-C):

active_ak_count

Number of active authorized keys sharing the same fingerprint. Only usable for filtering (-F).

active_request

Active request for this key. Only usable for output formatting (-C).

application_id

Application instance id the key is associated with. Only usable for output formatting (-C).

applications

List of application instances the key is associated with

audit_ids

List of audit event id:s for this key. Only usable for output formatting (-C).

black_listed

Key is black listed

changes_on_host

List of changes on host for this key. Only usable for output formatting (-C).

checksum

Checksum of the private key file of the private key

custom1

Custom 1 field for the key

custom2

Custom 2 field for the key

custom3

Custom 3 field for the key

date_audit_ids

Date filter for audit events id:s for this key. Only usable for filtering (-F).

date_created

Date when the key was created or first seen by PrivX Key Manager#### date_deleted Date when the key was removed

date_modified

Date when a modification to a private key was made. Only usable for filtering (-F).

external_key_owner_email

Email of the external user owning the key

external_key_owner_id

PrivX Key Manager id of the external user owning the key

fingerprint_babble

Fingerprint of key in Bubble Babble format

fingerprint_id

The unique ID of the fingerprint

fingerprint_openssh

Fingerprint of key in OpenSSH format

fingerprint_sha256

Fingerprint of key in OpenSSH SHA256 format

fingerprint_ssh1

Fingerprint of key in SSH1 format

host_classification

Classification of the host

host_id

Id of the host where the key is located

host_management_state

Management state of the host

host_tags

Tags attached to the host of the key

hostgroup

Name of host group that the private key is on. Only usable for filtering (-F).

hostgroupid

Id of host group that the private key is on. Only usable for filtering (-F).

hostname

Hostname of the host that the key is on

id

Internal PrivX Key Manager id for private key

is_external

Is this an external key? (i.e. not scanned by PKM)

is_in_config

Key is in SSH configuration

is_on_host

Key is on a host

is_requestless

There are no requests entered for this key. Only usable for filtering (-F).

job_id

Id of the job which acted on the key. Only usable for filtering (-F).

key_age

Age of the key

key_algorithm

Cryptographic algorithm of the key

key_comment

Comment field in SSH key

key_data

Public part of the key in OpenSSH format

key_deleted_age

Time since the key was deleted

key_format

Format of the key. One of openssh, secsh2, or ssh1

key_label

Label given to the key

key_location

Location of the public key file of the private key

key_owner

Human readable account that owns the key. Only usable for output formatting (-C).

key_owner_id

Internal PrivX Key Manager id of the user owning the key

key_owner_state

Key owner account state on the host

key_sharing

Sharing status public key file of the private key

key_size

Size of key in bits (e.g 768, 1024, 2048)

latest_request

Latest completed request for this key. Only usable for output formatting (-C).

management_state

Management state of the key's fingerprint

must_be_on_host

Key must be on a host

not_after

End of the validity period of the key

not_before

Start of the validity period of the key

notes

Notes for the key

parent_job_id

Id of the parent job whose child job acted on the key. Only usable for filtering (-F).

passphrase_protected

Flag to specify whether the private key file of the private key is passphrase protected

passphrase_status

Status of the private key passphrase

pending_key_operation

Pending key operation

policy_violation_id

List of policy rule ids this key is currently violating. Only usable for filtering (-F).

policy_violation_score

Combined numeric severities of the policies this key is currently violating

policy_violations

List of policy rules this key is currently violating

private_key_backup_location

Location of the private key backup file of the private key

private_key_file_attrs

Attributes of the private key file of private key. Only usable for output formatting (-C).

private_key_location

Location of the private key file of the private key

private_key_sharing

Sharing status private key file of the private key

product

Product of key

public_key_file_attrs

Attributes of the public key file of private key. Only usable for output formatting (-C).

request_state

Request state for this key. Only usable for filtering (-F).

requests

Requests entered for this key by id. Only usable for filtering (-F).

signoff_date

Date when the latest sign-off was done.

signoff_identity

Identity of the party signing off the key

signoff_state

Sign-off state of the private key

status

Status of the key

tags

Tags attached to the key

user_os_uid

OS uid of the account that owns the key

username

OS username of the account that owns the key

For example, to list all the keys that are on the host example.server.com:

$ ssh-mgr-client list-private-keys -F hostname=example.server.com

To find all the private keys with no known authorizations in the managed environment:

$ list-private-keys -F active_ak_count=0

As another example, to display the user name, status, and key size for private keys that are on example.server.com:

$ ssh-mgr-client -C "username,status,keysize" \
list-private-keys -F "hostname=example.server.com"

To list all the private keys that were created or otherwise modified by a certain job or its child jobs:

$ ssh-mgr-client list-private-keys -F parent_job_id=60760

list-request-approvals

Syntax:

ssh-mgr-client list-request-approvals [options] [-F <filter>] \
[-X <exclude-filter>] [-vvv] [-U <url>] [-o <format>] [-C <columns>] \
[-H] [-O <sort-order>] [-S <start-from>] [-M <max-results>] [-E <delim>] [-B]

List approvals stored in the Key Manager system. This includes both the approvals that have already been decided, and the approvals that are still waiting for decision.

The default command lists all the approvals stored in the Key Manager system:

$ ssh-mgr-client list-request approvals

1,Example Application,1,approved,accept_keys,admin\
,,,alice,2016-03-16T12:48:25.280Z,2016-03-16T12:51:05.677Z
2,Example Application,1,pending,accept_keys,admin\
,,,,2016-03-16T12:56:55.441Z,
3,Example Application,1,approved,remove_keys,admin\
,,,alice,2016-03-16T12:56:55.459Z,2016-03-16T12:59:52.650Z
3,Example Application,1,approved,remove_keys,admin\
,,,admin,2016-03-16T12:56:55.461Z,2016-03-16T13:05:47.996Z
...

The following columns can be used for filtering (-F) and output formatting (-C).

application

Application this request approval is originating from.

approval_class

Approval class (who can approve this).

approval_type

Approval type.

approving_admin

Approving admin (set at approval time).

approving_owner

Approving owner (set at approval time).

approving_owner_type

Approving owner role (set at approval time).

date_created

Date when the approval was created.

date_decided

Date when the approval was decided.

id

Internal PrivX Key Manager id for request approval.

is_active

Is actively pending for an approval. Only usable for filtering (-F).

request_id

Request id.

request_requester

Requests requesters email.

stage

Stage.

status

Status of approval.

Example for displaying all the approvals belonging to a single action request:

$ ssh-mgr-client list-request approvals -H -F "request_id=999"

tip

The user who decided the request is displayed by the fields approving_owner and approving_admin (depending on the approving_owner_type). If the approval has not been decided, both of these fields are empty.

list-requests

Syntax:

ssh-mgr-client list-requests [options] [-F <filter>] [-vvv] [-U <url>] \
[-o <format>] [-C <columns>] [-H] [-E <delim>] [-B]

The default command lists all the authorization and signoff requests in the Key Manager system:

$ ssh-mgr-client list-requests

The following columns can be used for filtering (-F) and output formatting (-C).

application

Primary application this request is associated with.

approval_stage

Current approval stage.

approving_admin

Username of the admin who gave the final approvalfor the request.

auth_key_id

Internal PrivX Key Manager id of the authorized key.

cancelled

Cancelled date.

comment

Comment from the requester. Only usable for output formatting (-C).

created

Creation date.

destination

Request destination users in readable format. Only usable for output formatting (-C).

destination_applications

Destination applications for this request.

extra_data

Extra data supplied by the requester. Only usable for output formatting (-C).

finished

Finished date.

id

Internal PrivX Key Manager id for request.

initiating_admin

Username of the admin who created the request.

job_options

Job options for requests. Only usable for output formatting (-C).

pending_approvals

Pending approvals count for the request. Only usable for output formatting (-C).

pk_authorizations

User IDs to be authorized. Only usable for output formatting (-C).

private_key_fingerprint

Fingerprint of the private key in OpenSSH format.

private_key_id

Internal PrivX Key Manager id of the private key.

related_applications

All applications this request is associated with. Only usable for output formatting (-C).

requester

Username of requester.

requester_id

Internal PrivX Key Manager id of the requester.

rollback_data

Rollback data for key rollback requests. Only usable for output formatting (-C).

source

Request source users in readable format. Only usable for output formatting (-C).

source_applications

Source applications for this request.

src_dst_pairs

Source-destination pairs in request. Only usable for output formatting (-C).

state

State of request.

tags

Tags for request. Only usable for output formatting (-C).

total_approvals

Total approvals count for the request. Only usable for output formatting (-C).

type

Request type.

updated

Last update date.

wait_cond

Currently waiting for.

wait_target

Waiting target.

For example, to list all the authorization requests that are awaiting handling:

$ ssh-mgr-client list-requests -H -F \
"state=initialized&&type=authorization_request"

manage-authorized-keys

Syntax:

ssh-mgr-client [-v] [-U <url>] manage-authorized-keys (-F <filter> | -i <id>)

Switches the (management) state of the selected authorized keys to managed. Any keys sharing the fingerprints of the selected keys will also be switched to the managed state.

You can select an authorized key by providing its ID (-i). Alternatively, you can select authorized keys using filters (-F). For filtering, you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

For example, to manage an authorized key with a certain ID:

$ ssh-mgr-client manage-authorized-keys -i 17

As another example, to manage all the authorized keys on a certain host:

$ ssh-mgr-client manage-authorized-keys -F "hostname=example.server.com"

manage-private-keys

Syntax:

ssh-mgr-client [-v] [-U <url>] manage-private-keys (-F <filter> | -i <id>)

Switches the (management) state of the selected private keys to managed. Any keys sharing the fingerprints of the selected keys will also be switched to the managed state.

You can select a private key by providing its ID (-i). Alternatively, you can select authorized keys using filters (-F). For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

For example, to manage a private key with a certain ID:

$ ssh-mgr-client manage-private-keys -i 17

As another example, to manage all the private keys on a certain host:

$ ssh-mgr-client manage-private-keys -F "hostname=example.server.com"

modify-authorized-key

Syntax:

ssh-mgr-client modify-authorized-key [options] \
(-I <id-filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Set the custom-data fields of the selected authorized key.

In input data (-d), specify the fields and their new values in columnname=value format. Any existing values for the specified fields are overwritten using the new values. Select the authorized key using its ID (-i), or using matching ID filters (-I). For ID filtering, you can use the same attributes that are available for the list-authorized-keys command (described in list-authorized-keys).

For a similar command that can target multiple authorized keys at once, see edit-authorized-keys.

Names of the fields that can be modified with this command:

notes
custom1
custom2
custom3

For example, setting custom1 to Example value, and setting custom2 to value,value2:

$ ssh-mgr-client modify-authorized-key -d \
'custom1=Example value,custom2=value,value2' -i 999

modify-private-key

Syntax:

ssh-mgr-client modify-private-key [options] \
(-I <id-filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Set the custom-data fields of the selected private key.

In input data (-d), specify the fields and their new values in columnname=value format. Any existing values for the specified fields are overwritten using the new values. Select the private key using its ID (i), or using matching ID filters (-I). For ID filtering, you can use the same attributes that are available for the list-private-keys command (described in list-private-keys).

For a similar command that can target multiple private keys at once, see edit-private-keys.

Names of the fields that can be modified with this command:

notes
custom1
custom2
custom3

For example, setting custom1 to Example value, and setting custom2 to value,value2:

$ ssh-mgr-client modify-private-key -d \
'custom1=Example value,custom2=value,value2' -i 999

provide-private-key-passphrase

Syntax:

ssh-mgr-client provide-private-key-passphrase -d <data> \
[options] (-F <filter> | -i <id>) [-vvv] [-U <url>]

Provide the passphrase for the selected private key(s). The provided passphrase is immediately stored in the Key Manager system.

In input data (-d), specify the passphrase of the selected keys. You can select a private key using its ID (-i). Alternatively, you can select multiple keys using filters (-F). For ID filtering, you can use the same attributes that are available for the list-private-keys command (described in list-private-keys).

Required data:

passphrase

The passphrase of the selected keys.

Example for providing the passphrase of one private key:

$ ssh-mgr-client provide-private-key-passphrase -i 99 \
-d 'passphrase=example_passphrase'

Example for selecting private keys using filters:

$ ssh-mgr-client provide-private-key-passphrase -F "username=alice" \
-d 'passphrase=example_passphrase'

register-external-private-key

Syntax:

ssh-mgr-client [global_options] register-external-private-key -d <data>

Add information about an external private key to the Key Manager environment.

Example:

$ ssh-mgr-client register-external-private-key \
-d 'email=test@example.com,key_data="ssh-rsa ..."' 

relocate-user-keys

Syntax:

ssh-mgr-client [global_options] relocate-user-keys (-F <filter> | -i <id>) \
(-d <data>) [-o <format>] [-B] [-T <timeout>] [-p <priority>] \
[--allow-actions-on-shared-keys]

Relocates user keys to the specified central directories on their respective hosts.

To relocate user keys using this command, you must specify the following parameters:

The hosts, on which to perform key centralization. Select target hosts using filters (-F), or by providing the ID of a host (-i).

For example, to select the host with the ID value of 81, use the -i option:
```
$ ssh-mgr-client relocate-user-keys -i 81
```
For example, to select all Linux hosts, the name of which begins with example.server you could specify the following filter attributes:
```
$ ssh-mgr-client relocate-user-keys -F "os=linux&&hostname=example.server*" ...
```
The attributes that are available for filtering hosts are similar to those used by the list-hosts command. You can quickly list the attributes by running:
```
$ ssh-mgr-client help list-hosts
```
For more information about the available attributes, see the list-hosts command documentation at list-hosts.
The central directory path, under which authorized keys are moved. The path is specified using the data attribute auth_keys_dir.

The given path musts contain a token for matching user names (%u or %U) or for matching home directories (%h or %D). Key Manager relocates user keys in sub-directories (under the central directory path) according to the keywords.

For example, if the host contains the users alice and bob, who have home directories at /home/alice and /home/bob respectively, and the centralized directory for authorized keys is provided as /opt/ssh_keys/%u, alice's and bob's authorized keys would be moved under the directories /opt/ssh_keys/alice and /opt/ssh_keys/bob respectively.

If in the previous example, if %h were used instead of %u, the authorized keys would have been placed under the directories /opt/ssh_keys/home/alice and /opt/ssh_keys/home/bob instead.
The key-relocation stage(s) to be performed. By default the command copies authorized keys to the auth_keys_dir (stage 1). To also update the SSH-server configurations, add update_configs=True (stage 2). To also delete old authorized keys, add remove_old_keys=True (stage 3).

The command launches a relocate-user-keys job to relocate the keys on the selected hosts. The requested key-relocation stages are completed when the job finishes.

As another example, copying keys and updating configurations to use those new keys:

$ ssh-mgr-client relocate-user-keys -F "hostname=example.server*" -d \
auth_keys_dir=/opt/ssh_keys/%u,update_configs=True,\
old_key_tags=old_keys,new_key_tags=new_keys

On hosts where key relocation has already been performed, you can relocate to another location using the force option:

$ ssh-mgr-client relocate-user-keys -F "hostname=example.server*" -d \
auth_keys_dir=/opt/ssh_keys2/%u,force=True,\
old_key_tags=old_keys,new_key_tags=new_keys

note

To resume key relocation on hosts where some key-relocation stages have already been performed, use the continue-key-relocation command instead (described in continue-key-relocation).

remove-authorizations

Syntax:

ssh-mgr-client remove-authorizations [options] \
(-d <data> | -f <file>) [-vvv] [-U <url>] [-o <format>] \
[-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Remove authorizations established between user accounts in the managed environment. The source and target accounts must be on hosts that are in the managed state.

caution

Key Manager cannot be used for restoring removed authorizations. We recommend that you review any authorizations before removing them. For example, to determine the usage of an authorization, you can use Key Manager to review the key activity associated to its authorized keys.

To remove authorizations using this command, you must identify the source and the destination accounts of the authorization. Identify the accounts using the username@hostname format. Similar to the syntax used with the ssh command.

You must provide the following data to identify the authorization source and destination:

from

The source account in username@hostname format.

to

The destination account in username@hostname format.

When specifying source accounts, the following wildcards can be used for specifying source accounts:

from=* matches all source accounts.
from=*@host matches all the source accounts on the given host.
from=user@* matches all the source accounts with the given user name.

The command launches a remove-authorization job to delete the authorized-key component of the matching authorizations. The authorizations are deleted and no longer usable as soon as the job finishes.

For example, to remove the authorization that authorizes the sourceuser account at source.host.com to the destinationuser account at destination.host.com:

$ ssh-mgr-client remove-authorizations -d \
from=sourceuser@source.host.com,to=destinationuser@destination.host.com

You can also remove authorizations between multiple source and destination accounts. For example, the following command removes the authorizations between each source and destination account:

$ ssh-mgr-client remove-authorizations -d \
'from=user@*,to=user@[host3,host4]'

It is also possible to remove all the authorizations that authorize to certain accounts:

$ ssh-mgr-client remove-authorizations -d \
'to=user@[host3,host4]'

You can provide the information from a text file as well, using the -f option. Using this approach, it is possible to remove multiple authorizations with a single command:

$ ssh-mgr-client remove-authorizations -f remove_auths.txt

An example of what the contents of remove_auths.txt could look like:

from,to
username01@bastion01.example.com,username01@pdserver03.example.com
username02@pdserver02.example.com,username02@dbwest.example.com
username01@bastion01.example.com,username02@tserver01.example.com

remove-authorized-key-options

Syntax:

ssh-mgr-client remove-authorized-key-options -d <data> [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-o <format>] [-B] \
[-T <timeout>] [-t <tags>] [-p <priority>]

Remove specified options from the selected authorized keys.

Select authorized keys using filters (-F). Alternatively, you can select a single authorized key using its ID (-i). For authorized-key filtering, you can use the same filter criteria that are available for the list-authorized-keys command (described in list-authorized-keys).

command

The forced command for this authorized key.

allow-from

An IP addresses, or a network, where the authorized keys can be used from.

deny-from

An IP addresses, or a network, from which using the authorized keys is denied.

from

A list of IP addresses and/or networks that defines where the authorized key can be used from. Used for specifying both allowed and denied addresses.

The command launches set-authorized-key-options jobs to modify the options of the selected keys. The new options are set as soon as the jobs finish.

Note that this command produces the exact opposite results to using add-authorized-key-options with identical arguments (for more information about the add-authorized-key-options command, see add-authorized-key-options).

For example, to remove multiple allow-from options and the no-port-forwarding option from all authorized keys on a certain host:

$ ssh-mgr-client remove-authorized-key-options -d \
allow-from='192.0.2.100',allow-from='192.0.2.14*',no-port-forwarding -F \
"hostname=server01.example.com"

$ ssh-mgr-client remove-authorized-key-options -d \
'from="192.0.2.100,192.0.2.101,!192.0.2.102",no-agent-forwarding' -i 110

$ ssh-mgr-client remove-authorized-key-options -d \
'command="ls /some/directory"' -i 110

If you need to specify double quotes inside the command restriction, these must be escaped. For example, to specify the command restriction echo "Hello world":

$ ssh-mgr-client remove-authorized-key-options -d \
command='"echo \"Hello world\""' -i 110

tip

You can use the set-authorized-key-options command to remove all the options from the selected authorized keys. For example:

$ ssh-mgr-client set-authorized-key-options -d '' \
-F hostname=server01.example.com

For more information about the set-authorized-key-options command, see set-authorized-key-options.

remove-authorized-keys

Syntax:

ssh-mgr-client remove-authorized-keys [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-o <format>] \
[-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Removes the selected authorized keys.

You can select an authorized key by providing its ID (-i). Alternatively, you can select authorized keys using filters (-F).

The command launches remove-authorization jobs to remove the selected keys. The keys are removed (and no longer usable for authentication) as soon as the jobs finish.

For example, if you want to remove the authorized key with the keyid of 12:

$ ssh-mgr-client remove-authorized-keys -i 12

You can also remove authorized keys using filters. The available attributes for specifying authorized keys are the same as those available for the list-authorized-keys command (see list-authorized-keys).

For example, to remove authorized keys by fingerprint:

$ ssh-mgr-client remove-authorized-keys -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

remove-private-key-backup

Syntax:

ssh-mgr-client remove-private-key-backup [options] (-F <filter> | -i <id>) \
[-vvv] [-U <url>] [-o <format>] [-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Remove the backup files of selected private keys (backups are created whenever a key is removed using Key Manager).

Select a private key using its ID (-i). Alternatively, you can select multiple private keys using filters (F). For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

note

After you remove the backup files of a private key, Key Manager will be unable to restore that private key.

tip

Integrate this command to your automated system scripts in order to periodically delete backups that are, for example, older than a specified time period.

Example for removing the backups of one private key:

$ ssh-mgr-client remove-private-key-backup -i 99

As another example, to delete the backups of those private keys that have been removed a certain time ago:

$ ssh-mgr-client remove-private-key-backup -F "key_deleted_age>20d"

In addition to relative times, you can also use a specified date:

$ ssh-mgr-client remove-private-key-backup -F "date_deleted<'2015-07-18 12:00:00'"

remove-private-keys

Syntax:

ssh-mgr-client remove-private-keys [options] (-F <filter> | -i <id>) [-d  <data>] \
[-vvv] [-U <url>] [-o <format>] [-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Removes the selected private keys. You can select a private key by providing its ID (-i). Alternatively, you can select multiple private keys using filters (-F). For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

The command launches remove-authorization jobs to remove the selected keys. The keys are removed (and no longer usable for authentication) as soon as the jobs finish.

caution

Be careful when removing private keys. Key Manager is unable to recover private keys after they are removed.

If you remove a private key by mistake, you can restore the authorizations from that key by renewing keys, for example, using the renew-private-keys command (described in renew-private-keys).

For example, to remove the private key with the id value of 12:

$ ssh-mgr-client remove-private-keys -i 12

To remove the private keys matching to an OpenSSH or bubble-babble fingerprint, use the fingerprint_openssh or fingerprint_babble attribute:

$ ssh-mgr-client remove-private-keys -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

renew-private-keys

Syntax:

ssh-mgr-client renew-private-keys [options] (-F <filter> | -i <id>) [-d <data>] \
[-vvv] [-U <url>] [-o <format>] [-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Renew the authorizations established with the selected private keys. You can select a private key by providing its ID (-i). Alternatively, you can select multiple private keys using filters (-F). For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

Optional data:

stage_period

Set this value to perform staged key renewal with the specified stage period. Value is to be specified in years (y), months (m), weeks (w), days (d), hours (H), minutes (M), or seconds (S). Set to 0 for an unlimited stage period. If no unit is specified (and only a numerical value is provided), the time is interpreted as seconds.

key_size

The size of the new keys in bits. Defaults to the size of the original keys.

key_alg

Algorithm used for generating the new keys. Possible values are rsa, dsa, ecdsa, and ed25519. Defaults to the algorithm of the original keys.

For more information about the key_alg option, see delete-host.

passphrase

The passphrase that is set for the new private keys. If unspecified, or if set to keep, the new keys inherit the passphrase from the old keys (only if the passphrase is stored in Key Manager). Set to random to set a random passphrase for the new private keys. Set to none to set a blank passphrase for the new private keys.

note

Before renewing any keys, we recommend that you familiarize yourself with the features and the limitations related to key renewal. For a list of known key-renewal features and limitations, see the PrivX Key Manager Product Description or the PrivX Key Manager Installation Manual.

The command launches renew-keys jobs to renew the target keys. The keys are renewed as soon as the jobs finish.

For example, to renew the authorizations where the private-key id value is 12:

$ ssh-mgr-client renew-private-keys -i 12

To renew an authorization matching to an OpenSSH or bubble-babble fingerprint, use the fingerprint_openssh or fingerprint_babble attribute:

$ ssh-mgr-client renew-private-keys -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

Renewing the user keys of multiple authorizations while also specifying the new key length and algorithm:

$ ssh-mgr-client renew-private-keys -F "hostname=server01.example.com" \
-d key_size=2048,key_alg=rsa

To perform staged key renewal, specify a stage period for the command. For example:

$ ssh-mgr-client renew-private-keys -d stage_period=2m -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

You can also specify compound time values for the stage period:

$ ssh-mgr-client renew-private-keys -d stage_period=1H30M -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

tip

Specify target keys using a fingerprint filter to ensure that all copies of the private key are renewed.

restore-authorized-keys

Syntax:

ssh-mgr-client restore-authorized-keys [options] (-F <filter> | -i <id>) [-vvv] \
[-U <url>] [-o <format>] [-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Restores the selected missing and deleted authorized keys.

You can select an authorized key by providing its ID (-i). Alternatively, you can select multiple authorized keys using filters (-F). For filtering, you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

The command launches add-authorization jobs for restoring the selected authorized keys. The authorized keys are restored and ready for use as soon as the jobs finish.

For example, to restore an authorized key with a given ID:

$ ssh-mgr-client restore-authorized-keys -i 99

To restore an authorized key by its OpenSSH or bubble-babble fingerprint, use the fingerprint_openssh or fingerprint_babble attribute:

$ ssh-mgr-client restore-authorized-keys -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

restore-private-keys

Syntax:

ssh-mgr-client restore-private-keys [options] (-F <filter> | -i <id>) [-vvv] \
[-U <url>] [-o <format>] [-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Restores the selected deleted private keys.

You can select a private key by providing its ID (-i). Alternatively, you can select multiple private keys using filters (-F). For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

The command launches restore-private-key jobs for restoring the selected private keys. The private keys are restored and ready for use as soon as the jobs finish.

For example, to restore a private key with a given ID:

$ ssh-mgr-client restore-private-keys -i 99

To restore a private key by its OpenSSH or bubble-babble fingerprint, use the fingerprint_openssh or fingerprint_babble attribute:

$ ssh-mgr-client restore-private-keys -F \
"fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

rollback-key-relocation

Syntax:

ssh-mgr-client [global_options] rollback-key-relocation (-F <filter> | -i <id>)
[-d <data>] [-o <format>] [-B] [-T <timeout>] [-p <priority>]

Roll back the SSH server configurations to a point in time before a key-relocation action. Note that this command only reverts stage-2 relocations, keys on the target hosts are not modified.

Select a target host by providing its ID (-i). Alternatively, you can select multiple target hosts using filters (-F).

By default, the command reverts the configurations to the point in time before the most recent key-relocation-configuration change. To roll back to a point in time before an earlier key-relocation-configuration change, specify the ID of an applicable key-relocation job.

For example, assume that stage-2 key relocation has been performed on a host (with host ID 99) multiple times, by the following job IDs:

1000
2000
3000

The default command would roll back the configuration to a point in time before job 3000 was performed:

$ ssh-mgr-client rollback-key-relocation -i 99

To roll back to a point in time before job 1000 was performed:

$ ssh-mgr-client rollback-key-relocation -i 99 -d 1000

caution

Rolling back a key relocation also undoes any other configuration changes made since the target key-relocation action. In most cases, any authorizations added to the target host(s) after the target key-relocation action will stop working.

set-authorized-key-options

Syntax:

ssh-mgr-client set-authorized-key-options -d <data> [options] (-F <filter> | -i <id>) \
[-vvv] [-U <url>] [-o <format>] [-B] [-T <timeout>] [-t <tags>] [-p <priority>]

Removes all existing options, then adds the options specified in the command arguments for the selected authorized keys.

caution

This command removes all existing options from the selected authorized keys. If you only want to replace authorized-key options of certain type(s), use the update-authorized-key-options command instead (described in update-authorized-key-options).

Select authorized keys using filters (-F). Alternatively, you can specify a single authorized key using its ID (-i). For filtering, you can use the same filter criteria that are available for the list-authorized-keys command (described in list-authorized-keys).

command

The forced command for this authorized key.

allow-from

An IP addresses, or a network, where the authorized keys can be used from.

deny-from

An IP addresses, or a network, from which using the authorized keys is denied.

from

A list of IP addresses and/or networks that defines where the authorized key can be used from. Used for specifying both allowed and denied addresses.

The command launches set-authorized-key-options jobs to modify the options of the selected keys. The new options are set as soon as the jobs finish.

caution

Ensure that the authorized-key options you specify are supported by the SSH Product that the selected keys belong to. Incorrect options may cause the selected keys to become unusable.

For example, to allow access from multiple addresses to all authorized keys on a certain host (and to remove all other options from those keys):

$ ssh-mgr-client set-authorized-key-options -d \
allow-from='192.0.2.100',allow-from='192.0.2.14*' -F \
"hostname=server01.example.com"

The command can also be used to conveniently remove all authorized-key options from the selected keys. To do this, provide blank data for the command:

$ ssh-mgr-client set-authorized-key-options -d ''\
-F "hostname=server01.example.com"

$ ssh-mgr-client set-authorized-key-options -d \
'from="192.0.2.100,192.0.2.101,!192.0.2.102",no-agent-forwarding' -i 110

$ ssh-mgr-client set-authorized-key-options -d \
'command="ls /some/directory"' -i 110

If you need to specify double quotes inside the command restriction, these must be escaped. For example, to specify the command restriction echo "Hello world":

$ ssh-mgr-client set-authorized-key-options -d \
command='"echo \"Hello world\""' -i 110

set-private-key-passphrase

Syntax:

ssh-mgr-client set-private-key-passphrase -d <data> [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>]

Set the passphrase of the selected keys.

In input data (-d), specify the passphrase that is to be set for the selected keys. Select a private key using its ID (-i). Alternatively, you can select multiple private keys using filters (-F). For filtering, you can use the same filter criteria that are available for the list-private-keys command (described in list-private-keys).

Required data:

passphrase

The passphrase that is to be set for the selected keys.

note

In order to change the passphrase of a key that is already passphrase-protected, the current passphrase of the key must be stored and verified in Key Manager. In other words, the passphrase_status of the key must be stored_verified.

The passphprase_status of private keys can be checked using the list-private-keys command (described in list-private-keys). The current passphrase of a private key can be provided and stored to Key Manager using the provide-passphrase command (described in provide-private-key-passphrase).

Example for setting the passphrase of one private key:

$ ssh-mgr-client set-private-key-passphrase -i 99 -d 'passphrase=example_passphrase'

Example for setting the passphrase of all the keys belonging to a certain user:

$ ssh-mgr-client set-private-key-passphrase -F "username=alice" -d 'passphrase=example_passphrase'

show-authorized-key

Syntax:

ssh-mgr-client show-authorized-key -i <id> [options] \
[-vvv] [-U <url>] [-o <format>] [-C <columns>]

Displays the authorized key with the given key ID.

For output formatting (-C), you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

Example:

$ ssh-mgr-client show-authorized-key -i 3

show-private-key-passphrase

Syntax:

ssh-mgr-client show-private-key-passphrase [options] (-F <filter> | -i <id>) \
[-vvv] [-U <url>] [-o <format>] [-t <tags>]

Display the passphrase of the selected private keys (if the passphrases are stored in the Key Manager system).

Select a private key by its ID (-i). Alternatively, you can specify filters (-F) for selecting multiple private keys. For filtering, you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

Usage examples:

$ ssh-mgr-client show-private-key-passphrase -i 99 -H

$ ssh-mgr-client show-private-key-passphrase -F "username=alice&&hostname=server01.example.com"

show-private-key

Syntax:

ssh-mgr-client [-v] [-U <url>] [-o <format>] [-C <columns>] show-private-key -i <id>

Displays the private key with the given key ID.

For output formatting (-C), you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

Example:

$ ssh-mgr-client show-private-key -i 3

signoff-accept-authorized-key

Syntax:

ssh-mgr-client signoff-accept-authorized-key [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>]

Immediately mark the selected authorized keys as accepted.

Select an authorized key using its authorized-key ID (-i). Alternatively, you can select multiple keys using filters (-F). For filtering, you can use the same attributes that are available for the list-authorized-keys command (described in list-authorized-keys).

note

This command immediately accepts the selected authorized keys, regardless of the approval policies that apply to those keys.

Example, accept all the keys belonging to a certain user on a certain host:

$ ssh-mgr-client signoff-accept-authorized-keys \
-F "hostname=server01.example.com&&username=alice"

signoff-reject-authorized-key

Syntax:

ssh-mgr-client signoff-reject-authorized-key [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>]

Immediately mark the selected authorized keys as rejected.

note

This command immediately rejects the selected authorized keys, regardless of the approval policies that apply to those keys.

Example, reject all the keys belonging to a certain user on a certain host:

$ ssh-mgr-client signoff-reject-authorized-keys \
-F "hostname=server01.example.com&&username=alice"

tag-authorized-keys

Syntax:

ssh-mgr-client tag-authorized-keys [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Tags selected authorized keys.

Specify the tag by the name of the tag. If the tag does not exist, it will be created automatically. You can select an authorized key using its ID. Alternatively, you can select multiple authorized keys using filters. For filtering (-F), you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

For example, to tag the authorized key that has the ID of 36, with the tag named to_be_renewed:

$ ssh-mgr-client tag-authorized-keys -i 36 -d tags="to_be_renewed"

tag-private-keys

Syntax:

ssh-mgr-client tag-private-keys [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Tags selected private keys.

Specify the tag by the name of the tag. If the tag does not exist, it will be created automatically. You can select a private key using its ID. Alternatively, you can select multiple private keys using filters. For filtering (-F), you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

For example, to tag the private key that has the ID of 36, with the tag named to_be_renewed:

$ ssh-mgr-client tag-private-keys -i 36 -d tags="to_be_renewed"

untag-authorized-keys

Syntax:

ssh-mgr-client untag-authorized-keys [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Removes a tag from the selected authorized key(s).

Specify the tag by the name of the tag. You can select an authorized key using its ID. Alternatively, you can select multiple authorized keys using filters. For filtering (-F), you can use the same attributes that are available for the list-authorized-keys command (see list-authorized-keys).

Example:

$ ssh-mgr-client untag-authorized-keys -i 36 -d tags="to_be_reviewed"

untag-private-keys

Syntax:

ssh-mgr-client untag-private-keys [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]

Removes a tag from the selected private key(s). Specify the tag by the name of the tag. You can select a private key using its ID. Alternatively, you can select multiple private keys using filters. For filtering (-F), you can use the same attributes that are available for the list-private-keys command (see list-private-keys).

Example:

$ ssh-mgr-client untag-private-keys -i 36 -d tags="to_be_reviewed"

update-authorized-key-options

Syntax:

ssh-mgr-client update-authorized-key-options -d <data> [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-o <format>] [-B] [-T <timeout>]

Replaces all existing options of the specified option type(s) with the options specified in the command arguments for the selected authorized keys.

caution

This command removes all existing options of the specified option type(s). If you only want to add additional options of certain type(s), without overwriting any existing options of the same type(s), use the add-authorized-key-options command instead (described in add-authorized-key-options).

command

The forced command for this authorized key.

allow-from

An IP addresses, or a network, where the authorized keys can be used from.

deny-from

An IP addresses, or a network, from which using the authorized keys is denied.

from

A list of IP addresses and/or networks that defines where the authorized key can be used from. Used for specifying both allowed and denied addresses.

The command launches set-authorized-key-options jobs to modify the options of the selected keys. The new options are set as soon as the jobs finish.

caution

Ensure that the authorized-key options you specify are supported by the SSH product that the selected keys belong to. Incorrect options may cause the selected keys to become unusable.

Note that this command cannot be used to remove authorized-key options that do not take arguments. Generally, this means that only allow-from, deny-from, from, and command restrictions can be updated. To remove other options, such as no-agent-forwarding and no-pty, use the remove-authorized-key-options command instead (described in remove-authorized-key-options).

For example, the following command removes the existing allow-from and command options from the selected authorized keys, and replaces them with the specified values. Existing deny-from options are left unmodified:

$ ssh-mgr-client update-authorized-key-options -d \
allow-from='192.0.2.100',command='"date"' -F \
"hostname=server01.example.com"

$ ssh-mgr-client update-authorized-key-options -d \
'from="192.0.2.100,192.0.2.101,!192.0.2.102",no-agent-forwarding' -i 110

$ ssh-mgr-client update-authorized-key-options -d \
'command="ls /some/directory"' -i 110

If you need to specify double quotes inside the command restriction, these must be escaped. For example, to specify the command restriction echo "Hello world":

$ ssh-mgr-client update-authorized-key-options -d \
command='"echo \"Hello world\""' -i 110

validate-authorized-key-options

Syntax:

ssh-mgr-client validate-authorized-key-options -d <data> [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-o <format>] [-B] [-T <timeout>]

Validate options for authorized keys. Returns an error if the options string is not in a legal format, or if the specified key options prevent access from addresses that have previously used the authorization (known source addresses, these are derived from key-activity logs).

This command can be used for validating authorized-key options before actually setting them for the selected keys.

Specify key options as input data (-d). Key options must be provided in the format specified by the SSH server that the selected keys belong to.

For example, if the specified key options prevent access from known source addresses:

]$ ssh-mgr-client validate-authorized-key-options -i 220 -d \
'allow-from=server01.example.com'

FAILURE validate_options auth_key#220: Key has been used from
address(es) which would be disallowed by the new from option(s).
MISSING: server02.example.com

By reviewing the failure message, we can add the missing allow-from addresses, and run the command again:

$ ssh-mgr-client validate-authorized-key-options -i 220 -d \
'allow-from=server01.example.com,allow-from=server02.example.com'

SUCCESS validate_options auth_key#220

The command can also be used for catching syntax errors in authorized-key options. For example, when providing an unquoted command option:

$ ssh-mgr-client validate-authorized-key-options -i 220 -d 'command=date'

ERROR:ssh-mgr-client:Could not parse key options 'command=date':
Unquoted command option date: 1 ERROR

You can review the error message to determine the potential problems, then fix the errors and revalidate:

$ ssh-mgr-client validate-authorized-key-options -i 220 -d 'command="date"'

SUCCESS validate_options auth_key#220

note

When using the validate-authorized-key-options command, bear in mind the following features and limitations:

The validate-authorized-key-options command only validates the specified authorized-key options against the selected keys. The command does not modify authorized-key options in any way. Also, Key Manager does not typically prevent you from setting authorized-key options that fail to validate.

After you have validated the options, you can set the options, for example, using the set-authorized-key-options command (described in set-authorized-key-options).
This command cannot be used for validating authorized-key options that contain wildcard characters (such as * or ?).

This command cannot be used for validating deny-from options. Authorized-key options in the following example will produce a failing result, regardless of known source addresses:

$ ssh-mgr-client validate-authorized-key-options -i 220 -d \
'allow-from=server01.example.com,deny-from=server.example.com'

FAILURE validate_options auth_key #220:
Validating deny-from options not supported.

Key Manager reverse-maps IP addresses, and validates known source addresses in FQDN format whenever FQDNs can be obtained. Therefore, if you specify a known source address in IP format, validation fails if the corresponding FQDN is available.

For example, assume that a known source address belongs to a host with the IP address 192.0.2.100, and that Key Manager is able to reverse-map this IP address to the FQDN server.example.com. In such a scenario, specifying the allow-from address in IP format would produce a failing result from the validation:
```
$ ssh-mgr-client validate-authorized-key-options -i 20 -d \
'allow-from=192.0.2.100'

FAILURE validate_options auth_key#20: Key has been used from
address(es) which would be disallowed by the new from option(s).
MISSING: server.example.com
```
We recommend specifying allow-from addresses in FQDN format when possible. For example, the validation returns a success when the corresponding FQDN is specified, instead of the IP:
```
$ ssh-mgr-client validate-authorized-key-options -i 20 -d \
'allow-from=server.example.com'

SUCCESS validate_options auth_key#20    
```

validate-private-key-passphrase

Syntax:

ssh-mgr-client validate-private-key-passphrase -d <data> [options] \
[(-F <filter> | -i <id>)] [-vvv] [-U <url>] [-o <format>]

Check whether the specified passphrase conforms to the current passphrase policies set for the selected keys. In other words, check whether the specified passphrase can be set to the selected keys. If no keys are selected. This command checks whether the specified passphrase is allowed by Key Manager global passphrase-policy settings.

If the passphrase is allowed by the applicable passphrase policies, the command returns a success message similar to the following:

SUCCESS validate_passphrase private_key: example_passphrase

If the passphrase is disallowed by the applicable passphrase policies, the command returns a failure message similar to the following

FAILURE validate_passphrase private_key: Password must contain at least 1 numbers

note

This command merely checks whether the specified passphrase could be set. Existing private- key passphrases are not modified in any way.

Required data:

passphrase

The passphrase of the selected keys.

You may select a private key using its ID (-i). Alternatively, you may select multiple keys using filters (- F). Provide the passphrase as input data (-d).

Example for checking a passphrase against Key Manager global passphrase policies:

$ ssh-mgr-client validate-private-key-passphrase -d "passphrase=example_passphrase"

Example for checking a passphrase against the passphrase policies that apply to an existing key:

$ ssh-mgr-client validate-private-key-passphrase -d "passphrase=example_passphrase" -i 99

add-request​

request_type​

command​

comment​

dst​

extra_data​

from_stanza​

key_alg​

key_size​

owner​

passphrase​

reuse​

src​

tags​

validity​

auth_key_filter​

auth_key_ids​

private_key_filter​

private_key_ids​

timepoint​

application​

execution_window​

key_args​

key_ids​

key_type​

owner​

add-authorizations​

from​

from_keyids​

from_userids​

to​

to_extuserids​

to_keyids​

to_userids​

add_to_config​

command​

contact​

from_stanza​

key_alg​

key_data​

key_path​

key_size​

passphrase​

reason​

reuse​

tags​

validity​

add-authorized-key-options​

command​

allow-from​

deny-from​

from​

approve-authorized-keys​

approve-private-keys​

approve-requests​

owner​

approval_options​

blacklist-authorized-keys​

cancel-requests​

continue-key-relocation​

count-authorized-keys​

count-private-keys​

edit-authorized-keys​

edit-private-keys​

forget-private-key-passphrase​

decide-requests​

send-email​

message​

to​

allow-from​

command​

tags​

generate-user-private-keys​

add_to_config​

comment​

key_alg​

key_path​

key_size​

passphrase​

reuse​

add-request

request_type

command

comment

dst

extra_data

from_stanza

key_alg

key_size

owner

passphrase

reuse

src

tags

validity

auth_key_filter

auth_key_ids

private_key_filter

private_key_ids

timepoint

application

execution_window

key_args

key_ids

key_type

owner

add-authorizations

from

from_keyids

from_userids

to

to_extuserids

to_keyids

to_userids

add_to_config

command

contact

from_stanza

key_alg

key_data

key_path

key_size

passphrase

reason

reuse

tags

validity

add-authorized-key-options

command

allow-from

deny-from

from

approve-authorized-keys

approve-private-keys

approve-requests

owner

approval_options

blacklist-authorized-keys

cancel-requests

continue-key-relocation

count-authorized-keys

count-private-keys

edit-authorized-keys

edit-private-keys

forget-private-key-passphrase

decide-requests

send-email

message

to

allow-from

command

tags

generate-user-private-keys

add_to_config

comment

key_alg

key_path

key_size

passphrase

reuse