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]

The enroll command enrolls your Ockam Identity with Ockam Orchestrator.

It involves multiple steps. In the first step, if you specify an Identity using the --identity argument, the command uses it. If you don't specify an Identity, it checks if you have a default Identity. If you have one, the command uses this default Identity. If you do not have a default Identity, the command generates a new Identity in your default Vault. If you do not have a default Vault, the command creates a new one on your file system, makes it the default Vault, and uses it to store the private keys of your new Identity.

You will also need to use your web browser to type in a one-time code in order to activate the machine you are using to run the enroll command. You will then be required to log in to your Orchestrator account to complete activating this machine. To do so, you can choose to authenticate using GitHub or create a new email and password. If you choose the latter, then you will need to verify your email address.

Orchestrator is a SaaS product that allows remote relays, add-ons integration like Confluent, Okta, etc. If this is your first time signing in, the Orchestrator creates a new dedicated Space and Project for you. A Project offers two services: a Membership Authority and a Relay service.

The enroll command then asks this Project’s Membership Authority to sign and issue a Credential that attests that your Identifier is a member of this Project. Since your account in Orchestrator is the creator and hence first administrator on this new Project, the Membership Authority issues this Credential. The command stores the Credential for later use and exits.

Options

  • --identity [IDENTITY_NAME] (optional)
    The name of an existing Ockam Identity that you wish to enroll. You can use ockam identity list to get a list of existing Identities. To create a new Identity, use ockam identity create. If you don't specify an Identity name, and you don't have a default Identity, this command will create a default Identity for you and save it locally in the default Vault

  • --authorization-code-flow (optional)
    This option allows you to bypass pasting the one-time code and confirming device activation, and PKCE (Proof Key for Code Exchange) authorization flow. Please be careful with this option since it will open your default system browser. This option might be useful if you have already enrolled and want to re-enroll using the same account information

  • --force (optional)
    By default this command skips the enrollment process if the Identity you specified (using --identity), or the default Identity, is already enrolled, by checking its status. Use this flag to force the execution of the Identity enrollment process

  • --skip-resource-creation (optional)
    Use this flag to skip creating Orchestrator resources. When you use this flag, we only check whether the Orchestrator resources are created. And if they are not, we will continue without creating them

Examples

$ ockam enroll

To create your own identity and enroll with it, run:

ockam identity create my_id
ockam enroll --identity my_id

Troubleshoot:

If you have problems with your enrollment, please run ockam reset --yes && ockam enroll to delete your local state and start again. You can also reach out to us on Discord to ask for help https://discord.ockam.io.

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] [SPACE_NAME]

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

Arguments

  • [SPACE_NAME] (optional)
    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] (optional)
    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>

The project command allows you to manage your Ockam Projects. You can create new Projects, list existing Projects, import existing Projects, and delete them.

As an administrator, you can also create tickets to allow other Ockam Nodes to become members of your Project (using ockam project ticket). You can provide these tickets to others, and they can redeem them to enroll their Ockam Nodes into your Project (using ockam project enroll).

An Ockam Project is a collection of Nodes and Workers that work together to achieve a common goal. You can create Nodes and Workers within a Project using various commands, like ockam node create.

Upon enrolling in Ockam, using ockam enroll, the Orchestrator creates a new dedicated Project for you. It offers two services: a Membership Authority and a Relay Service. You can use the Relay Service to create end-to-end secure channels. You can use the Membership Authority to manage which Identities are members of your Project.

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 import


ockam project import --project-file <PATH>

This command will import a project in the local database from a json file produce with ockam project show --output json. If the project already exists, an error is returned

Options

  • --project-file <PATH>
    Project file

Examples

# To import a project
$ ockam project import --project-file project.json

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] (optional)
    Name of the project

Options

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

  • --retry-count [RETRY_COUNT] (optional)
    Number of times to retry the command

  • --retry-delay [RETRY_DELAY] (optional)
    Delay between retries

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 Orchestrator Controller and 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 ticket


ockam project ticket [OPTIONS]

The project ticket command allows you to create a one-time enrollment ticket, and provide custom attributes, after you have run ockam enroll. This is typically only done by Project administrators. How long the ticket is valid, and how many times it can be redeemed is also configurable via this command. Once redeemed, the attributes in this ticket are assigned to its redeemer. You can also use the --relay argument to allow the other Identity to create a Relay at the given address. The --enroller argument allows the Identity using the ticket to enroll other Identities into the Project, typically something that only administrators can do.

