System Commands
System commands are used for managing Key Manager jobs. System commands are also used for managing agentless management keys.
For more information about Key Manager jobs, see Jobs and Back-end Performance.
calculate-reporting-data
Syntax:
ssh-mgr-client [global_options] calculate-reporting-data [-p <priority>]
Calculate reporting data based on the current state of the managed environment.
This command updates the contents of PDF reports (both manually generated and automatically emailed reports).
Example usage:
$ ssh-mgr-client calculate-reporting-data
cancel-jobs
Syntax:
ssh-mgr-client cancel-jobs [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-B] [-T <timeout>]
Cancels selected jobs that are in progress (running, queued, or pending).
You can select a job by providing its ID (-i). Alternatively, you can select jobs using filters (-F).
For filtering, you can use the same attributes that are available for the list-jobs command (see list-jobs).
The permissions required for canceling a job are the same as those required for starting that job: Key Manager users who are able to start the job are also able to cancel it. The exact permissions required for canceling a job depend on the characteristics of the job, such as its type and target.
Example for canceling the job with the jobid of 12:
$ ssh-mgr-client cancel-jobs -i 12
As another example, canceling all currently running host-scan jobs:
$ ssh-mgr-client cancel-jobs -F "job_type=scan-host"
Canceling a parent job automatically cancels all the associated child jobs.
Canceling a job does not undo the actions that have already been run by the target job. See the job log for a list of all the commands that have been run. To review what commands have been run by a job, see its full job log. See Jobs and Back-End Performance for instruction about viewing the job log.
clear-global-setting
Syntax:
ssh-mgr-client clear-global-setting [options] -d <data> [-vvv] [-U <url>] [-B]
Clears a global setting.
In input data (-d), specify the category and the name of the setting that is to be cleared. Global settings
defined with default values are reset rather than cleared.
A list of valid setting categories and names can be displayed by invoking help for this command:
$ ssh-mgr-client help clear-global-setting
Example:
$ ssh-mgr-client clear-global-setting -d category=host,name=scan_interval
clear-host-group-setting
Syntax:
ssh-mgr-client clear-host-group-setting (-i <id> | -I <id-filter>) \
-d <data> [options] [-vvv] [-U <url>]
Clears a host group setting.
In input data (-d), specify the category and the name of the setting that is to be cleared. Select the host
group using its ID (-i) or matching ID filters (-I). For ID filtering, you can use the same attributes that are
available for the list-host-groups command (described in list-host-groups).
A list of valid ID-filter attributes, setting categories, and setting names can be displayed by invoking help for this command:
$ ssh-mgr-client help clear-host-group-setting
Example:
$ ssh-mgr-client clear-host-group-setting -I \
'hostgroup=Example_Group' -d category=host,name=scan_interval
clear-host-setting
Syntax:
ssh-mgr-client clear-host-setting (-i <id> | -I <id-filter>) \
-d <data> [options] [-vvv] [-U <url>]
Clear a setting from the selected host.
In input data (-d), specify the category and the name of the setting that is to be cleared. Select the host
using its ID (-i) or matching ID filters (-I). For ID filtering, you can use the same attributes that are
available for the list-hosts command (described in list-hosts).
A list of valid ID-filter attributes, setting categories, and names can be displayed by invoking help for this command:
$ ssh-mgr-client help clear-host-setting
Example:
$ ssh-mgr-client clear-host-setting -I \
'hostname=server.example.com' -d category=host,name=scan_interval
clear-mgmt-server-setting
Syntax:
ssh-mgr-client clear-mgmt-server-setting (-i <id> | -I <id-filter>) \
-d <data> [options] [-vvv] [-U <url>]
Clear a setting from the selected management server (Key Manager Server).
In input data (-d), specify the category and the name of the setting that is to be cleared. Select the Key
Manager Server using its ID (-i) or matching ID filters (-I). For ID filtering, you can use the same attributes
that are available for the list-mgmt-servers command (described in list-mgmt-servers).
A list of valid ID-filter attributes, setting categories, and names can be displayed by invoking help for this command:
$ ssh-mgr-client help clear-mgmt-server-setting
Example:
$ ssh-mgr-client clear-mgmt-server-setting -I \
"fqdn=server.example.com" -d category=backend,name=max_processes
continue-jobs
Syntax:
ssh-mgr-client continue-jobs [options] (-F <filter> | -i <id>) \
[-d <data>] [-vvv] [-U <url>] [-B] [-T <timeout>]
Continue executing the selected jobs. This command can be used, for example, to continue staged key renewal before its stage period expires.
Select a job using its ID (-i). Alternatively, you can speficy filters (-F) to select multiple jobs. For filtering
(-F), you can use the same attributes that are available for the list-jobs command (see list-jobs).
For example, to continue a pending job that has a specific ID:
$ ssh-mgr-client continue-jobs -i 484
count-db-connections
Syntax:
ssh-mgr-client [global_options] count-db-connections
Show the number of database connections to the Key-Manager-database instance.
The database-connection count includes all the sessions to the database instance, including sessions from other sources than the Key Manager system, and sessions to all the databases/ tablespaces on the same instance.
Example:
$ ssh-mgr-client count-db-connections
count-jobs
Syntax:
ssh-mgr-client count-jobs [options] [-F <filter>] [-vvv] [-U <url>]
Returns the number of jobs in the Key Manager system.
For filtering (-F), you can use the same attributes that are available for the list-jobs command (see list-jobs).
Example:
$ ssh-mgr-client count-jobs
2430
Example for counting the number of jobs that finished on a certain date:
$ ssh-mgr-client count-jobs -F date_finished=2011-01-28*
27
list-all-settings
Syntax:
ssh-mgr-client list-all-settings [options] \
[-vvv] [-U <url>] [-F <filter>] [-o <format>] [-C <columns>] [-H] \
[-O <sort-order>] [-S <start-from>] [-M <max-results>] [-E <delim>]
The default version of the command lists all the settings in the managed environment
$ ssh-mgr-client list-all-settings
global,,alert_dispatch,critical,[],,
global,,alert_dispatch,normal,[],,
global,,authentication,active_directory_domain,,,
global,,backend,load_multiplier,2.0,,
...
The following columns can be used for filtering (-F) and output formatting (-C):
category
Setting category
hostgroup
Name of the setting owner, if the owner is a host group. Only usable for output formatting (-C).
hostname
Name of the setting owner, if the owner is a host. Only usable for output formatting (-C).
name
Setting name
object_id
Numeric identifier for the setting owner
object_type
Type of the object which is the setting owner
value
Setting value. Only usable for output formatting (-C).
Example for displaying all the settings of a certain category:
$ ssh-mgr-client list-all-settings -F 'category= host' -H
list-global-settings
Syntax:
ssh-mgr-client list-global-settings [options] \
[-F <filter>] [-vvv] [-U <url>] [-o <format>] \
[-C <columns>] [-H] [-O <sort-order>] [-E <delim>]
The default version of the command lists the global settings in the managed environment
$ ssh-mgr-client list-global-settings
global,,alert_dispatch,critical,[],,
global,,alert_dispatch,normal,[],,
global,,authentication,active_directory_domain,,,
global,,backend,load_multiplier,2.0,,
...
The following columns can be used for filtering (-F) and output formatting (-C):
category
Setting category
hostgroup
Name of the setting owner, if the owner is a host group. Only usable for output formatting (-C).
hostname
Name of the setting owner, if the owner is a host. Only usable for output formatting (-C).
name
Setting name
object_id
Numeric identifier for the setting owner
object_type
Type of the object which is the setting owner
value
Setting value. Only usable for output formatting (-C).
Example for displaying the global settings of a certain category:
$ ssh-mgr-client list-global-settings -F 'category= host' -H
list-host-group-settings
Syntax:
ssh-mgr-client list-host-group-settings (-i <id> | -I <id-filter>) [options] \
[-F <filter>] [-vvv] [-U <url>] [-o <format>] [-C <columns>] [-H] \
[-O <sort-order>] [-E <delim>]
List the effective settings of the selected host group.
Select the host group using its ID (-i), or by using ID filters (-I). For ID filtering, you can use the filter
attributes that are available for the list-host-groups command (described in list-host-groups).
The following columns can be used for filtering (-F) and output formatting (-C):
category
Setting category
hostgroup
Name of the setting owner, if the owner is a host group. Only usable for output formatting (-C).
hostname
Name of the setting owner, if the owner is a host. Only usable for output formatting (-C).
name
Setting name
object_id
Numeric identifier for the setting owner
object_type
Type of the object which is the setting owner
value
Setting value. Only usable for output formatting (-C).
Example for displaying the effective settings of the host group with the given host-group name:
$ ssh-mgr-client list-host-group-settings -I 'hostgroup=Example_Group' -H
list-host-settings
Syntax:
ssh-mgr-client list-host-settings (-i <id> | -I <id-filter>) [options] \
[-F <filter>] [-vvv] [-U <url>] [-o <format>] [-C <columns>] [-H] \
[-O <sort-order>] [-E <delim>]
List the effective settings of the selected host.
Select the host using its ID (-i), or by using ID filters (-I). For ID filtering, you can use the filter attributes
that are available for the list-hosts command (described in list-hosts).
The following columns can be used for filtering (-F) and output formatting (-C):
category
Setting category
hostgroup
Name of the setting owner, if the owner is a host group. Only usable for output formatting (-C).
hostname
Name of the setting owner, if the owner is a host. Only usable for output formatting (-C).
name
Setting name
object_id
Numeric identifier for the setting owner
object_type
Type of the object which is the setting owner
value
Setting value. Only usable for output formatting (-C).
Example for displaying the effective settings of the host with the given hostname:
$ ssh-mgr-client list-host-settings -I 'hostname=server.example.com' -H
Example for displaying the value of a specific setting:
$ ssh-mgr-client list-host-settings \
-I "hostname=server.example.com" -F "name=timezone"
list-mgmt-server-settings
Syntax:
ssh-mgr-client list-mgmt-server-settings (-i <id> | -I <id-filter>) [options] \
[-F <filter>] [-vvv] [-U <url>] [-o <format>] [-C <columns>] [-H] \
[-O <sort-order>] [-E <delim>]
List the effective settings of the selected management server (Key Manager back end).
Select the management server using its ID (-i), or by using ID filters (-I). For ID filtering, you can use the
filter attributes that are available for the list-mgmt-servers command (described in list-mgmt-servers).
The following columns can be used for filtering (-F) and output formatting (-C):
category
Setting category
hostgroup
Name of the setting owner, if the owner is a host group. Only usable for output formatting (-C).
hostname
Name of the setting owner, if the owner is a host. Only usable for output formatting (-C).
name
Setting name
object_id
Numeric identifier for the setting owner
object_type
Type of the object which is the setting owner
value
Setting value. Only usable for output formatting (-C).
Example for displaying the effective settings of the management server with the given host name:
$ ssh-mgr-client list-mgmt-server-settings -I 'fqdn=server.example.com' -H
list-job-statistics
Syntax:
ssh-mgr-client list-job-statistics [options] [-F <filter>] [-vvv] \
[-U <url>] [-o <format>] [-C <columns>] [-H] [-O <sort-order>] \
[-S <start-from>] [-M <max-results>] [-E <delim>] [-B]
List job statistics
The following columns can be used for filtering (-F) and output formatting (-C):
first_failure
Date when the job has first failed
first_success
Date when the job was first successfully finished
host_id
Id of the host the job statistic is for
hostname
Name of the host the job statistic is for
id
Internal PrivX Key Manager id
job_type
Type of the job
last_cancelled
Date when the job was last cancelled
last_error
Last error that caused this job to fail
last_failure
Date when the job has last failed
last_finished
Date when the job was last finished
last_job_failed
Last job failed. Only usable for filtering (-F).
last_queued
Date when the job was last queued for running
last_success
Date when the job was last successfully finished
total_failures
Number of total failed runs of this job
total_successes
Number of total successful runs of this job
For example, listing job statistics for a certain host:
$ ssh-mgr-client list-job-statistics -F hostname=server01.example.com -H
list-jobs
Syntax:
ssh-mgr-client list-jobs [options] \
[-F <filter>] [-vvv] [-U <url>] [-o <format>] [-C <columns>] [-H] [-B]
The default command lists all the jobs in the system:
$ ssh-mgr-client list-jobs
1,reverse-ip-mapper,,2014-02-06T10:42:59.746Z,finished,1
2,internal-calculate-statistics,,2014-02-06T10:13:22.677Z,finished,2
3,discover,,2014-02-06T10:02:48.888Z,finished,3
4,discover-host,server.example.com,2014-02-06T10:02:27.249Z,finished,4
...
In large environments, the unfiltered list of jobs is likely to return an overwhelming number of items. For performance reasons it is recommended that you use filters to restrict the number of returned items.
The following columns can be used for filtering (-F) and output formatting (-C):
admin
Username of the admin who started the job
cancellation_status
Description of the status of the cancellation process for cancelled jobs.. Only usable for output formatting (-C).
date_created
Date when the job was created
date_finished
Date when the job finished
date_started
Date when the job started
deadlock_count
Number of deadlocks this job has encountered
duration
Duration of the job. Only usable for output formatting (-C).
error
Error that caused this job to fail
has_children
Does this job have child jobs?
host_id
Id of the host the job is for
hostgroup
Name of host group that the job concerns. Only usable for filtering (-F).
hostgroupid
Id of host group that the job concerns. Only usable for filtering (-F).
hostname
Name of the host the job is for
id
Internal PrivX Key Manager id for job
iduration
Duration of the job as an integer (seconds). Only usable for output formatting (-C).
is_interesting
Is the job interesting; internal jobs that have not failed are not considered interesting.. Only usable for filtering (-F).
job_target
Target of the job
job_type
Type of the job
job_type_localized
Type of the job (localized). Only usable for output formatting (-C).
last_updated
Date when the job was last updated
not_after
End of the validity period of the key
not_before
Start of the validity period of the key
operation_id
Internal PrivX Key Manager id for operation the job is a part of
owner
Tag of the process or entity responsible for this job
parent_job_id
Id of the parent job
priority
Numeric priority of the job. Smaller value means higher priority.
progress
Number (0-100) showing the progress of the job
queue_duration
Duration of the time the job stayed queued. Only usable for output formatting (-C).
restart_count
Number of times this job has been restarted
results_len
Total length of stored results of this job. Only usable for output formatting (-C).
state
State of the job
state_localized
State of the job (localized). Only usable for output formatting (-C).
status
Status of the job
status_localized
Status of the job (localized). Only usable for output formatting (-C).
tree_id
Id of the job tree
For example, to find all the jobs run on the host example.server.com:
$ ssh-mgr-client list-jobs -F "job_target=server.example.com"
As another example, to find all the jobs run on the host example.server.com; while listing their job type, status, and creation date:
$ ssh-mgr-client -C "job_type,status,date_created" \
list-jobs -F "job_target=server.example.com"
You can also use the hostname filter attribute for displaying jobs run on a certain host. However,
filtering by hostname does not display jobs that were run on the host before it was successfully
added to the managed environment, such as failed host-discovery jobs.
When searching for jobs by some time value, you must match the time stamp as it is displayed on the
command line (visible in the previous example). It is recommended to use the * wildcard, as the full time
stamp format is somewhat complex.
For example, to display all the jobs that finished on 28th of January 2011 (regardless of the time of day):
$ ssh-mgr-client list-jobs -F date_finished=2011-01-28*
progress-report-for-jobs
Syntax:
ssh-mgr-client progress-report-for-jobs [options] (-F <filter> | -i <id>) \
[-vvv] [-U <url>] [-o <format>]
Return progress-related information about the selected jobs.
This command returns the status, progress, job_type, description, and the target of the selected
jobs. The values are returned in JSON format.
Select a job by specifying its ID (-i), alternatively, you can specify multiple jobs using filters (-F). For
filtering, you can use the same attributes that are available for the list-jobs command (described in
list-jobs).
Example command and output:
$ ssh-mgr-client progress-report-for-jobs -i 999
SUCCESS progress_report job #999: \
{u'status': u'finished', u'progress': 100, \
u'job_type': u'internal-expire-authorizations', \
u'description': u'Internal Authorization Expiry', u'target': u''}
progress-report-for-requests
Syntax:
ssh-mgr-client progress-report-for-requests [options] \
(-F <filter> | -i <id>) [-vvv] [-U <url>] [-o <format>]
Return progress-related information about the selected action requests.
This command returns the state, and the job_id of the selected requests. The values are returned in
JSON format.
Additional information about jobs can be retrieved using the commands list-requests and
view-request (described in the sections list-requests and view-request respectively).
Select a request by specifying its ID (-i), alternatively, you can specify multiple requests using filters (-
F). For filtering, you can use the same attributes that are available for the list-requests command
(described in show-job).
Example command and output:
$ ssh-mgr-client progress-report-for-requests -i 999
SUCCESS progress_report request #999: \
{u'state': u'requiring_approval', u'job_id': None}
renew-management-keys
Syntax:
ssh-mgr-client renew-management-keys [options] (-F <filter> | -i <id>) \
[-vvv] [-U <url>] [-B] [-T <timeout>] [-p <priority>]
Renews the management keys on the selected hosts. Select a target hosts using its host ID. Alternatively,
you can use filters to select all matching hosts. For filtering, you can use similar attributes as the list-hosts command (see list-hosts).
The command launches renew-mgmt-key jobs for renewing the management keys on the selected hosts.
The management keys are renewed as soon as the jobs finish.
For example, to renew the management keys of a certain host:
$ ssh-mgr-client manage-hosts -i 8
As another example, to renew the management keys on all the Linux hosts:
$ ssh-mgr-client manage-hosts -F "os=linux"
For more information about management keys, see Managing Agentless Management Keys.
set-global-setting
Syntax:
ssh-mgr-client set-global-setting -d <data> [options] [-vvv] [-U <url>]
Set a global setting.
In input data (-d), specify the category, name, and the new value of the setting that is to be set.
A list of valid setting categories and names can be displayed by invoking help for this command:
$ ssh-mgr-client help set-global-setting
Example syntax for setting most settings:
$ ssh-mgr-client set-global-setting -d \
category=host,name=scan_interval,value=3600
When setting global proxy settings via the command-line client, use syntax similar to the following:
$ ssh-mgr-client set-global-setting -d \
category=backend,name=socks_proxy,value='\
{"rules": [{"to": "192.168.0.0/24", "via": "proxy.example.com:1080"}]}'
set-host-group-setting
Syntax:
ssh-mgr-client set-host-group-setting (-i <id> | -I <id-filter>) \
-d <data> [options] [-vvv] [-U <url>]
Set a setting for the selected host group.
In input data (-d), specify the category, name, and the new value of the setting that is to be set. Select the
host group using its ID (-i) or matching ID filters (-I). For ID filtering, you can use the same attributes
that are available for the list-host-groups command (described in list-host-groups).
A list of valid ID-filter attributes, setting categories, and setting names can be displayed by invoking help for this command:
$ ssh-mgr-client help set-host-group-setting
Example:
$ ssh-mgr-client set-host-group-setting -I 'hostgroup=Example_Group' \
-d category=host,name=scan_interval,value=3600
set-host-setting
Syntax:
ssh-mgr-client set-host-setting (-i <id> | -I <id-filter>) \
-d <data> [options] [-vvv] [-U <url>]
Set a setting for the selected host.
In input data (-d), specify the category, name, and the new value of the setting that is to be set. Select
the host using its ID (-i) or matching ID filters (-I). For ID filtering, you can use the same attributes that
are available for the list-hosts command (described in list-hosts).
A list of valid ID-filter attributes, setting categories, and names can be displayed by invoking help for this command:
$ ssh-mgr-client help set-host-setting
Example:
$ ssh-mgr-client set-host-setting -I 'hostname=server.example.com' \
-d category=host,name=scan_interval,value=3600
To set the classification or custom data for a host, use the command modify-host instead (described in modify-host).
set-job-priority
Syntax:
ssh-mgr-client set-job-priority (-F <filter> | -i <id>) -p <priority> \
[options] [-vvv] [-U <url>]
Set the priority for the selected jobs.
Select a job by providing its ID (-i). Alternatively, you can select multiple jobs using filters (-F). For filtering, you can use the same attributes that are available for the list-jobs command (described in list-jobs).
For example, to set the priority of a job that has a specific ID:
$ ssh-mgr-client set-job-priority -i 999 -p 4
Note that the previous command only sets the priority of the job with the given ID. If the job has child jobs, the priority for these must be set separately:
$ ssh-mgr-client set-job-priority -F "parent_job_id=999" -p 4
set-mgmt-server-setting
Syntax:
ssh-mgr-client set-mgmt-server-setting (-i <id> | -I <id-filter>) \
-d <data> [options] [-vvv] [-U <url>]
Set a setting for the selected management server (Key Manager Server).
In input data (-d), specify the category, name, and the new value of the setting that is to be set. Select
the Key Manager Server using its ID (-i) or matching ID filters (-I). For ID filtering, you can use the same
attributes that are available for the list-mgmt-servers command (described in list-mgmt-servers).
A list of valid ID-filter attributes, setting categories, and names can be displayed by invoking help for this command:
$ ssh-mgr-client help set-mgmt-server-setting
Example:
$ ssh-mgr-client set-mgmt-server-setting -I "fqdn=server.example.com" \
-d category=backend,name=max_processes,value=40
When setting proxy settings via the command-line client, use syntax similar to the following:
$ ssh-mgr-client set-mgmt-server-setting -I "fqdn=server.example.com" -d \
category=backend,name=socks_proxy,value='\
{"rules": [{"to": "192.168.0.0/24", "via": "proxy.example.com:1080"}]}'
show-job
Syntax:
ssh-mgr-client [-v] [-U <url>] [-o <format>] [-C <columns>] show-job -i <id>
Displays the job with the given ID.
For output formatting (-C), you can use the same attributes that are available for the list-jobs command
(see list-jobs).
Example:
$ ssh-mgr-client show-job -i 3
tag-mgmt-servers
Syntax:
ssh-mgr-client tag-mgmt-servers [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]
Tag the selected management servers (Key Manager Servers) with the specified tags.
Specify tags as input data (-d). If any of the specified tags do not exist, they will be created automatically.
You can select a Key Manager Server using its ID (-i). Alternatively, you can select multiple Key Manager
Servers using filters (-F). For filtering, you can use the same attributes that are available for the list-mgmt-servers command (described in list-mgmt-servers).
For example, to tag the Key Manager Server that has the ID value 2, with the tag apac:
$ ssh-mgr-client tag-mgmt-servers -i 2 -d tags="apac"
You can use filters to tag a Key Manager Server by address:
$ ssh-mgr-client tag-mgmt-servers -F "fqdn=server01.example.com" -d tags="primary"
As another example, setting multiple tags to all the Key Manager Servers that server as both Key Manager back ends and Key Manager front ends:
$ ssh-mgr-client tag-mgmt-servers -F "backend=True&&frontend=True" \
-d tags="front_end,back_end"
untag-mgmt-servers
Syntax:
ssh-mgr-client untag-mgmt-servers [options] \
(-F <filter> | -i <id>) -d <data> [-vvv] [-U <url>]
Remove the specified tags from the selected management servers (Key Manager Servers)
Specify tags as input data (-d). You can select a Key Manager Server using its ID (-i). Alternatively, you
can select multiple Key Manager Servers using filters (-F). For filtering, you can use the same attributes
that are available for the list-mgmt-servers command (described in list-mgmt-servers).
For example, to remove the tag apac from the Key Manager Server that has the ID value 2:
$ ssh-mgr-client untag-mgmt-servers -i 2 -d tags="apac"
You can use filters to untag a Key Manager Server by address:
$ ssh-mgr-client untag-mgmt-servers -F "fqdn=server01.example.com" -d tags="primary"
As another example, to remove multiple tags from all the Key Manager Servers that serve as both Key Manager back ends and Key Manager front ends:
$ ssh-mgr-client untag-mgmt-servers -F "backend=True&&frontend=True" \
-d tags="front_end,back_end"
view-job
Syntax:
ssh-mgr-client view-job -i <id> [options] [-vvv] [-U <url>]
Displays the full job log for the job with the given ID. For example, to display the job log for the job
with the jobid of 71:
$ ssh-mgr-client view-job -i 71
view-request
Syntax:
ssh-mgr-client view-request -i <id> [options] [-vvv] [-U <url>]
Displays the full log for the request with the given ID. For example, to display the job log for the job
with the jobid of 71:
$ ssh-mgr-client view-request -i 71