ochami is the command line interface to interact with the API of OpenCHAMI services, especially the State Management Database (SMD) and the Boot Script Service (BSS). The tool is meant to ease interaction with the API so one need not be proficient in curl.

There are manual pages in the man directory, which contain the most complete usage documentation available. While they are quite readable on the web, they are in scdoc format and require scdoc to build. There is a make target to do build them:

make man
man man/ochami.1

See Building for instructions on how to build ochami. Then, continue here with how to use it.

There are two configuration files in YAML format that ochami reads, in order:

1. System-Wide: /etc/ochami/config.yaml
2. User: ${HOME}/.config/ochami/config.yaml

If neither exist, it will use compiled defaults. Configuration in the second file override configuration in the first. Alternatively, the -c/--config flag can be used to manually specify a config file path.

Let's generate a user-level configuration:

mkdir -p ~/.config/ochami/
ochami config show > ~/.config/ochami/config.yaml

This will generate a default configuration at ~/.config/ochami/config.yaml.

Next, ochami needs to be told how to contact the Ochami services. The configuration file could be edited to do this, but ochami provides the cluster config command to edit cluster configuration.

Run the following command to add a default cluster configuration to the user configuration file called foobar whose base URI is https://foobar.openchami.cluster:

ochami config cluster set --user --default foobar cluster.uri https://foobar.openchami.cluster:8443

Now, when the configuration is shown, we should see the new cluster's details:

$ ochami config show
clusters:
    - cluster:
        uri: https://foobar.openchami.cluster:8443
      name: foobar
default-cluster: foobar
log:
    format: rfc3339
    level: warning

Test access by contacting an API endpoint not requiring an access token:

$ ochami bss status
{"bss-status":"running"}

Since ochami supports multiple cluster configurations, it supports reading environment variables corresponding to the cluster for the access token. This can be overridden by using --token. Since our cluster is named "foobar", we need to set FOOBAR_ACCESS_TOKEN to the value of the token so ochami can read it when communicating with this cluster.

export FOOBAR_ACCESS_TOKEN=eyJhbGc...

Note that the format of the environment variable that ochami reads for the access token is <CLUSTER_NAME>_ACCESS_TOKEN where <CLUSTER_NAME> is the value of the cluster name (name in the config file specified with --cluster, or default-cluster in the config file, the former taking precedence over the latter) in all capitals and with dashes (-) and spaces substituted with underscores (_).

Now, we should be able to contact the API on an endpoint that requires authentication:

$ ochami bss boot params get
null

Goreleaser is the way ochami gets built for releases, and is the officially supported build method for troubleshooting.

export GOVERSION=$(go env GOVERSION)
export BUILD_HOST=$(hostname)
export BUILD_USER=$(whoami)
goreleaser build --clean --snapshot --single-target

Remove --single-target to build for all targets.

Make provides convenient and quick building for fast iteration and development.

Linker flags are used to embed build metadata into the binary. Building can simply be done via:

make

On Unix-like systems, one can also install the binary, man pages, and completions:

sudo make install

docker pull ghcr.io/synackd/ochami:latest

There are two dockerfiles for two different purposes.

• Dockerfile is for manual building and is intended for building locally. It uses a multi-stage build, the first stage building from source and the second stage copying the binary from the first stage.
• goreleaser.dockerfile is used by Goreleaser for CI. It assumes the binary has already been built and copies it into the container.

To build the ochami container (with dirty tag):

docker build . --tag ochami:dirty

docker run ghcr.io/synackd/ochami:latest ochami --ignore-config help

The above incantation will print out the command line's help message.