Once you create a ticket, with attributes, for a Project, another Ockam node can use it later to enroll into this Project (using ockam project enroll).

When another Ockam node runs ockam project enroll with this ticket (the Identity of that node is enrolled), they become a member of the Project, and they get a credential at the end of this process. The Project's Membership Authority will cryptographically attest to the specific attributes that the ticket was created with. As a member, they can request a credential whenever they need one. Credentials do not live forever, and expire.

The ticket is plain text representing a one-time use token and the non-sensitive data about the Project, like the route to reach it, and some other information, which will be used to validate the Project Identity. The ticket itself can be stored in an environment variable, or a file.

Options

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

  • --project [PROJECT_NAME] (optional)
    Project name to use for the command

  • --authority-identity [IDENTITY] (optional)
    Hex encoded Identity

  • --authority-route [AUTHORITY_ROUTE] (optional)
    Address to the Authority node

  • --credential-scope [CREDENTIAL_SCOPE] (optional)
    Expect credential manually saved to the storage

  • -t, --to [ROUTE_TO_PROJECT] (optional)
    The Project name from this option is used to create the enrollment ticket. This takes precedence over --project

  • -a, --attribute [ATTRIBUTE] (optional)
    Attributes in key=value format to be attached to the member. You can specify this option multiple times for multiple attributes

  • --expires-in [DURATION] (optional)
    Duration for which the enrollment ticket is valid, if you don't specify this, the default is 10 minutes. Examples: 10000ms, 600s, 600, 10m, 1h, 1d. If you don't specify a length sigil, it is assumed to be seconds

  • --usage-count [USAGE_COUNT] (optional)
    Number of times the ticket can be used to enroll, the default is 1

  • --relay [ENROLLEE_ALLOWED_RELAY_NAME] (optional)
    Name of the relay that the identity using the ticket will be allowed to create. This name is transformed into attributes to prevent collisions when creating relay names. For example: --relay foo is shorthand for --attribute ockam-relay=foo

  • --enroller (optional)
    Add the enroller role to your ticket. If you specify it, this flag is transformed into the attributes --attribute ockam-role=enroller. This role allows the Identity using the ticket to enroll other Identities into the Project, typically something that only admins can do

  • --retry-count [RETRY_COUNT] (optional)
    Number of times to retry the command

  • --retry-delay [RETRY_DELAY] (optional)
    Delay between retries

Examples

# To generate an enrollment ticket that can be used to enroll a machine
$ ockam project ticket --attribute component=db --attribute location=sf

# To generate an enrollment ticket that can be used to enroll a machine and save it to a file
$ ockam project ticket --attribute component=db --attribute location=sf > ticket.txt

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>

Configure an addon for a project

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>
    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 addon configure instaclustr-kafka


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

Instaclustr (Kafka) 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>
    Bootstrap server address

Examples

Examples of how to configure and use the Instaclustr (Kafka) addon can be found within the example documentation:

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

project addon configure aiven-kafka


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

Aiven (Kafka) 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>
    Bootstrap server address

Examples

Examples of how to configure and use the Aiven (Kafka) addon can be found within the example documentation:

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

project addon configure redpanda


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

Redpanda 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>
    Bootstrap server address

Examples

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

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

project addon configure warpstream


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

WarpSteam 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>
    Bootstrap server address

Examples

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

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

project addon configure kafka


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

Apache Kafka 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>
    Bootstrap server address

Examples

Examples of how to configure and use the Apache Kafka 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]

The project enroll command allows you to use an enrollment ticket generated by ockam project ticket (for a Project) to enroll an Identity, on an Ockam Node, typically running on another machine, to that Project. This is a great choice for enrolling large fleets of applications, services, or machines. It is also friendly to automated provisioning scripts and tools.

When you or someone else uses a machine to run this command with a ticket, the following steps take place for it to get a credential. The Identity of the Ockam Node running on this machine is enrolled with the ticket's Project. This Identity gets a Project membership credential that attests to the attributes that the ticket was created with. Then, for example, this Node can create a Relay in the Project, at an address specified in the attributes of the ticket. The attributes are also used in conjunction with access control policies on other Ockam Nodes to ensure that Project members that possess a certain credential with a certain attribute can communicate with them.

