ockam


ockam [OPTIONS] <COMMAND>

Orchestrate end-to-end encryption, mutual authentication, key management, credential management, and authorization policy enforcement — at scale.

Modern applications are distributed and have an unwieldy number of interconnections that must trustfully exchange data. Ockam makes it simple to build secure by-design applications that have granular control over every trust and access decision.

Subcommands

Examples

Let's walk through a simple example to create an end-to-end encrypted, mutually authenticated, secure and private cloud relay – for any application.

First let's enroll with Ockam Orchestrator where we'll create a managed cloud based relay that will move end-to-end encrypted data between distributed parts of our application.

# Create a cryptographic identity and enroll with Ockam Orchestrator.
# This will sign you up for an account with Ockam Orchestrator and setup a
# hobby space and project for you.
$ ockam enroll

You can also create encrypted relays outside the orchestrator. See ockam relay --help.

Application Service

Next let's prepare the service side of our application.

# Start our application service, listening on a local ip and port, that clients
# would access through the cloud relay. We'll use a simple http server for our
# first example but this could be some other application service.
$ python3 -m http.server --bind 127.0.0.1 5000

# Setup an ockam node, called blue, as a sidecar next to our application service.
$ ockam node create blue

# Create a tcp outlet on the blue node to send raw tcp traffic to the application service.
$ ockam tcp-outlet create --at /node/blue --to 127.0.0.1:5000

# Then create a relay at your default orchestrator project to blue.
$ ockam relay create blue --to /node/blue

Application Client

Now on the client side

# Setup an ockam node, called green, as a sidecar next to our application service.
$ ockam node create green

# Then create an end-to-end encrypted secure channel with blue, through the cloud relay.
# Then tunnel traffic from a local tcp inlet through this end-to-end secure channel.
$ ockam secure-channel create --from /node/green \\
    --to /project/default/service/forward_to_blue/service/api \\
        | ockam tcp-inlet create --at /node/green --from 127.0.0.1:7000 --to -/service/outlet

# Access the application service though the end-to-end encrypted, secure relay.
$ curl 127.0.0.1:7000

We just created end-to-end encrypted, mutually authenticated, and authorized secure communication between a tcp client and server. This client and server can be running in separate private networks / NATs. We didn't have to expose our server by opening a port on the Internet or punching a hole in our firewall.

The two sides authenticated and authorized each other's known, cryptographically provable identifiers. In later examples we'll see how we can build granular, attribute-based access control with authorization policies.

ockam enroll


ockam enroll [OPTIONS]

When you run this command for the first time, it creates a space for you in Ockam Orchestrator, the SaaS service. This is where you host your projects, as well as a default project for you within this space.

It also generates a unique cryptographically provable identity and saves the corresponding key in a vault. This identity is issued a membership credential that will be used to manage the resources in your project. Optionally, you can pass an existing identity.

Options

  • --identity [IDENTITY_NAME] (optional)
    The name of an existing identity that you wish to enroll

  • --authorization-code-flow (optional)
    Use PKCE authorization flow

Examples

$ ockam enroll

Troubleshoot:

If you have problems with your enrollment then you can run ockam reset -y && ockam enroll to delete your local state and start again.

ockam space


ockam space <COMMAND>

In Ockam, a space is an infinitely scalable Ockam Node in the cloud that can be created, managed, and scaled by Ockam Orchestrator. Spaces offer services such as creating projects within a space, inviting teammates to it, or attaching payment subscriptions.

When you enroll in Ockam for the first time, a space is created for you to host your projects.

Subcommands

space create


ockam space create [OPTIONS] [SPACE_NAME] [-- <ADMINS>...]

This command will create a new space. If the space already exists, it will just fetch it and show its details.

Arguments

  • [SPACE_NAME] (optional)
    Name of the space - must be unique across all Ockam Orchestrator users

  • [ADMINS] (optional)
    Administrators for this space

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

Examples

# To create a new space with a random name
$ ockam space create

# To create a new space with a specific name
# Names must be unique across all Ockam Orchestrator users
$ ockam space create s

space delete


ockam space delete [OPTIONS] <NAME>

This command will delete the specified space. Deleting a space implies deleting all the projects associated with it.

Arguments

  • <NAME>
    Name of the space

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a space given its name
$ ockam space delete s

space list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam space list [OPTIONS]

This command will show the details of all the available spaces.

By default, it will fetch the spaces associated to the default identity. This can be overridden by passing the --identity flag.

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

Examples

# To list the spaces of the default identity
$ ockam space list

# To list the spaces of a specific identity
$ ockam space list --identity i2

space show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam space show [OPTIONS] <NAME>

This command will show all the details of a space such as its name, ID, and users that have access to it.

Arguments

  • <NAME>
    Name of the space

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

Examples

# To show a space with a specific name
$ ockam space show s

ockam project


ockam project <COMMAND>

In Ockam, a project is a collection of nodes and services that work together to achieve a common goal. The project also includes an Elastic Relay Service that can be used to create end-to-end secure channels.

When you enroll in Ockam, a project is created for you and you can create nodes and services within that project using the Ockam CLI.

Subcommands

project create


ockam project create [OPTIONS] <SPACE_NAME> [PROJECT_NAME]

This command will create a new project within the given space. If the project already exists, it will just fetch it and show its details.

Arguments

  • <SPACE_NAME>
    Name of the Space the project belongs to

  • [PROJECT_NAME] (optional)
    Name of the project - must be unique within parent Space

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

Examples

# To create a new project with a random name
$ ockam project create myspace

# To create a new project with a specific name
$ ockam project create myspace myproject

project delete


ockam project delete [OPTIONS] <SPACE_NAME> <PROJECT_NAME>

This command will delete the specified project. Deleting a project implies deleting all the resources and services available for that project.

Arguments

  • <SPACE_NAME>
    Name of the space

  • <PROJECT_NAME>
    Name of the project

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a project given its name
$ ockam project delete myspace myproject

project list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam project list [OPTIONS]

This command will show the details of all the available projects across the user's spaces.

By default, it will access the spaces associated to the default identity. This can be overridden by passing the --identity flag.

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

Examples

# To list the projects of the default identity
$ ockam project list

# To list the spaces of a specific identity
$ ockam project list --identity i2

project show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam project show [OPTIONS] <NAME>

This command will show all the details of a project such as its name, ID, and associated space.

Arguments

  • <NAME>
    Name of the project

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

Examples

# To show a project with a specific name
$ ockam project show myspace myproject

project version


ockam project version [OPTIONS]

This command will return the version of the projects.

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name
# To retrieve the version of the projects
$ ockam project version

project information


ockam project information [OPTIONS] [NAME]

Arguments

  • [NAME] (optional)
    Name of the project

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • --as-trust-context (optional)

project ticket


ockam project ticket [OPTIONS]

Ockam offers several pluggable enrollment protocols. This command allows project administrators to enroll known identities or create an one-time enrollment ticket that can be used later on the end device to enroll themselves into the project.

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • --project-path [PROJECT_JSON_PATH] (optional)
    Project config file

  • --trust-context [TRUST_CONTEXT_NAME | TRUST_CONTEXT_JSON_PATH] (optional)
    Trust Context config file

  • --project [PROJECT_NAME] (optional)

  • -m, --member [MEMBER] (optional)

  • -t, --to [TO] (optional)

  • -a, --attribute [ATTRIBUTE] (optional)
    Attributes in key=value format to be attached to the member

  • --expires-in [DURATION] (optional)

  • --usage-count [USAGE_COUNT] (optional)

Examples

# To enroll a known identity
$ ockam project ticket --member id_identifier

# To generate an enrollment ticket that can be used to enroll a device
$ ockam project ticket --attribute component=control

project addon


ockam project addon [OPTIONS] <COMMAND>

Manage addons for a project

Subcommands

project addon list


ockam project addon list --project <PROJECT_NAME>

List available addons for a project

Options

  • --project <PROJECT_NAME>
    Project name

project addon disable


ockam project addon disable --project <PROJECT_NAME> --addon <ADDON_ID>

