node create

ockam node create [OPTIONS] [NAME_OR_CONFIGURATION]

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_CONFIGURATION] (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

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

  • --started-from-configuration (optional)
    A flag used internally to indicate that the node was started from a configuration file

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

  • -u, --udp-listener-address [SOCKET_ADDRESS_UDP] (optional)
    The address to bind the UDP listener to. UDP listener is not started unless --udp is passed. 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

  • --http-server (optional)
    [DEPRECATED] Enable the HTTP server for the node that will listen to in a random free port. To specify a port, use --status-endpoint-port instead

  • --no-status-endpoint (optional)
    Disable the node's status endpoint that serves the healthcheck endpoint

  • --status-endpoint-port [PORT] (optional)
    Specify the port that the status endpoint will listen to

  • --udp (optional)
    Enable UDP transport puncture

  • --launch-configuration [LAUNCH_CONFIGURATION] (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 --configuration "{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