The ticket is plain text representing a one-time use token and the non-sensitive data about the Project, like the route to reach it and the Project Identity Identifier, which will be used to validate the Project Identity. The ticket itself can be stored in an environment variable, or a file.

Ockam offers several pluggable enrollment protocols. Another options for you is to use Okta as an enrollment provider using --okta. This is a great choice for enrolling users without manual intervention (no need to manually provision tickets for each user). Workforce identities in Okta can be combined with application identities in Ockam for attribute-based access control of distributed applications.

Arguments

  • [ENROLLMENT TICKET] (optional)
    Path, URL or inlined hex-encoded enrollment ticket

Options

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

  • --project [PROJECT_NAME] (optional)
    Project name to use for the command

  • --authority-identity [IDENTITY] (optional)
    Hex encoded Identity

  • --authority-route [AUTHORITY_ROUTE] (optional)
    Address to the Authority node

  • --credential-scope [CREDENTIAL_SCOPE] (optional)
    Expect credential manually saved to the storage

  • --okta (optional)
    Use Okta instead of an enrollment ticket

  • --retry-count [RETRY_COUNT] (optional)
    Number of times to retry the command

  • --retry-delay [RETRY_DELAY] (optional)
    Delay between retries

Examples

# 1) Use hex encoded string enrollment ticket:

# 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 ticket
$ ockam project enroll $TICKET --identity control_identity

# 2) Use file enrollment ticket:

# From the admin machine, generate an enrollment ticket, save to a file
$ ockam project ticket --attribute component=user > $NAME.ticket

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

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] [NAME_OR_CONFIG]

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

  • [NAME_OR_CONFIG] (optional)
    Name of the node or a configuration to set up the node. The configuration can be either a path to a local file or a URL

Options

  • --node-config [YAML] (optional)
    Inline node configuration

  • --enrollment-ticket [ENROLLMENT TICKET] (optional)
    A path, URL or inlined hex-encoded enrollment ticket to use for the Ockam Identity associated to this node. When passed, the identity will be given a project membership credential. Check the project ticket command for more information about enrollment tickets

  • --variable [VARIABLE] (optional)
    Key-value pairs defining environment variables used in the Node configuration. The variables passed here will have precedence over global environment variables. This argument can be used multiple times, each time adding a new key-value pair. Example: --variable KEY1=VALUE1 --variable KEY2=VALUE2

  • -f, --foreground (optional)
    Run the node in foreground mode. This will block the current process until the node receives an exit signal (e.g., SIGINT, SIGTERM, CTRL+C, EOF)

  • -e, --exit-on-eof (optional)
    When running a node in foreground mode, exit the process when receiving EOF on stdin

  • --child-process (optional)
    A flag to determine whether the current foreground node was started as a child process. This flag is only used internally and should not be set by the user

  • -s, --skip-is-running-check (optional)
    Use this flag to not raise an error if the node is already running. This can be useful in environments where the PID is constant (e.g., kubernetes)

  • -t, --tcp-listener-address [SOCKET_ADDRESS] (optional)
    The address to bind the TCP listener to. Once the node is created, its services can be accessed via this address. By default, it binds to 127.0.0.1:0 to assign a random free port

  • --launch-config [LAUNCH_CONFIG] (optional)
    A configuration in JSON format to set up the node services. Node configuration is run asynchronously and may take several seconds to complete

  • --identity [IDENTITY_NAME] (optional)
    The name of an existing Ockam Identity that this node will use. You can use ockam identity list to get a list of existing Identities. To create a new Identity, use ockam identity create. If you don't specify an Identity name, and you don't have a default Identity, this command will create a default Identity for you and save it locally in the default Vault

  • --project [PROJECT_NAME] (optional)
    Project name to use for the command

  • --authority-identity [IDENTITY] (optional)
    Hex encoded Identity

  • --authority-route [AUTHORITY_ROUTE] (optional)
    Address to the Authority node

  • --credential-scope [CREDENTIAL_SCOPE] (optional)
    Expect credential manually saved to the storage

  • --opentelemetry-context [OPENTELEMETRY_CONTEXT] (optional)
    Serialized opentelemetry context

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

# To create a new node with a configuration file
$ ockam node create config.yaml