Disable an addon for a project

Options

  • --project <PROJECT_NAME>
    Project name

  • --addon <ADDON_ID>
    Addon id/name

project addon configure


ockam project addon configure <COMMAND>

Subcommands

project addon configure okta


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam project addon configure okta [OPTIONS] --tenant <TENANT> --client-id <CLIENT_ID>

InfluxDB Cloud addon allows you to create, store and retrieve InfluxDB Tokens with expiry times.

Options

  • --project [PROJECT_NAME] (optional)
    Ockam Project name

  • --tenant <TENANT>
    Okta Plugin tenant URL

  • --cert [CERTIFICATE] (optional)
    Okta Certificate. Use either this or --cert-path

  • --cert-path [CERTIFICATE_PATH] (optional)
    Okta Certificate file path. Use either this or --cert

  • --client-id <CLIENT_ID>
    Okta Client ID

  • -a, --attribute [ATTRIBUTE] (optional)
    Attributes names to copy from Okta userprofile into Ockam credential

Examples

Examples of how to configure and use the InfluxDB Cloud addon can be found within the example documentation:

  • https://docs.ockam.io/guides/examples/influxdb-cloud-token-lease-management

project addon configure influxdb


ockam project addon configure influxdb [OPTIONS] --endpoint-url <ENDPOINT_URL> --token <INFLUXDB_TOKEN> --org-id <ORGANIZATION_ID>

InfluxDB Cloud addon allows you to create, store and retrieve InfluxDB Tokens with expiry times.

Options

  • --project [PROJECT_NAME] (optional)
    Ockam Project Name

  • -e, --endpoint-url <ENDPOINT_URL>
    Url of the InfluxDB instance

  • -t, --token <INFLUXDB_TOKEN>
    InfluxDB Token with permissions to perform CRUD token operations

  • -o, --org-id <ORGANIZATION_ID>
    InfluxDB Organization ID

  • --permissions [PERMISSIONS_JSON] (optional)
    InfluxDB Permissions as a JSON String https://docs.influxdata.com/influxdb/v2.0/api/#operation/PostAuthorizations

  • --permissions-path [PERMISSIONS_JSON_PATH] (optional)
    InfluxDB Permissions JSON PATH. Use either this or --permissions

  • --max-ttl [MAX_TTL_SECS] (optional)
    Max TTL of Tokens within the Lease Manager [Defaults to 3 Hours]

  • --user-access-role [USER_ACCESS_ROLE] (optional)
    Ockam Access Rule for who can use the token lease service

  • --adamin-access-role [ADMIN_ACCESS_ROLE] (optional)
    Ockam Access Rule for who can manage the token lease service

Examples

Examples of how to configure and use the InfluxDB Cloud addon can be found within the example documentation:

  • https://docs.ockam.io/guides/examples/influxdb-cloud-token-lease-management

project addon configure confluent


ockam project addon configure confluent [OPTIONS] --bootstrap-server <BOOTSTRAP_SERVER>

Confluent Cloud addon allows you to enable end-to-end encryption with your Kafka Consumers and Kafka Producers.

Options

  • --project [PROJECT_NAME] (optional)
    Ockam project name

  • --bootstrap-server <BOOTSTRAP_SERVER>
    Confluent Cloud bootstrap server address

Examples

Examples of how to configure and use the Confluent Cloud addon can be found within the example documentation:

  • https://docs.ockam.io/guides/examples/end-to-end-encrypted-kafka

project enroll


ockam project enroll [OPTIONS] [ENROLLMENT TICKET PATH | ENROLLMENT TICKET]

Ockam offers several pluggable enrollment protocols. One simple option is to use one-time-use enrollment ticket. This is a great option to enroll large fleets of applications, service, or devices. It is also easy to use with automated provisioning scripts and tools.

With this command you can use an enrollment ticket generated with the ockam project ticket command to enroll an identity to a project.

Arguments

  • [ENROLLMENT TICKET PATH | ENROLLMENT TICKET] (optional)

Options

  • --okta (optional)

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • --project-path [PROJECT_JSON_PATH] (optional)
    Project config file

  • --trust-context [TRUST_CONTEXT_NAME | TRUST_CONTEXT_JSON_PATH] (optional)
    Trust Context config file

  • --project [PROJECT_NAME] (optional)

  • --new-trust-context-name [NEW_TRUST_CONTEXT_NAME] (optional)
    Name of the new trust context to create, defaults to project name

  • --force (optional)
    Execute enrollment even if the trust context already exists

Examples

# From the admin machine, generate an enrollment ticket
$ ticket=$(ockam project ticket --attribute component=user)

# From the user machine, enroll the local identity to the project using the enrollment ticket
$ ockam project enroll $ticket --identity control_identity

ockam sidecar


ockam sidecar <COMMAND>

This command starts sidecar, every sidecar is thought to be standalone and can be executed locally or within a docker container. You can also customize recipes to fit your needs by running the sidecar with --dry-run parameter and then editing the generated recipe. To execute a recipe, use ockam run.

Subcommands

sidecar secure-relay-inlet


ockam sidecar secure-relay-inlet [OPTIONS] <--enroll-ticket <ENROLLMENT TICKET PATH>|--okta> <SERVICE NAME>

This sidecar starts a TCP inlet listening in the provided port. It requires a valid enrollment mechanism. The portal will be named and inlet and outlet name must match.

Arguments

  • <SERVICE NAME>
    The name of the service

Options

  • --from [SOCKET_ADDRESS] (optional)
    Address on which to accept tcp connections

  • --dry-run (optional)
    Just print the recipe and exit

  • --enroll-ticket [ENROLLMENT TICKET PATH] (optional)
    Enrollment ticket to use

  • --okta (optional)
    If using Okta enrollment

Examples

# Starts the inlet relay listening in port 5432 with a service called `postgresql-production`
ockam sidecar secure-relay-inlet --from 127.0.0.1:5432 --enrollment-ticket ./ticket postgresql-production

# Prints the recipe without executing any command, can be used with `ockam run`
ockam sidecar secure-relay-inlet --from 127.0.0.1:5432 --enrollment-ticket ./ticket --dry-run postgresql-production

# Starts an inlet relay service called `my-http-service` listening on port 6000 inside a docker container
docker run --name my-http-service -ti -p 6000:6000 --volume /tmp/ticket_for_docker:/ticket ockam sidecar secure-relay-inlet --from 0.0.0.0:6000 --enrollment-ticket /ticket my-http-service

sidecar secure-relay-outlet


ockam sidecar secure-relay-outlet [OPTIONS] --to <SOCKET_ADDRESS> <--enroll-ticket <ENROLLMENT TICKET PATH>|--okta> <SERVICE NAME>

This sidecar starts a TCP outlet connecting to the provided address. It requires a valid enrollment mechanism. The portal will be named and inlet and outlet name must match.

Arguments

  • <SERVICE NAME>
    The name of the service

Options

  • --to <SOCKET_ADDRESS>
    TCP address to send raw tcp traffic

  • --dry-run (optional)
    Just print the recipe and exit

  • --enroll-ticket [ENROLLMENT TICKET PATH] (optional)
    Enrollment ticket to use

  • --okta (optional)
    If using Okta enrollment

Examples

# Starts the outlet connecting to localhost port 5432, with a named service `postgresql-production`
ockam sidecar secure-relay-outlet --to 127.0.0.1:5432 --enrollment-ticket ./ticket postgresql-production

# Prints the recipe without executing any command, can be used with `ockam run`
ockam sidecar secure-relay-outlet --to 127.0.0.1:5432 --enrollment-ticket ./ticket --dry-run postgresql-production

# Starts an outlet relay service called `my-http-service` listening connecting to port 5000 inside a docker container
docker run --name my-http-service -ti --volume /tmp/ticket_for_docker:/ticket ockam sidecar secure-relay-outlet --to 127.0.0.1:5000 --enrollment-ticket /ticket my-http-service

ockam share


ockam share <COMMAND>

Manage sharing invitations in Ockam Orchestrator

