appliance-cli¶

Manage your Anapaya appliance

Synopsis¶

This tool helps you interact with the Anapaya appliance.

Capabilities¶

The appliance-cli acts as a frontend interface for the appliance management API. It can connect to appliances on the same host, or to appliances on remote hosts over the network.

The appliance-cli has a group of commands which are generated from the endpoints that are available in the appliance management API. To help you discover the available endpoints, we recommend that you install auto completion. See appliance-cli completion for further information. This enables tab completion for the appliance-cli, and will complete all the matching endpoints for the generated commands.

The generated commands to interact with the appliance management API are:

Additionally, the tool comes with debugging capabilities that, depending on the command, are only available if the appliance-cli is run on the appliance host itself:

Basic Usage¶

If the appliance-cli is run on an appliance host directly and no authentication for the appliance management API is enabled, no additional setup is required.

Tip

Check out appliance context if you want to use the appliance-cli remotely, or if you want to configure authentication.

For example, you can request the appliance configuration with the following command:

appliance-cli get config

You will see a response like this:

{
  config: {...}
}

Tip

By default, the output is the JSON encoding of the response body. You can get access to other response fields or formats. See output for more information.

Input¶

Various inputs can be passed as needed:

# Pass a query parameter (flag)
appliance-cli get cppki/trcs --query all=true

# Pass a query parameter (environment)
APPLIANCE_CLI_QUERY="all=true" appliance-cli get cppki/trcs

# Pass a header (flag)
appliance-cli get config --header ETag:W/d393abc

# Pass a header (environment)
APPLIANCE_CLI_HEADER="ETag:W/d393abc" appliance-cli get config

# Pass a file as the body
appliance-cli put config < appliance.json

# Pass body as CLI Shorthand
appliance-cli post cppki/certificates/renew 'subject.isd_as: "1-ff00:0:111"'

See the official documentation for more information on how to compose complex payloads with the CLI shorthand.

Tip

If you want to persistently add headers or query parameters for an appliance, consider configuring them in the appliance context.

Editing Resources¶

For endpoints that support both a GET and PUT request, a convenience edit command is created which allows you to modify the resource. There are two ways of editing the resource.

You can edit the resource with the CLI shorthand:

appliance-cli edit config 'config.management.hostname: host1.site1.org'

You can edit the configuration interactively with your editor of choice:

appliance-cli edit config -i

To use the interactive mode, you need to have the VISUAL or EDITOR environment variable set. Here, you can pass your editor of choice. E.g., to configure VSCode, you can set the VISUAL environment variable:

export VISUAL="code --wait"

Output¶

The appliance-cli output defaults to the response body in JSON format. Filters are used to tailor the output that you want to see. Via filters, you have access to the response body, the response headers, and the status codes. Furthermore, you can narrow down the information that is relevant to you.

Tip

You can change the body format to YAML with the --format flag. E.g., to return the appliance configuration as YAML, run the following command:

appliance-cli get config --format yaml

A filter must begin with one of the following (or be empty):

body: The response body (default)
headers: The response headers
status: The reponse status code

For example, to only show the response headers, and not the response body pass the following filter:

appliance-cli get config -f headers

To get a human-readable output that lists both the response body and response headers, pass the empty filter:

appliance-cli get config -f ""

The filter supports the CLI shorthand querying syntax and allows you to narrow down the output even more. Here are some examples to illustrate this:

Return the hostname of an appliance:

$ appliance-cli get config -f body.config.management.hostname

host1.site1.org

Show some basic AS properties:

$ appliance-cli get config -f 'body.config.scion.ases.{isd_as, core, scion_mtu}'

[
  {
    core: false
    isd_as: "1-ff00:0:1"
    scion_mtu: 1500
  },
  {
    core: true
    isd_as: "2-ff00:0:1"
    scion_mtu: 1472
  },
]

List the ISD-AS identifier of all ASes with more than one neighboring AS:

$ appliance-cli get config -f 'body.config.scion.ases[neighbors.length > 0].isd_as'

["1-ff00:0:1", "2-ff00:0:1"]

List all certificates that are valid on May 4th:

$ appliance-cli get cppki/certificates -f 'body.certificate_chains[
  validity.not_before before "2023-05-04" and
  validity.not_after after "2023-05-04"
].{id, validity}'

[
  {
    id: "1b267d9a208603618db8f9dcc02d58906af18e2992e5412e5fa42a715d350841"
    validity: {
      not_after: "2023-05-06T00:50:03Z"
      not_before: "2023-05-03T00:49:33Z"
    }
  }
]

Environment Variables¶

APPLIANCE_CLI_PATH: The directory where the appliance-cli stores the configurations and appliance contexts. Defaults to $HOME/.appliance-cli.
APPLIANCE_CLI_NOCOLOR: Disable colored output on the tty.
HTTP_PROXY and NO_PROXY: Configure proxies for output HTTPS traffic. See http.ProxyFromEnvironment for more information.

You can also pass all flags to the appliance-cli via environment variables. Add APPLIANCE_CLI_<flag> to your flag of choice. Note that the flag name must be all upper case. E.g., APPLIANCE_CLI_FORMAT=yaml appliance-cli get config is equivalent to appliance-cli get config --format yaml. The precedence order is: flags > environment variables > configuration file.

Appliance Context¶

By default, the appliance-cli connects to the appliance on the localhost with the default address 127.0.0.1:443. If you enable basic auth, OAuth2, or want to manage appliances remotely, you will need to set up one (or multiple) appliance contexts explicitly.

When configuring an appliance context, you can define the appliance address and a default profile with the necessary credentials. You can then quickly switch between different appliance contexts, such that you can easily work with various appliances.

To configure a new or edit an existing appliance, run the following command:

appliance-cli context configure <name>

Note

If you are configuring an appliance with a self-signed certificate, you will need to pass the --insecure flag to disable TLS verification.

This interactive command guides you through the configuration, and sets up the the appliance context with a default profile in the APPLIANCE_CLI_PATH.

A sample execution to configure basic authorization for an appliance host1.site1.org that is running on the local host is shown here:

$ appliance-cli context configure host1.site1.org --insecure

? Base URI https://127.0.0.1:443
Setting up a `default` profile
? Select option for profile `default` Setup auth
? API auth type http-basic
? Auth parameter username admin
? Auth parameter password super-secret
? Add additional auth param? No
? Select option for profile `default` Finished with profile
? Select option Save and exit

To switch between different appliances, use the following command:

$ appliance-cli context select

? Select appliance context  [Use arrows to move, type to filter]
> host1.site1.org (https://127.0.0.1:443)
  host2.site1.org (https://10.00.0.1:443)

You can also override this setting for single commands by specifying the --context flag or APPLIANCE_CLI_CONTEXT environment variable explicitly.

For more information on appliance contexts, consult the help of appliance-cli context:

appliance-cli context --help

An appliance context can have multiple profiles. However, in most cases you are served best by sticking with one default profile per appliance context.

Options¶

  -h, --help   help for appliance-cli