# To create a new node with an inline configuration
$ ockam node create --node-config "{name: n1, tcp-outlet: {db-outlet: {to: '127.0.0.1:5432'}}}"

An example of a configuration file is:

# variables can be used and overridden with environment variables
variables:
  NODE_PORT: 3333
  SERVICE_PORT: 5000
  CLIENT_PORT: 15000

# name of the node
name: n1

# TCP listener address for the node
tcp-listener-address: 127.0.0.1:$NODE_PORT

# This creates a relay named default
# by running the ockam relay create command
relay: default

# List of outlets
tcp-outlet:
  # Name of the outlet
  db-outlet:
    # Arguments to the ockam tcp-outlet create command
    to: $SERVICE_PORT

# List of outlets
tcp-inlet:
  # Name of the inlet
  web-inlet:
    # Arguments to the ockam tcp-outlet create command
    from: $CLIENT_PORT

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

# 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 [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

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_NAME] (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 [PROJECT_NAME] (optional)
    Project name to use for the command

  • --authority-identity [IDENTITY] (optional)
    Hex encoded Identity

  • --authority-route [AUTHORITY_ROUTE] (optional)
    Address to the Authority node

  • --credential-scope [CREDENTIAL_SCOPE] (optional)
    Expect credential manually saved to the storage

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. If not provided, 'default' will be used

Options

  • --to [NODE_NAME] (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

  • --relay-address [RELAY_ADDRESS] (optional)
    Relay address to use. By default, inherits the relay name

  • --project-relay (optional)
    Whether the relay will be used to relay messages at a project. By default, this information will be inferred from the --at argument

  • --retry-count [RETRY_COUNT] (optional)
    Number of times to retry the command

  • --retry-delay [RETRY_DELAY] (optional)
    Delay between retries

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] [RELAY_NAME]

Show a Relay given its name

Arguments

  • [RELAY_NAME] (optional)
    Name assigned to the Relay

Options

  • --at [NODE] (optional)
    Node which the 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] (optional)
    Name assigned to the Relay

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 internal address

Options

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

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

Examples

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

# To delete a TCP listener given its socket address on the default node
$ ockam tcp-listener delete 127.0.0.1:5000

# To delete a TCP listener given its internal address 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

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 internal address or socket address

Options

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

Examples

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

# To show a TCP listener given its socket address
$ ockam tcp-listener show 127.0.0.1:5000

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 internal address or socket address

Options

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

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

Examples

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

# To delete a TCP connection given its socket address on the default node
$ ockam tcp-connection delete 127.0.0.1:5000

# To delete a TCP connection given its internal address 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

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 internal address or socket address

Options

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

Examples

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

# To show a TCP connection given its socket address
$ ockam tcp-connection show 127.0.0.1:5000

ockam tcp-outlet


ockam tcp-outlet <COMMAND>

A TCP Inlet and TCP Outlet together form a portal, working hand in hand with Relays. A TCP Inlet defines where a node, running on another machine, listens for connections. The Inlet's route provides information on how to forward traffic to the Outlet (its address). Relays allow you to establish end-to-end protocols with services that operate in remote private networks.

When you create a TCP Outlet, on an Ockam node, running on your local machine, it makes the TCP service available to the Inlet, from a worker address. You must specify the TCP address of the server, to which your Outlet should send raw TCP traffic. You can also name your Outlet by giving it an alias.

A TCP Outlet runs adjacent to a TCP server. The Outlet unwraps Ockam messages and delivers the raw TCP messages to the TCP server. Conversely, it sends messages from the TCP server to the Inlet (refer to ockam tcp-inlet and ockam relay).

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 <HOSTNAME_PORT>

Create a TCP Outlet that runs adjacent to a TCP server. The Outlet unwraps Ockam messages and delivers the raw TCP messages to the TCP server.

You must specify the TCP address of the server, that your Outlet should send raw TCP traffic to. You can also name your Outlet by giving it an alias.

When you create a TCP Outlet, on an Ockam node, running on your local machine, it makes the TCP server available from a worker address, to the corresponding TCP Inlet (see ockam tcp-inlet).