Subcommands

share accept


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam share accept [OPTIONS] <ID>

Accept a received sharing invitation

Arguments

  • <ID>

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

share create


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam share create [OPTIONS] <SCOPE> <TARGET_ID> <RECIPIENT_EMAIL>

Create an invitation for another user to join a Space or Project

Arguments

  • <SCOPE>
  • <TARGET_ID>
  • <RECIPIENT_EMAIL>

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • -R, --grant-role [GRANT_ROLE] (optional)

  • -x, --expires-at [EXPIRES_AT] (optional)

share list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam share list [OPTIONS]

List sharing invitations you've created or received

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

share revoke


ockam share revoke

Revoke a sharing invitation you've previously created

share service


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam share service [OPTIONS] <PROJECT_ID> <RECIPIENT_EMAIL> <PROJECT_IDENTITY> <PROJECT_ROUTE> <PROJECT_AUTHORITY_IDENTITY> <PROJECT_AUTHORITY_ROUTE> <SHARED_NODE_IDENTITY> <SHARED_NODE_ROUTE> <ENROLLMENT_TICKET>

Create a sharing invitation for a single service

Arguments

  • <PROJECT_ID>
  • <RECIPIENT_EMAIL>
  • <PROJECT_IDENTITY>
  • <PROJECT_ROUTE>
  • <PROJECT_AUTHORITY_IDENTITY>
  • <PROJECT_AUTHORITY_ROUTE>
  • <SHARED_NODE_IDENTITY>
  • <SHARED_NODE_ROUTE>
  • <ENROLLMENT_TICKET>

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • -x, --expires-at [EXPIRES_AT] (optional)

share show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam share show [OPTIONS] <INVITATION_ID>

Show information about a single invitation you own or received, including service access details

Arguments

  • <INVITATION_ID>

Options

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

ockam node


ockam node <COMMAND>

An Ockam node is any running application that can communicate with other applications using various Ockam protocols like Routing, Secure Channels, Relays etc.

We can create Ockam nodes using the Ockam CLI or using various Ockam programming libraries like our Rust and Elixir libraries.

Subcommands

Examples

# Create two nodes
$ ockam node create n1
$ ockam node create n2

# Send a message to the uppercase service on node 2
$ ockam message send hello --to /node/n2/service/uppercase
HELLO

# A more verbose version of the above would be,
# assuming n2 started its tcp listener on port 4000.
$ ockam message send hello --to /ip4/127.0.0.1/tcp/4000/service/uppercase
HELLO

# Send a message to the uppercase service on node n2 from node n1
$ ockam message send hello --from /node/n1 --to /node/n2/service/uppercase
HELLO

# Create a secure channel from node n1 to the api service on node n2
# The /service/api is a secure channel listener that is started on every node
# Send a message through this encrypted channel to the uppercase service
$ ockam secure-channel create --from /node/n1 --to /node/n2/service/api \\
    | ockam message send hello --from /node/n1 --to -/service/uppercase
HELLO

# Create a node, with a specified tcp listener address
$ ockam node create n1 --tcp-listener-address 127.0.0.1:6001

# Create a node, and run it in the foreground with verbose traces
$ ockam node create n1 --foreground -vvv

# Show information about a specific node
$ ockam node show n1

# List all created nodes
$ ockam node list

# Delete the node
$ ockam node delete n1

# Delete all nodes
$ ockam node delete --all

# Delete all nodes and force cleanup
$ ockam node delete --all --force

node create


ockam node create [OPTIONS] [NODE_NAME]

This command will create a new node. It will create a vault and identity if none exist and will be assigned as the default for the system.

When creating a node, a pre-defined set of default services will be started, including:

  • An uppercase service at /service/uppercase
  • A secure channel listener at /service/api
  • A tcp listener listening at some TCP port picked by the operating system. After creating a node, you can use the ockam node show command to see the port that was assigned to it.

Services are one or more Ockam Workers identified by addresses of the form /service/{ADDRESS}. Services can be attached to identities and authorization policies to enforce attribute based access control (ABAC) rules.

Arguments

  • [NODE_NAME] (optional)
    Name of the node

Options

  • -f, --foreground (optional)
    Run the node in foreground

  • -e, --exit-on-eof (optional)
    Watch stdin for EOF

  • -t, --tcp-listener-address [SOCKET_ADDRESS] (optional)
    TCP listener address

  • --child-process (optional)
    node create started a child process to run this node in foreground

  • --launch-config [LAUNCH_CONFIG] (optional)
    JSON config to setup a foreground node

  • --trusted-identities [TRUSTED_IDENTITIES] (optional)

  • --trusted-identities-file [TRUSTED_IDENTITIES_FILE] (optional)

  • --reload-from-trusted-identities-file [RELOAD_FROM_TRUSTED_IDENTITIES_FILE] (optional)

  • --vault [VAULT_NAME] (optional)
    Name of the Vault that the node will use

  • --identity [IDENTITY_NAME] (optional)
    Name of the Identity that the node will use

  • --authority-identity [AUTHORITY_IDENTITY] (optional)

  • --credential [CREDENTIAL_NAME] (optional)

  • --project-path [PROJECT_JSON_PATH] (optional)
    Project config file

  • --trust-context [TRUST_CONTEXT_NAME | TRUST_CONTEXT_JSON_PATH] (optional)
    Trust Context config file

  • --project [PROJECT_NAME] (optional)

Examples

# To create a new node with a random name
$ ockam node create

# To create a new node with a specific name
$ ockam node create n

node delete


ockam node delete [OPTIONS] [NODE_NAME]

This command will delete the specified node or all the available nodes if the --all flag is used. Deleting a node implies killing the process and removing its data directory. To temporary pause a node use ockam node stop instead.

Arguments

  • [NODE_NAME] (optional)
    Name of the node to be deleted

Options

  • -a, --all (optional)
    Terminate all node processes and delete all node configurations

  • -f, --force (optional)
    Terminate node process(es) immediately (uses SIGKILL instead of SIGTERM)

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete the default node
$ ockam node delete

# To delete a node given its name
$ ockam node delete n

# To delete all existing nodes
$ ockam node delete --all

node list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam node list

This command will show the details of all the nodes registered in the system.

Examples

$ ockam node list

node logs


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam node logs [NODE_NAME]

This command will return the path to the node's log file. The user can select whether to return the stdout or the stderr log file. The default is to return the stdout log file.

Arguments

  • [NODE_NAME] (optional)
    Name of the node to retrieve the logs from

Examples

# Return the path to the stdout log file of the default node
$ ockam node logs

# Return the path to the stderr log file of the given node
$ ockam node logs n --err

# Pipe the logs to a file into another tool to process it
$ cat < $(ockam node logs n)

node show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam node show [NODE_NAME]

This command will show all the details of a node such as its name, route, default identity, and the services running on it.

Arguments

  • [NODE_NAME] (optional)
    Name of the node to retrieve the details from

Examples

# To show the default node
$ ockam node show

# To show a node with a specific name
$ ockam node show n

node start


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam node start [OPTIONS] [NODE_NAME]

This command will start a node as a background process that was previously stopped via the command ockam node stop. The node will be started with the same configuration as when it was created.

Arguments

  • [NODE_NAME] (optional)
    Name of the node to be started

Options

  • --aws-kms (optional)

Examples

# To start the default node
$ ockam node start

# To start a node with a specific name
$ ockam node start n

node stop


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam node stop [OPTIONS] [NODE_NAME]

This command will a running node, killing the associated background process. This operation will keep the node state in the $OCKAM_HOME directory, so it can be restarted with ockam node start.

Arguments

  • [NODE_NAME] (optional)
    Name of the node

Options

  • -f, --force (optional)
    Whether to use the SIGTERM or SIGKILL signal to stop the node

Examples

# To stop the default node sending a SIGTERM signal
$ ockam node stop

# To stop the given node sending a SIGKILL signal
$ ockam node stop n --force

node default


ockam node default [NODE_NAME]

This command will change the default node. The default node is used by most of the commands when none is specified.

