Using the ssh-mgr-cli API Client

This section provides instructions for getting started with the ssh-mgr-cli, which is a client for the Key Manager API. The instructions in this chapter describe how to log in using the API client and its syntax conventions.

The instructions in this section assume that you have already set up the API client. If you need instructions for setting up the API client, see the PrivX Key Manager Installation Manuals.

Before you can run API commands using the API client, you will need to log into the Key Manager API. This is done with the following command:

$ ssh-mgr-cli client login

When logging in, you will be prompted for the URL of the API. For this you may specify the HTTPS address of any Key Manager front end in your Key Manager system. The following is an example of an accepted API URL (replace frontend.example.com with the address of your Key Manager front end):

https://frontend.example.com/

You will also be prompted for the user name and the password of a Key Manager account. API commands are executed as the Key Manager administrator who owns the specified account, with the same permissions that the specified account has.

API commands become available after successful login.

You can update the API definitions with certificate verification by using the --ca-file-path option or the --ca-dir-path option as follows (replace /path/to/ca.crt with the path to the CA-certificate file, or replace /path/to/cadir with the path of the directory that contains the CA-certificate file):

$ ssh-mgr-cli --ca-file-path /path/to/ca.crt client update

$ ssh-mgr-cli --ca-dir-path /path/to/cadir client update

The API client allows you to use all the endpoints provided by the Key Manager API (within the limits of your account permissions, of course). API endpoints are grouped into command categories - such as host, authorization, job, and so on. Each command category includes a set of commands that can be performed. For example, you can list hosts by calling the list command under the host category:

$ ssh-mgr-cli host list

The previous command corresponds to calling the following endpoint:

GET /api/v3/hosts/

note

The command categories available in the API client correspond to singular forms of the API endpoints. For example: the hosts endpoint in the API is represented by the host category in the API client.

The API client accepts JSON data as. In addition, the API client provides options for individual JSON fields. For example, when updating host data you may provide information similar to the following:

{
    "classification": "TEST",
    "description": "Example description"
}

Using the API client, you may provide the same information in either of the following ways:

$ ssh-mgr-cli host update 1 --body \
'{"classification": "TEST", "description": "Example description"}'

$ ssh-mgr-cli host update 1 \
--classification "TEST" --description "Example description"

When using options for individual JSON fields, list values may be provided without square brackets. For example, the following two commands behave identically:

$ ssh-mgr-cli host tag 1 --tag-names '["example_tag","test_tag"]'

$ ssh-mgr-cli host tag 1 --tag-names "example_tag","test_tag"

Furthermore, when using options for individual JSON fields, quotes around string values may be omitted:

$ ssh-mgr-cli host tag 1 --tag-names example_tag,test_tag

note

In the API client, options for individual JSON fields typically correspond to the name of the JSON field, except with underscores replaced with hyphens. For example, the JSON field "tag_names" is provided using the option --tag-names.

For additional information about any command, append --help to the command. Help typically describes the command usage, the available subcommands (if any), and the available command options.

To display the general API client help:

$ ssh-mgr-cli --help

Help is also available for individual commands and command categories. For example, displaying help for the host command category, and for the host-listing command:

$ ssh-mgr-cli host --help

$ ssh-mgr-cli host list --help