Options

  • --to <HOSTNAME_PORT>
    TCP address where your TCP server is running: domain:port. Your Outlet will send raw TCP traffic to it

  • --tls (optional)
    If tls is set then the outlet will establish a TLS connection over TCP

  • --from [OUTLET_ADDRESS] (optional)
    Address of your TCP Outlet, which is part of a route that is used in other commands. This address must be unique. This address identifies the TCP Outlet worker, on the node, on your local machine. Examples are /service/my-outlet or my-outlet. If you don't provide it, /service/outlet will be used. You will need this address when you create a TCP Inlet (using ockam tcp-inlet create --to <OUTLET_ADDRESS>)

  • --at [NODE_NAME] (optional)
    Your TCP Outlet will be created on this node. If you don't provide it, the default node will be used

  • --allow [EXPRESSION] (optional)
    Policy expression that will be used for access control to the TCP Outlet. If you don't provide it, the policy set for the "tcp-outlet" resource type will be used

Examples

# To create a new TCP Outlet to the TCP server, using the default node
$ ockam tcp-outlet create --to 127.0.0.1:5000

# To create a new TCP Outlet at the given address, to the TCP server
$ ockam tcp-outlet create --to 127.0.0.1:5000 --from payroll-db-outlet

# To create a new TCP Outlet to the TCP server, 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. This does not delete any TCP Inlets or Relays that you may have created, you can use ockam tcp-inlet delete and ockam relay delete to delete them.

Arguments

  • [ALIAS] (optional)
    Delete the Outlet with this alias name. If you don't provide an alias, you will be prompted to select from a list of available Outlets to delete

Options

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

  • -y, --yes (optional)
    Run the delete command, without prompting for confirmation. This is useful for scripts

  • -a, --all (optional)
    Delete all the TCP Outlets

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 all the TCP Outlets at a given node, and provide limited information about each Outlet. For detailed information about each Outlet, use ockam tcp-outlet show. If you don't specify a node using the --at option, the TCP Outlets on the default node will be listed.

Options

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

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 detailed information on TCP Outlets

Arguments

  • [ALIAS] (optional)
    Show detailed information about the Outlet that has this alias. If you don't provide an alias, you will be prompted to select from a list of available Outlets to show

Options

  • --at [NODE_NAME] (optional)
    Show Outlet at the specified node. If you don't provide it, the default node will be used

Examples

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

# To display a list of available TCP Outlets to show
$ ockam tcp-outlet show

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_NAME] (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 or the name of the TCP Outlet service you want to connect to

  • --via [RELAY_NAME] (optional)
    Name of the relay that this TCP Inlet will use to connect to the TCP Outlet

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

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

  • --allow [EXPRESSION] (optional)
    Policy expression that will be used for access control to the TCP Inlet. If you don't provide it, the policy set for the "tcp-inlet" resource type will be used

  • --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 the TCP Outlet

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

  • --no-connection-wait (optional)
    Create the TCP Inlet without waiting for the TCP Outlet to connect

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] (optional)
    Delete the inlet with this alias

Options

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

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

  • -a, --all (optional)
    Delete all the TCP Inlet

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 alias 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

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

Examples

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

ockam kafka-inlet


ockam kafka-inlet <COMMAND>

Manage Kafka Inlets

Subcommands

kafka-inlet create


ockam kafka-inlet create [OPTIONS]

Create a new Kafka Inlet. Kafka clients v3.7.0 and earlier are supported. You can find the version you have with 'kafka-topics.sh --version'

Options

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

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

  • --from [FROM] (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:4000) will be used

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

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

  • --to [TO] (optional)
    The route to the Kafka outlet node, either the project in ockam orchestrator or a rust node, expected something like /project/. Conflicts with --bootstrap-server

  • --consumer [CONSUMER] (optional)
    The route to the Kafka consumer node, valid only when --bootstrap-server is specified

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

  • --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. Kafka clients v3.7.0 and earlier are supported. You can find the version you have with 'kafka-console-consumer.sh --version'

Options

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

  • --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

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

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

  • --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 broker

  • --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

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

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. Kafka clients v3.7.0 and earlier are supported. You can find the version you have with 'kafka-console-producer.sh --version'

Options

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

  • --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

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

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

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

  • --identity [IDENTITY_NAME] (optional)
    Name of the Identity that the secure-channel listener will use If it is different from the default node identity

Examples

$ ockam node create n1
$ ockam node create n2