Arguments

  • [NODE_NAME] (optional)
    Name of the node to set as default

Examples

# The first created node will be set as the default node
$ ockam node create n1

# Let's create a second node and assign it as default
$ ockam node create n2
$ ockam node default n2

ockam worker


ockam worker <COMMAND>

Ockam nodes run very lightweight, concurrent, stateful actors called Ockam Workers. Workers have addresses and a node can deliver messages to workers on the same node or on a different node using the Ockam Routing Protocol and its Transports. One or more workers can work as a team to offer a service.

Subcommands

worker list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam worker list [OPTIONS]

When creating a new node, a set of default services are started. This command lists all the available workers on a given node, which can be helpful to check if all the services are running, or to check the workers' addresses associated to secure channels or relays created by the node.

Options

  • --at [NODE] (optional)
    Node at which to lookup workers

Examples

# Create a node
$ ockam node create n1

# List the workers available in the node
$ ockam worker list --at n1

ockam message


ockam message <COMMAND>

Send and receive messages

Subcommands

message send


ockam message send [OPTIONS] --to <ROUTE> <MESSAGE>

This command is used to send messages between Ockam nodes. In order to use this command, you need to specify at least the recipient of the message, which is an address to a service of an Ockam node. Optionally, you can specify the sender node. If not provided, a temporary node will be created for the duration of the command to perform the operation.

Arguments

  • <MESSAGE>

Options

  • -f, --from [NODE] (optional)
    The node to send messages from

  • -t, --to <ROUTE>
    The route to send the message to

  • --hex (optional)
    Flag to indicate that the message is hex encoded

  • --timeout [TIMEOUT] (optional)
    Override default timeout

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • --project-path [PROJECT_JSON_PATH] (optional)
    Project config file

  • --trust-context [TRUST_CONTEXT_NAME | TRUST_CONTEXT_JSON_PATH] (optional)
    Trust Context config file

  • --project [PROJECT_NAME] (optional)

Examples

# Create two nodes
$ ockam node create n1
$ ockam node create n2

# Send a message to the uppercase service on node 2
$ ockam message send hello --to /node/n2/service/uppercase
HELLO

# A more verbose version of the above would be,
# assuming n2 started its tcp listener on port 4000.
$ ockam message send hello --to /ip4/127.0.0.1/tcp/4000/service/uppercase
HELLO

# Send a message to the uppercase service on node n2 from node n1
$ ockam message send hello --from /node/n1 --to /node/n2/service/uppercase
HELLO

# Create a secure channel from node n1 to the api service on node n2
# The /service/api is a secure channel listener that is started on every node
# Send a message through this encrypted channel to the uppercase service
$ ockam secure-channel create --from /node/n1 --to /node/n2/service/api \\
    | ockam message send hello --from /node/n1 --to -/service/uppercase
HELLO

ockam relay


ockam relay <COMMAND>

Communication topologies often encounter situations where the machine providing a service cannot or will not open a listening port or expose a bridge node to other networks. This is a common security best practice in enterprise environments, home networks, OT networks, and VPCs across clouds. Application developers may not have control over these choices from the infrastructure/operations layer. In such cases, relays are useful.

Relays make it possible to establish end-to-end protocols with services operating in a remote private networks, without requiring a remote service to expose listening ports to an outside hostile network like the Internet.

Subcommands

Examples

# Create two nodes blue and green
$ ockam node create blue
$ ockam node create green

# Create a relay to node blue at node green
$ ockam relay create blue --at /node/green --to /node/blue

# Send a message to the uppercase service on blue via its relay on green
$ ockam message send hello --to /node/green/service/forward_to_blue/service/uppercase

This can be very useful in establishing communication between applications that cannot otherwise reach each other over the network.

For instance, we can use relays to create an end-to-end secure channel between two nodes that are behind private NATs:

# Create another node called yellow
$ ockam node create yellow

# Create an end-to-end secure channel between yellow and blue.
# This secure channel is created through blue's relay at green, and we can
# send end-to-end encrypted messages through it.
$ ockam secure-channel create --from /node/yellow --to /node/green/service/forward_to_blue/service/api \\
    | ockam message send hello --from /node/yellow --to -/service/uppercase

In this topology green acts as an encrypted relay between yellow and blue. Yellow and blue can be running in completely separate private networks. Green needs to be reachable from both yellow and blue and only sees encrypted traffic.

You can find more details within the documentation:

  • https://docs.ockam.io/reference/command/advanced-routing#relays

relay create


ockam relay create [OPTIONS] [RELAY_NAME]

Create a Relay. If no arguments are passed in, and you are enrolled in Orchestrator, then it creates a Relay at the default Orchestrator project, to the local default node.

Arguments

  • [RELAY_NAME] (optional)
    Name of the relay

Options

  • --to [NODE] (optional)
    Node for which to create the relay

  • --at [ROUTE] (optional)
    Route to the node at which to create the relay

  • --authorized [AUTHORIZED] (optional)
    Authorized identity for secure channel connection

Examples

$ ockam relay create r --at n1 --to n2

relay list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam relay list [OPTIONS]

List Relays on your default node. If you pass '--to ' then it lists the Relays at the given node.

Options

  • --to [NODE] (optional)
    Get the list of Relays at the given node

Examples

$ ockam relay list --to n2

relay show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam relay show [OPTIONS] <REMOTE_ADDRESS>

Show a Relay by its alias

Arguments

  • <REMOTE_ADDRESS>
    Name assigned to relay that will be shown (prefixed with forward_to_)

Options

  • --at [NODE] (optional)
    Node which relay belongs to

Examples

$ ockam relay show forward_to_r --at n2

relay delete


ockam relay delete [OPTIONS] <RELAY_NAME>

Delete a Relay

Arguments

  • <RELAY_NAME>
    Name assigned to Relay that will be deleted

Options

  • --at [NODE] (optional)
    Node on which to delete the Relay. If not provided, the default node will be used

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

$ ockam relay delete forward_to_r --at n2

ockam tcp-listener


ockam tcp-listener <COMMAND>

Manage TCP Listeners

Subcommands

tcp-listener create


ockam tcp-listener create [OPTIONS] <ADDRESS>

Create tcp listener on the selected node

Arguments

  • <ADDRESS>
    Address for this listener (eg. 127.0.0.1:7000)

Options

  • --at [NODE] (optional)
    Node at which to create the listener

Examples

# To create a new TCP listener at the given address using the default node
$ ockam tcp-listener create 127.0.0.1:5000

# To create a new TCP listener at the given address using a specific node
$ ockam tcp-listener create 127.0.0.1:5000 --at n1

tcp-listener delete


ockam tcp-listener delete [OPTIONS] <ADDRESS>

Delete tcp listener on the selected node

Arguments

  • <ADDRESS>
    Tcp Listener ID

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a TCP listener given its ID on the default node
$ ockam tcp-listener delete d59c01ab8d9683f8c454df746e627b43

# To delete a TCP listener given its ID on a specific node
$ ockam tcp-listener delete d59c01ab8d9683f8c454df746e627b43 --at n1

tcp-listener list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-listener list [OPTIONS]

List tcp listeners registered on the selected node

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the TCP listeners on the default node
$ ockam tcp-listener list

# To list the TCP listeners on a specific node
$ ockam tcp-listener list --at n1

tcp-listener show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-listener show [OPTIONS] <ADDRESS>

Show tcp listener details

Arguments

  • <ADDRESS>
    TCP listener Worker Address or Tcp Address

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To show a TCP listener given its ID
$ ockam tcp-listener show d59c01ab8d9683f8c454df746e627b43

ockam tcp-connection


ockam tcp-connection <COMMAND>

Manage TCP Connections

Subcommands

tcp-connection create


ockam tcp-connection create [OPTIONS] --to <ADDRESS>

Create a TCP connection

Options

  • -f, --from [NODE] (optional)
    Node that will initiate the connection

  • -t, --to <ADDRESS>
    The address to connect to

Examples

