Command-Line Client Usage Examples

This section provides examples about running various commands via the command-line client. Note that to run these examples you must first set up the command-line client, as per instructions provided in the PrivX Key Manager Installation Manual.

You can use the command-line client to list information about various types of objects. For example, you can list jobs using the list-jobs command:

$ ssh-mgr-client list-jobs

1,discover,alice,,2015-07-22T11:29:44.017Z,finished
2,discover-host,alice,192.168.2.111,2015-07-22T11:29:09.145Z,finished
3,reverse-ip-mapper,system,,2015-07-22T12:29:18.734Z,finished
4,internal-calculate-statistics,system,,2015-07-22T11:59:37.902Z,finished
7,discover,alice,,2015-07-22T11:30:50.200Z,finished
...

By default, list commands returns information about objects as comma-separated values. Each returned row describes one object. And unless explicitly specified, values are returned for pre-configured columns (default values differ for each type of list command).

If you want to know what each value represents, you can display a header row by including the -H option:

$ ssh-mgr-client list-jobs -H

id,job_type,admin,job_target,last_updated,status
1,discover,alice,,2015-07-22T11:29:44.017Z,finished
2,discover-host,alice,192.168.2.111,2015-07-22T11:29:09.145Z,finished
3,reverse-ip-mapper,system,,2015-07-22T12:29:18.734Z,finished
4,internal-calculate-statistics,system,,2015-07-22T11:59:37.902Z,finished
7,discover,alice,,2015-07-22T11:30:50.200Z,finished
...

To explicitly specify the return columns, use the -C option:

$ ssh-mgr-client list-jobs -H -C id,job_type,status

id,job_type,status
1,discover,finished
2,discover-host,finished
3,reverse-ip-mapper,finished
4,internal-calculate-statistics,finished
7,discover,finished
...

You can use command-line client commands in conjunction with most OS commands, for example, by piping:

$ ssh-mgr-client list-jobs -H   head -n 3

id,job_type,admin,job_target,last_updated,status
1,discover,alice,,2015-07-22T11:29:44.017Z,finished
2,discover-host,alice,192.168.2.111,2015-07-22T11:29:09.145Z,finished

Sometimes, it may be convenient to direct the command output to a file:

$ ssh-mgr-client list-jobs -H > jobs_example.txt

Some commands (such as list commands) utilize filters for filtering or specifying target elements. Filters are specified using -F. For example, to see all the jobs of a certain type (scan-full) performed on a certain host (bilberry.example.com):

$ ssh-mgr-client list-jobs -H -F "job_type=scan-full&&hostname=bilberry.example.com"

id,job_type,admin,job_target,last_updated,status
12352,scan-full,alice,192.168.2.111,2015-08-20T11:17:34.685Z,finished
12415,scan-full,system,bilberry.example.com,2015-08-20T12:18:01.841Z,finished
12433,scan-full,system,bilberry.example.com,2015-08-20T13:18:09.556Z,finished
12446,scan-full,system,bilberry.example.com,2015-08-20T14:18:23.314Z,finished
12459,scan-full,system,bilberry.example.com,2015-08-20T15:18:33.221Z,finished
12472,scan-full,system,bilberry.example.com,2015-08-20T16:18:42.830Z,finished
12485,scan-full,system,bilberry.example.com,2015-08-20T17:18:52.737Z,finished
...

Most Key Manager actions can be performed via the command-line client. For example, to add agentless hosts:

$ ssh-mgr-client add-hosts -d \
hostname=mulberry.example.com,username=root,password=example_password

STARTED Add hosts: Job 13712
STARTED Add host mulberry.example.com: Job 13713

### SUMMARY REPORT #13712 ###

# Rows started/failure/total: 1/0/1
# Operations started/failure/total: 1/0/1
# Parent job launched: 13712
# Jobs launched: 13713

The command starts jobs for adding the specified authorization. The job IDs are provided in the command output. You can use commands to check the current status of the job:

$ ssh-mgr-client list-jobs -H -F "id=13388"

id,job_type,admin,job_target,last_updated,status
13712,discover,jizhouya,,2015-08-27T12:37:11.952Z,finished

If the job status is finished, the host has been added successfully. You can verify that the newly-added host is listed in the managed environment, and that its status is monitored. Also, to make the output more readable, we specify the relevant output columns with -C:

$ ssh-mgr-client list-hosts -H -C hostname,state

hostname,state
bilberry.example.com,managed
cranberry.example.com,managed
mulberry.example.com,monitored

Switch the host to the managed state to enable key-management actions on it:

$ ssh-mgr-client manage-hosts -F "hostname=mulberry.example.com"

Once again, check the host state:

$ ssh-mgr-client list-hosts -H -C hostname,state

hostname,state
bilberry.example.com,managed
cranberry.example.com,managed
mulberry.example.com,managed

As another example, we shall add authorizations between accounts:

$ ssh-mgr-client add-authorizations -d \
"from=charlie@bilberry.example.com,to=charlie@mulberry.example.com"

STARTED Add authorizations: Job 13388
SUCCESS Get or create private key for charlie@bilberry.example.com #16
STARTED Authorize private key #16 from charlie@bilberry.example.com to \
charlie@mulberry.example.com #16: Job 13389

### SUMMARY REPORT #13388 ###

# Rows started/failure/total: 1/0/1
# Operations started/failure/total: 2/0/2
# Parent job launched: 13388
# Jobs launched: 13389

The command starts jobs for adding the specified authorization. The job IDs are provided in the command output. You can use command-line client commands to check the current status of the job:

$ ssh-mgr-client list-jobs -H -F "id=13388"

id,job_type,admin,job_target,last_updated,status
13388,add-authorization,alice,,2015-08-26T11:52:22.841Z,finished

If the job status becomes finished, the authorization has been added successfully. You can still verify that the authorization is also recorded in Key Manager, for example, by searching for authorizations with the previously-specified source account. Also, to make the output more readable, we specify the relevant output columns with -C:

$ ssh-mgr-client --insecure list-authorizations -H -F \
"pk_username=charlie&&pk_hostname=bilberry.example.com" \
-C pk_username,pk_hostname,ak_username,ak_hostname

pk_username,pk_hostname,ak_username,ak_hostname
charlie,bilberry.example.com,charlie,mulberry.example.com