# Create a secure channel listener with a custom name on the default node
$ ockam secure-channel-listener create test --at n2
  ✔ Secure Channel Listener at /service/test created successfully
  At node /node/n2

# 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/api
  ✔ Secure Channel at /service/5c2a940cf008783cfd8d7012e772d674 created successfully
  From /node/n1 to /node/n2/service/api

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

Examples

$ ockam secure-channel-listener delete 8eb3bfc8a6419f24c05ddd627d144bec --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

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

Examples

$ ockam secure-channel-listener show 8eb3bfc8a6419f24c05ddd627d144bec --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

  • -c, --credential [CREDENTIAL] (optional)

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

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
  ✔ Secure Channel at /service/a2b1a2275d02308a7920499b5f49e4ee created successfully
  From /node/n1 to /node/n2/service/api

$ 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 8eb3bfc8a6419f24c05ddd627d144bec --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 8eb3bfc8a6419f24c05ddd627d144bec --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

  • --path [PATH] (optional)
  • --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 move


ockam vault move --path <PATH> <NAME>

This command will move an existing vault file to a new path:

  • the vault needs to exist
  • the vault data should not be stored in the main database
  • the vault path should exist
  • the new vault path should not exist

Arguments

  • <NAME>

Options

  • --path <PATH>

Examples

# To move a vault to a new path
$ ockam vault move my_vault --path new/path

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] (optional)
    Name of the vault

Options

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

  • -a, --all (optional)

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

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

  • --identity [IDENTITY] (optional)
    Identity to import in hex format

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] (optional)
    Name of the identity to be deleted

Options

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

  • -a, --all (optional)

Examples

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

ockam credential


ockam credential <COMMAND>

Manage Credentials

Subcommands

credential list


ockam credential list [OPTIONS]

Options

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

  • --subject [SUBJECT] (optional)
    Subject Identifier

  • --issuer [ISSUER] (optional)
    Issuer Identifier

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

  • --ttl [TTL] (optional)

credential store


ockam credential store [OPTIONS] --issuer <IDENTIFIER> --scope <CREDENTIAL_SCOPE>

Options

  • --issuer <IDENTIFIER>

  • --scope <CREDENTIAL_SCOPE>
    Scope is used to separate credentials given they have the same Issuer&Subject Identifiers Scope can be an arbitrary value, however project admin, project member, and account admin credentials have scope of a specific format. See [CredentialScope]

  • --credential [CREDENTIAL_STRING] (optional)

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

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

credential verify


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

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.

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> [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

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

  • -s, --skip-is-running-check (optional)
    Skip the check if such node is already running. Useful for kubernetes when the pid is the same on each run

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

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

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

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

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

  • --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

  • --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

  • --account-authority [ACCOUNT_AUTHORITY_CHANGE_HISTORY] (optional)
    Full, hex-encoded Identity (change history) of the account authority to trust for account and project administrator credentials

  • --enforce-admin-checks (optional)
    Enforce distinction between admins and enrollers

  • --disable-trust-context-id (optional)
    Not include trust context id and project id into the credential TODO: Set to true after old clients are updated

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\": \"I6c20e814b56579306f55c64e8747e6c1b4a53d9a3f4ca83c252cc2fbfc72fa94\", \"attributes\": {\"ockam-role\": \"enroller\"}}]"

# Delete an authority node
$ ockam node delete authority

ockam policy


ockam policy <COMMAND>

Subcommands

policy create


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

Options

  • --at [NODE_NAME] (optional)
  • --resource-type [RESOURCE_TYPE] (optional)
  • --resource [RESOURCE] (optional)
  • --expression <EXPRESSION>

policy show


ockam policy show [OPTIONS] [RESOURCE]

Arguments

  • [RESOURCE] (optional)

Options

  • --at [NODE_NAME] (optional)

policy delete


ockam policy delete [OPTIONS] [RESOURCE]

Arguments

  • [RESOURCE] (optional)

Options

  • --at [NODE_NAME] (optional)
  • -y, --yes (optional)
    Confirm the deletion without prompting

policy list


ockam policy list [OPTIONS] [RESOURCE]

Arguments

  • [RESOURCE] (optional)

Options

  • --at [NODE_NAME] (optional)

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 the default timeout

ockam reset


ockam reset [OPTIONS]

Removes the local Ockam configuration including all Identities and Nodes

Options

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

  • --all (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 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