# To create a new TCP connection at the given address using the default node
$ ockam tcp-connection create --to 127.0.0.1:5000

# To create a new TCP connection at the given address using a specific node
$ ockam tcp-connection create --from n1 --to 127.0.0.1:5000

tcp-connection delete


ockam tcp-connection delete [OPTIONS] <ADDRESS>

Delete a TCP connection

Arguments

  • <ADDRESS>
    TCP connection ID

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a TCP connection given its ID on the default node
$ ockam tcp-connection delete d59c01ab8d9683f8c454df746e627b43

# To delete a TCP connection given its ID on a specific node
$ ockam tcp-connection delete d59c01ab8d9683f8c454df746e627b43 --at n1

tcp-connection list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-connection list [OPTIONS]

List TCP connections

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the TCP connections on the default node
$ ockam tcp-connection list

# To list the TCP connections on a specific node
$ ockam tcp-connection list --at n1

tcp-connection show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-connection show [OPTIONS] <ADDRESS>

Show a TCP connection

Arguments

  • <ADDRESS>
    TCP connection Worker Address or Tcp Address

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To show a TCP connection given its ID
$ ockam tcp-connection show d59c01ab8d9683f8c454df746e627b43

ockam tcp-outlet


ockam tcp-outlet <COMMAND>

A TCP Outlet makes a TCP service available on a worker address (allows data to be transmitted to a listener on a TCP address). It is one end of a portal (tcp-inlet being the other), which receives Ockam Routing messages, unwraps them to extract TCP data and sends that data along to the target service.

Subcommands

Examples

# Create a target service, we'll use a simple http server for this example
$ python3 -m http.server --bind 127.0.0.1 5000

# Create two nodes
$ ockam node create n1
$ ockam node create n2

# Create a TCP outlet from n1 to the target server
$ ockam tcp-outlet create --at /node/n1 --to 127.0.0.1:5000

# Create a TCP inlet from n2 to the outlet on n1
$ ockam tcp-inlet create --at /node/n2 --from 127.0.0.1:6000 --to /node/n1/service/outlet

# Access the service via the inlet/outlet pair
$ curl 127.0.0.1:6000

tcp-outlet create


ockam tcp-outlet create [OPTIONS] --to <SOCKET_ADDRESS>

Create a TCP Outlet

Options

  • --at [NODE] (optional)
    Node on which to start the tcp outlet

  • --from [OUTLET_ADDRESS] (optional)
    Address of the tcp outlet

  • --to <SOCKET_ADDRESS>
    TCP address to send raw tcp traffic

  • --alias [ALIAS] (optional)
    Assign a name to this outlet

Examples

# To create a new TCP outlet at the given address using the default node
$ ockam tcp-outlet create --to 127.0.0.1:5000

# To create a new TCP outlet at the given address using a specific node
$ ockam tcp-outlet create --at n1 --to 127.0.0.1:5000

tcp-outlet delete


ockam tcp-outlet delete [OPTIONS] <ALIAS>

Delete a TCP Outlet

Arguments

  • <ALIAS>
    Delete the outlet with this alias

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a TCP outlet given its alias on the default node
$ ockam tcp-outlet delete myoutlet

# To delete a TCP outlet given its alias on a specific node
$ ockam tcp-outlet delete myoutlet --at n1

tcp-outlet list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-outlet list [OPTIONS]

List TCP Outlets on the default node

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the TCP outlets on the default node
$ ockam tcp-outlet list

# To list the TCP outlets on a specific node
$ ockam tcp-outlet list --at n1

tcp-outlet show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-outlet show [OPTIONS] <ALIAS>

Show a TCP Outlet's details

Arguments

  • <ALIAS>
    Name assigned to outlet that will be shown

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To show a TCP outlet given its alias
$ ockam tcp-outlet show myoutlet

ockam tcp-inlet


ockam tcp-inlet <COMMAND>

A TCP inlet is a way of defining where a node should be listening for connections, and where it should forward that traffic to. It is one end (tcp-outlet being the other) of a portal, which receives TCP data, chunks and wraps them into Ockam Routing messages and sends them along the supplied route.

Subcommands

Examples

# Create a target service, we'll use a simple http server for this example
$ python3 -m http.server --bind 127.0.0.1 5000

# Create two nodes
$ ockam node create n1
$ ockam node create n2

# Create a TCP outlet from n1 to the target server
$ ockam tcp-outlet create --at /node/n1 --to 127.0.0.1:5000

# Create a TCP inlet from n2 to the outlet on n1
$ ockam tcp-inlet create --at /node/n2 --from 127.0.0.1:6000 --to /node/n1/service/outlet

# Access the service via the inlet/outlet pair
$ curl 127.0.0.1:6000

tcp-inlet create


ockam tcp-inlet create [OPTIONS]

Create TCP Inlets

Options

  • --at [NODE] (optional)
    Node on which to start the tcp inlet

  • --from [SOCKET_ADDRESS] (optional)
    Address on which to accept tcp connections

  • --to [ROUTE] (optional)
    Route to a tcp outlet

  • --authorized [AUTHORIZED] (optional)
    Authorized identity for secure channel connection

  • --alias [ALIAS] (optional)
    Assign a name to this inlet

  • --connection-wait [WAIT] (optional)
    Time to wait for the outlet to be available

  • --retry-wait [RETRY] (optional)
    Time to wait before retrying to connect to outlet

  • --timeout [TIMEOUT] (optional)
    Override default timeout

Examples

# To create a new TCP inlet at the given address using the default node
$ ockam tcp-inlet create --from 127.0.0.1:5000 --to /node/n1/service/outlet

# To create a new TCP inlet at the given address using a specific node
$ ockam tcp-inlet create --at n2 --from 127.0.0.1:5000 --to /node/n1/service/outlet

tcp-inlet delete


ockam tcp-inlet delete [OPTIONS] <ALIAS>

Delete a TCP Inlet

Arguments

  • <ALIAS>
    Delete the inlet with this alias

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a TCP inlet given its alias on the default node
$ ockam tcp-inlet delete myinlet

# To delete a TCP inlet given its ID on a specific node
$ ockam tcp-inlet delete myinlet --at n1

tcp-inlet list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-inlet list [OPTIONS]

List TCP Inlets on the default node

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the TCP inlets on the default node
$ ockam tcp-inlet list

# To list the TCP inlets on a specific node
$ ockam tcp-inlet list --at n1

tcp-inlet show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam tcp-inlet show [OPTIONS] <ALIAS>

Show a TCP Inlet's details

Arguments

  • <ALIAS>
    Name of the inlet

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To show a TCP inlet given its alias
$ ockam tcp-inlet show myinlet

ockam kafka-outlet


ockam kafka-outlet <COMMAND>

Manage Kafka Outlets

Subcommands

kafka-outlet create


ockam kafka-outlet create [OPTIONS]

Create a new Kafka Outlet

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • --addr [ADDR] (optional)
    The local address of the service

  • --bootstrap-server [BOOTSTRAP_SERVER] (optional)
    The address of the kafka bootstrap broker

ockam kafka-consumer


ockam kafka-consumer <COMMAND>

Manage Kafka Consumers

Subcommands

kafka-consumer create


ockam kafka-consumer create [OPTIONS]

Create a new Kafka Consumer

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • --addr [ADDR] (optional)
    The local address of the service

  • --bootstrap-server [BOOTSTRAP_SERVER] (optional)
    The address where to bind and where the client will connect to alongside its port,

    :. In case just a port is specified, the default loopback address (127.0.0.1) will be used

  • --brokers-port-range [BROKERS_PORT_RANGE] (optional)
    Local port range dynamically allocated to kafka brokers, must not overlap with the bootstrap port

  • --project-route [PROJECT_ROUTE] (optional)
    The route to the project in ockam orchestrator, expected something like /project/

kafka-consumer delete


ockam kafka-consumer delete [OPTIONS] <ADDRESS>

Delete a Kafka Consumer

Arguments

  • <ADDRESS>
    Kafka consumer service address

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To delete a kafka consumers on the default node
$ ockam kafka-consumer delete kcaddr

# To delete a kafka consumers on a specific node
$ ockam kafka-consumer delete kcaddr --at n

kafka-consumer list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam kafka-consumer list [OPTIONS]

List Kafka Consumers

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the kafka consumers on the default node
$ ockam kafka-consumer list

# To list the kafka consumers on a specific node
$ ockam kafka-consumer list --at n

ockam kafka-direct


ockam kafka-direct <COMMAND>

Manage Kafka Consumers

Subcommands

kafka-direct create


ockam kafka-direct create [OPTIONS]

Create a new Kafka Direct Consumer

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • --addr [ADDR] (optional)
    The local address of the service

  • --bind-address [BIND_ADDRESS] (optional)
    The address where to bind and where the client will connect to alongside its port,

    :. In case just a port is specified, the default loopback address (127.0.0.1) will be used

  • --bootstrap-server [BOOTSTRAP_SERVER] (optional)
    The address of the kafka bootstrap broke

  • --brokers-port-range [BROKERS_PORT_RANGE] (optional)
    Local port range dynamically allocated to kafka brokers, must not overlap with the bootstrap port

  • --consumer-route [CONSUMER_ROUTE] (optional)
    The route to another kafka consumer node

kafka-direct delete


ockam kafka-direct delete [OPTIONS] <ADDRESS>

Delete a Kafka Consumer

Arguments

  • <ADDRESS>
    Kafka consumer service address

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To delete a kafka consumers on the default node
$ ockam kafka-consumer delete kcaddr

# To delete a kafka consumers on a specific node
$ ockam kafka-consumer delete kcaddr --at n

kafka-direct list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam kafka-direct list [OPTIONS]

List Kafka Consumers

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the kafka consumers on the default node
$ ockam kafka-consumer list

# To list the kafka consumers on a specific node
$ ockam kafka-consumer list --at n

ockam kafka-producer


ockam kafka-producer <COMMAND>

Manage Kafka Producers

Subcommands

kafka-producer create


ockam kafka-producer create [OPTIONS]

Create a new Kafka Producer

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • --addr [ADDR] (optional)
    The local address of the service

  • --bootstrap-server [BOOTSTRAP_SERVER] (optional)
    The address where to bind and where the client will connect to alongside its port,

    :. In case just a port is specified, the default loopback address (127.0.0.1) will be used

  • --brokers-port-range [BROKERS_PORT_RANGE] (optional)
    Local port range dynamically allocated to kafka brokers, must not overlap with the bootstrap port

  • --project-route [PROJECT_ROUTE] (optional)
    The route to the project in ockam orchestrator, expected something like /project/

kafka-producer delete


ockam kafka-producer delete [OPTIONS] <ADDRESS>

Delete a Kafka Producer

Arguments

  • <ADDRESS>
    Kafka producer service address

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To delete a kafka producers on the default node
$ ockam kafka-producer delete kcaddr

# To delete a kafka producers on a specific node
$ ockam kafka-producer delete kcaddr --at n

kafka-producer list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam kafka-producer list [OPTIONS]

List Kafka Producers

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

# To list the kafka producers on the default node
$ ockam kafka-producer list

# To list the kafka producers on a specific node
$ ockam kafka-producer list --at n

ockam secure-channel-listener


ockam secure-channel-listener <COMMAND>

Manage Secure Channel Listeners

Subcommands

secure-channel-listener create


ockam secure-channel-listener create [OPTIONS] <ADDRESS>

All nodes are created with a secure channel listener at /service/api.

You can use this command to start a custom listener with a specific name and authorization policies.

Arguments

  • <ADDRESS>
    Address for this listener

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • -a, --authorized [IDENTIFIERS] (optional)
    Authorized Identifiers of secure channel initiators

  • --vault [VAULT_NAME] (optional)
    Name of the Vault that the secure-channel listener will use

  • --identity [IDENTITY_NAME] (optional)
    Name of the Identity that the secure-channel listener will use

Examples

# Create a secure channel listener with a custom name on the default node
$ ockam secure-channel-listener create test --at n2
/service/test

# Create a secure channel from n1 to our test secure channel listener on n2
$ ockam secure-channel create --from /node/n1 --to /node/n2/service/test
/service/09738b73c54b81d48531f659aaa22533

secure-channel-listener delete


ockam secure-channel-listener delete [OPTIONS] <ADDRESS>

This command will delete a secure channel listener from a node. The user must pass the secure channel listener address and, optionally, the node where the secure channel was set up. Otherwise, the default node will be used.

Once deleted, it can't be recovered and a new one must be set up.

Arguments

  • <ADDRESS>
    Address at which the channel listener to be deleted is running

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

$ ockam secure-channel-listener delete scaddr --at n1

secure-channel-listener list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam secure-channel-listener list [OPTIONS]

This command will list all the secure channel listeners available in a node. If the node is not provided, the default node will be used.

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

$ ockam secure-channel-listener list --at n1

secure-channel-listener show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam secure-channel-listener show [OPTIONS] <ADDRESS>

This command will return the details of a secure channel listener. The user must pass the secure channel listener address and, optionally, the node where the secure channel was set up. Otherwise, the default node will be used.

Arguments

  • <ADDRESS>
    Address of the channel listener

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

Examples

$ ockam secure-channel-listener show scaddr --at n1

ockam secure-channel


ockam secure-channel <COMMAND>

Ockam Secure Channels is an end-to-end protocol built on top of Ockam Routing. This cryptographic protocol guarantees data authenticity, integrity, and confidentiality over any communication topology that can be traversed with Ockam Routing.

Subcommands

Examples

You can find more details and examples in the documentation:

  • https://docs.ockam.io/reference/command/secure-channels

secure-channel create


ockam secure-channel create [OPTIONS] --from <NODE> --to <ROUTE>

When a secure channel is created between two nodes they mutually authenticate each other using their Ockam Identity. Once the channel is created, you can send messages through through it using the returned address.

Options

  • --from <NODE>
    Node from which to initiate the secure channel

  • --to <ROUTE>
    Route to a secure channel listener

  • -a, --authorized [IDENTIFIER] (optional)
    Identifiers authorized to be presented by the listener

  • --identity [IDENTITY_NAME] (optional)
    Run the command as the given identity name

  • -c, --credential [CREDENTIAL] (optional)
    Name of a stored Credential to use within this Secure Channel

Examples

Every node, created with Ockam Command, starts a secure channel listener at address /service/api. Let's create a secure channel between two nodes and send a message from one node to another.

$ ockam node create a
$ ockam node create b
$ ockam secure-channel create --from a --to /node/b/service/api
  Created Secure Channel:
  • From: /node/a
  •   To: /node/b/service/api (/ip4/127.0.0.1/tcp/53483/service/api)
  •   At: /service/d92ef0aea946ec01cdbccc5b9d3f2e16

$ ockam message send hello --from a --to /service/d92ef0aea946ec01cdbccc5b9d3f2e16/service/uppercase
HELLO

secure-channel delete


ockam secure-channel delete [OPTIONS] <ADDRESS>

This command will delete a secure channel from a node. The user must pass the secure channel address and, optionally, the node where the secure channel was set up. Otherwise, the default node will be used.

Once deleted, it can't be recovered and a new one must be set up.

Arguments

  • <ADDRESS>
    Address at which the channel to be deleted is running

Options

  • --at [NODE] (optional)
    Node at which the secure channel was initiated

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

$ ockam secure-channel delete scaddr --at n1

secure-channel list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam secure-channel list [OPTIONS]

This command will list all the secure channels available in a node. If the node is not provided, the default node will be used.

Options

  • --at [NODE_NAME] (optional)
    Node at which the returned secure channels were initiated

Examples

$ ockam secure-channel list --at n1

secure-channel show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam secure-channel show [OPTIONS] <ADDRESS>

This command will return the details of a secure channel. The user must pass the secure channel address and, optionally, the node where the secure channel was set up. Otherwise, the default node will be used.

Arguments

  • <ADDRESS>
    Channel address

Options

  • --at [NODE_NAME] (optional)
    Node at which the secure channel was initiated

Examples

$ ockam secure-channel show scaddr --at n1

ockam vault


ockam vault <COMMAND>

A vault is a secure storage location for secret keys belonging to Ockam identities. Ockam Vaults safely store these secret keys in cryptographic hardware and cloud key management systems.

Vaults are designed to be used in a way that secret keys never have to leave a vault. There is a growing base of Ockam Vault implementations in the Ockam Github Repository that safely store secret keys in specific KMSs, HSMs, Secure Enclaves etc.

Subcommands

vault create


ockam vault create [OPTIONS] [NAME]

This command will create a new vault. By default, it creates a file system based vault, where Ockam Identities are stored at a specific file path.

Arguments

  • [NAME] (optional)

Options

  • --aws-kms (optional)

Examples

# To create a new vault with a random name
$ ockam vault create

# To create a new vault with a specific name
$ ockam vault create v

vault show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam vault show [NAME]

This command will show the details of a given vault, including its name, path and type.

Arguments

  • [NAME] (optional)
    Name of the vault

Examples

# To show the default vault
$ ockam vault show

# To show a specific vault
$ ockam vault show v1

vault delete


ockam vault delete [OPTIONS] <NAME>

This command will delete the specified vault. Note that the identities stored in the vault will become unusable. Use this command with caution.

Arguments

  • <NAME>
    Name of the vault

Options

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a vault given its name
$ ockam vault delete v

vault list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam vault list

This command will show the details of all the available vaults.

Examples

$ ockam vault list

vault default


ockam vault default <NAME>

This command will change the default vault. The default vault is used when creating a node if not specified otherwise.

Arguments

  • <NAME>
    Name of the vault to be set as default

Examples

# The first created vault will be set as the default vault
$ ockam vault create v1

# Let's create a second vault and assign it as default
$ ockam vault create v2
$ ockam vault default v2

ockam identity


ockam identity <COMMAND>

Ockam Identities are unique, cryptographically verifiable digital identities. These identities authenticate by proving possession of secret keys and are stored in Ockam Vaults. Each Ockam Identity has a unique public identifier, called the Ockam Identifier of this identity.

Subcommands

identity create


ockam identity create [OPTIONS] [NAME]

This command will create a new identity. It will create a vault if none exists and will be assigned as the default for the system.

Arguments

  • [NAME] (optional)

Options

  • --vault [VAULT_NAME] (optional)
    Vault name to store the identity key

  • -k, --key-id [KEY_ID] (optional)
    Key ID to use for the identity creation

Examples

# To create a new identity with a random name
$ ockam identity create

# To create a new identity with a specific name
$ ockam identity create i

# To create a new identity for a specific vault
$ ockam identity create --vault v

identity show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam identity show [OPTIONS] [NAME]

This command will show the identifier of a given identity. If the --full flag is passed, it will show the change history of the identity.

Arguments

  • [NAME] (optional)

Options

  • -f, --full (optional)
    Show the full identity history, and not just the identifier or the name

  • --encoding [ENCODING] (optional)

Examples

# To show the default identity
$ ockam identity show

# To show a specific identity
$ ockam identity show i

# To show the full details
$ ockam identity show --full

identity list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam identity list

This command will show the details of all the available identities.

Examples

$ ockam identity list

identity default


ockam identity default [NAME]

This command will change the default identity. The default identity is used when creating a node if not specified otherwise.

Arguments

  • [NAME] (optional)
    Name of the identity to be set as default

Examples

# The first created identity will be set as the default identity
$ ockam identity create i1

# Let's create a second identity and assign it as default
$ ockam identity create i2
$ ockam identity default i2

identity delete


ockam identity delete [OPTIONS] <NAME>

This command will delete the specified identity. If a running node is using that identity, it won't be deleted and an error will be raised.

Arguments

  • <NAME>
    Name of the identity to be deleted

Options

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete an identity given its name
$ ockam identity delete i

ockam credential


ockam credential <COMMAND>

Manage Credentials

Subcommands

credential get


ockam credential get [OPTIONS]

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • --overwrite (optional)

  • --identity [IDENTITY_NAME] (optional)
    Name of the Identity for which the credential was issued

credential issue


ockam credential issue [OPTIONS] --for <IDENTIFIER> [VAULT_NAME]

Arguments

  • [VAULT_NAME] (optional)
    Name of the Vault that will be used to issue the credential

Options

  • --as [IDENTITY_NAME] (optional)
    Name of the Identity to be used as the credential issuer

  • --for <IDENTIFIER>

  • -a, --attribute [ATTRIBUTE] (optional)
    Attributes in key=value format to be attached to the member

  • --encoding [ENCODE_FORMAT] (optional)
    Encoding Format

credential list


ockam credential list [VAULT_NAME]

Arguments

  • [VAULT_NAME] (optional)
    Name of the Vault from which to retrieve the credentials

credential present


ockam credential present [OPTIONS] --to <ROUTE>

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME

  • --to <ROUTE>

  • -o, --oneway (optional)

credential show


ockam credential show <CREDENTIAL_NAME> [VAULT_NAME]

Arguments

  • <CREDENTIAL_NAME>
  • [VAULT_NAME] (optional)
    Name of the Vault from which to retrieve the credential

credential store


ockam credential store [OPTIONS] --issuer <HEX_ENCODED_FULL_IDENTITY> [CREDENTIAL_NAME] [VAULT_NAME]

Arguments

  • [CREDENTIAL_NAME] (optional)
  • [VAULT_NAME] (optional)
    Name of the Vault that was used to issue the credential

Options

  • --issuer <HEX_ENCODED_FULL_IDENTITY>
    The full hex-encoded Identity that was used to issue the credential

  • --credential [CREDENTIAL_STRING] (optional)

  • --credential-path [CREDENTIAL_FILE] (optional)

credential verify


ockam credential verify [OPTIONS] --issuer <IDENTIFIER> [VAULT_NAME]

Arguments

  • [VAULT_NAME] (optional)
    Name of the Vault that was used to issue the credential

Options

  • --issuer <IDENTIFIER>
  • --credential [CREDENTIAL_STRING] (optional)
  • --credential-path [CREDENTIAL_FILE] (optional)

ockam authority


ockam authority <COMMAND>

An Ockam Authority node is an Ockam node running a limited set of services used by other nodes to:

  • issue credentials
  • create enrollment tokens
  • accept enrollment tokens
  • authenticate identities as project members

Those services are accessible by creating a secure channel over a TCP connection at tcp-listener-address.

Subcommands

authority create


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam authority create [OPTIONS] --project-identifier <PROJECT_IDENTIFIER> <--trusted-identities <JSON_OBJECT>|--reload-from-trusted-identities-file <PATH>> [NODE_NAME]

This command starts an authority node with the needed services to issue and verify cryptographically signed credentials.

Arguments

  • [NODE_NAME] (optional)
    Name of the node

Options

  • --project-identifier <PROJECT_IDENTIFIER>
    Identifier of the project associated to this authority node on the Orchestrator

  • -t, --tcp-listener-address [SOCKET_ADDRESS] (optional)
    TCP listener address

  • --child-process (optional)
    authority create started a child process to run this node in foreground

  • --no-direct-authentication (optional)
    Set this option if the authority node should not support the enrollment of new project members

  • --no-token-enrollment (optional)
    Set this option if the authority node should not support the issuing of enrollment tokens

  • --trusted-identities [JSON_OBJECT] (optional)
    List of the trusted identities, and corresponding attributes to be preload in the attributes storage. Format: {"identifier1": {"attribute1": "value1", "attribute2": "value12"}, ...}

  • --reload-from-trusted-identities-file [PATH] (optional)
    Path of a file containing trusted identities and their attributes encoded as a JSON object. Format: {"identifier1": {"attribute1": "value1", "attribute2": "value12"}, ...}

  • --tenant-base-url [URL] (optional)
    Okta: URL used for accessing the Okta API

  • --certificate [STRING] (optional)
    Okta: pem certificate used to access the Okta server

  • --attributes [ATTRIBUTE_NAMES] (optional)
    Okta: name of the attributes which can be retrieved from Okta

  • -f, --foreground (optional)
    Run the node in foreground

  • --vault [VAULT_NAME] (optional)
    Vault that authority will use

  • --identity [IDENTITY_NAME] (optional)
    Name of the Identity that the authority will use

Examples

# Create an authority node which can be accessed by users of project 93c6455c5f
# The default node name is 'authority'.
$ ockam authority create \
    --tcp-listener-address 127.0.0.1:4200 \
    --project-identifier 93c6455c5f \
    --trusted-identities "[{\"identifier\": \"P6c20e814b56579306f55c64e8747e6c1b4a53d9a3f4ca83c252cc2fbfc72fa94\", \"attributes\": {\"ockam-role\": \"enroller\"}}]"

# Create an authority node which can be accessed by users of project 93c6455c5f
# Trusted identities come from a file which is always reloaded where searching for an identity attribute
$ ockam authority create \
    --tcp-listener-address 127.0.0.1:4200 \
    --project-identifier 93c6455c5f \
    --reload-from-trusted-identities-file trust-anchors.json

# Delete an authority node
$ ockam node delete authority

ockam policy


ockam policy <COMMAND>

Subcommands

policy create


ockam policy create [OPTIONS] --resource <RESOURCE> --expression <EXPRESSION>

Options

  • --at [NODE_NAME] (optional)
  • -r, --resource <RESOURCE>
  • -a, --action [ACTION] (optional)
  • -e, --expression <EXPRESSION>

policy show


ockam policy show --at <NODE_NAME> --resource <RESOURCE> --action <ACTION>

Options

  • --at <NODE_NAME>
  • -r, --resource <RESOURCE>
  • -a, --action <ACTION>

policy delete


ockam policy delete [OPTIONS] --resource <RESOURCE> --action <ACTION>

Options

  • --at [NODE_NAME] (optional)
  • -r, --resource <RESOURCE>
  • -a, --action <ACTION>
  • -y, --yes (optional)
    Confirm the deletion without prompting

policy list


ockam policy list [OPTIONS] --resource <RESOURCE>

Options

  • --at [NODE_NAME] (optional)
  • -r, --resource <RESOURCE>

ockam lease


ockam lease [OPTIONS] <COMMAND>

Subcommands

lease create


ockam lease create

Create a token within the lease token manager

lease list


ockam lease list

List tokens within the lease token manager

lease show


ockam lease show --token-id <TOKEN_ID>

Show detailed token information within the lease token manager

Options

  • -t, --token-id <TOKEN_ID>
    ID of the token to retrieve

lease revoke


ockam lease revoke --token-id <TOKEN_ID>

Revoke a token within the lease token manager

Options

  • -t, --token-id <TOKEN_ID>
    ID of the token to revoke

ockam status


ockam status [OPTIONS]

Display information about the system's status

Options

  • -a, --all (optional)
    Show status for all identities; default: enrolled only

  • --timeout [TIMEOUT] (optional)
    Override default timeout (in seconds)

ockam reset


ockam reset [OPTIONS]

Removes the local Ockam configuration including all Identities and Nodes

Options

  • -y, --yes (optional)
    Confirm the reset without prompting

  • --with-orchestrator (optional)
    Remove your spaces from the Orchestrator

ockam completion


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam completion --shell <SHELL>

Generate shell completion scripts for Ockam commands.

If you’ve installed ockam command using a package manager, you likely don't need to do any additional shell configuration to gain completion support.

If you need to set up completions manually, follow the instructions below. The exact configuration file locations might vary based on your system. Remember to restart your shell before testing whether completions are working.

Options

  • -s, --shell <SHELL>
    The type of shell

Examples

The following steps outline how to build the Ockam completion file, where to store it, and what to expect from the process.

Build the Completion File

Start by ensuring you have a valid directory available to store the completion files, depending on your operating system and shell:

  • For Bash: /usr/share/bash-completion/completions
  • For Zsh: /usr/local/share/zsh/site-functions
  • For Fish: ~/.config/fish/completions

If the directory doesn't exist, create it using the following command, replacing {dir} with the appropriate path:

mkdir -p {dir}

Generate the completion file by executing the relevant command for your shell. The file name must match the specific name for each shell.

# Bash
$ ockam completion --shell bash > /usr/share/bash-completion/completions/ockam.bash

# Zsh
$ ockam completion --shell zsh > /usr/local/share/zsh/site-functions/_ockam

# Fish
$ ockam completion --shell fish > ~/.config/fish/completions/ockam.fish

Update Completion Cache

After generating the completion file, it may be necessary to update your shell's completion cache to activate the changes:

$ compinit

Expected Results

Upon successfully completing the steps outlined above:

  • The completion file will be generated according to the specified shell format.
  • The file will contain relevant completion definitions for Ockam commands and options.
  • The completion file will be saved in the designated directory for your shell.

Congratulations! You have successfully created and integrated the Ockam completion file into your shell environment. As you type Ockam commands, you'll enjoy the convenience of auto-suggestions and completion.

ockam trust-context


ockam trust-context <COMMAND>

An Ockam Trust Context defines which authorities are trusted to attest to which attributes.

Trust Contexts can be defined when creating a new node and resources, by supplying the given name or path. A default trust context can be created and will be used when an explicit trust context is not provided.

Subcommands

trust-context create


ockam trust-context create [OPTIONS] [NAME]

This command will create a new trust context. If none exists, it will be set as the default for the system.

Arguments

  • [NAME] (optional)
    The name of the trust context to create

Options

  • --credential [CREDENTIAL] (optional)
    Create a trust context from a credential

  • --project-path [PROJECT_JSON_PATH] (optional)
    Project config file

  • --trust-context [TRUST_CONTEXT_NAME | TRUST_CONTEXT_JSON_PATH] (optional)
    Trust Context config file

  • --project [PROJECT_NAME] (optional)

Examples

# To create a trust context with a random name, using the default project information
$ ockam trust-context create

# To create a trust context with a specific name, using the default project information
$ ockam trust-context create t

# To create a trust context with a specific credential
$ ockam trust-context create --credential c

trust-context show


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam trust-context show [NAME]

This command will show the details of a given trust context.

Arguments

  • [NAME] (optional)
    Name of the trust context

Examples

# To show the default trust context
$ ockam trust-context show

# To show a specific trust context
$ ockam trust-context show t1

trust-context delete


ockam trust-context delete [OPTIONS] <NAME>

This command will delete the specified trust context.

Arguments

  • <NAME>
    Name of the trust context

Options

  • -y, --yes (optional)
    Confirm the deletion without prompting

Examples

# To delete a trust context given its name
$ ockam trust-context delete t

trust-context list


Preview

Preview features are available for use, but are still under rapid development.

There may be some minor gaps in functionality or documentation.

Your feedback on the enhancements you'd like to see on this feature are especially valuable, please send them through at https://github.com/build-trust/ockam/discussions/new

ockam trust-context list

This command will show the details of all the available trust contexts.

Examples

$ ockam trust-context list

trust-context default


ockam trust-context default <NAME>

This command will change the default trust context. The default trust context is used when creating a node if not specified otherwise.

Arguments

  • <NAME>
    Name of the trust context to be set as default

Examples

# The first created trust context will be set as the default
$ ockam trust-context create t1

# Let's create a second trust context and assign it as default
$ ockam trust-context create t2
$ ockam trust-context default t2

ockam environment


ockam environment

Outputs information about environment variables used by the Ockam CLI

ockam flow-control


ockam flow-control <COMMAND>

Subcommands

flow-control add-consumer


ockam flow-control add-consumer [OPTIONS] <FLOW_CONTROL_ID> <ADDRESS>

Arguments

  • <FLOW_CONTROL_ID>
    Corresponding FlowControlId value

  • <ADDRESS>
    Address of the Consumer

Options

  • --at [NODE_NAME] (optional)
    Perform the command on the given NODE_NAME