Environment Variables Reference
This page lists the environment variables that Fuzzball sets inside your
workflow's containers, the values it substitutes into command and args before a container
starts, and the environment variables that change how the fuzzball CLI behaves.
Variables set inside workflow containers
Fuzzball sets the variables below in the containers of every
job and service, in addition to the variables defined in
the image and in the job's or service's env section. Read them from your script or program like
any other environment variable, for example $FB_WORKFLOW_ID in a shell script.
Don't define variables with these names in your own env section. Fuzzball does not overwrite
your value for most of them, so the container can end up with two definitions of the same
variable. The exceptions are noted below.
Every job and service
| Variable | Value |
|---|---|
FB_WORKFLOW_ID | ID of the running workflow |
FB_ACCOUNT_ID | ID of the group that owns the workflow |
FB_GROUP_ID | Same value as FB_ACCOUNT_ID |
FB_JOB_NAME | Name of the job or service, as written under jobs or services in the Fuzzfile |
FB_JOB_ID | ID of the job's allocation. Each replica of an autoscaled service has its own. |
FB_JOB_IMAGE | URI of the job's or service's image, for example docker://alpine:latest |
FB_JOB_KIND | single, task-array, or multinode. Services are single or multinode. |
TERM | xterm |
Task arrays
| Variable | Value |
|---|---|
FB_TASK_ID | Number of the current task, between the array's start and end |
Fuzzball also substitutes $FB_TASK_ID in a task array's command and args; see
Values substituted before a container starts.
See Parallel Jobs for examples.
API access from inside a workflow
Unless a cluster administrator has turned off workflow tokens, every job and service gets a short-lived token for the workflow owner, so it can call the Fuzzball API or run the Fuzzball CLI without logging in.
| Variable | Value |
|---|---|
FB_TOKEN | Token for the workflow owner, scoped to this workflow |
FB_API_HOST | host:port of the cluster's gRPC API, usable as a CLI context address |
FB_OPENAPI_URL | URL of the cluster's REST (OpenAPI) endpoint, usable with curl |
SSL_CERT_DIR | The system certificate directories plus the cluster trust store at /run/fuzzball-substrate/trusted-certs. Not set if the job's or service's env already sets SSL_CERT_DIR. |
These four are set together: if workflow tokens are turned off, none of them is set. See In-Workflow API Access for how to use them.
Service endpoints
When a workflow has services with endpoints, every job and service in the workflow gets the address of each endpoint, and each service also gets the address of its own endpoints.
| Variable | Value | Set in |
|---|---|---|
FB_SERVICE_<SERVICE>_ENDPOINT_ID_<ENDPOINT> | ID of the endpoint | Every job and service |
FB_SERVICE_<SERVICE>_ENDPOINT_URL_<ENDPOINT> | Public URL of the endpoint | Every job and service |
FB_SERVICE_<SERVICE>_ENDPOINT_HOST_<ENDPOINT> | Host part of the URL | Every job and service |
FB_SERVICE_<SERVICE>_ENDPOINT_PATH_<ENDPOINT> | Path part of the URL | Every job and service |
FB_ENDPOINT_ID_<ENDPOINT>, FB_ENDPOINT_URL_<ENDPOINT>, FB_ENDPOINT_HOST_<ENDPOINT>, FB_ENDPOINT_PATH_<ENDPOINT> | The same for the service's own endpoint | The service that owns the endpoint |
FB_ENDPOINT_ID, FB_ENDPOINT_URL, FB_ENDPOINT_HOST, FB_ENDPOINT_PATH | The same for the service's first endpoint | The service that owns the endpoint |
FB_ENDPOINT_REPLICA_ID_<ENDPOINT>, FB_ENDPOINT_REPLICA_ID | ID of this replica's own endpoint | Replicas of an autoscaled service, for per-replica endpoints |
<SERVICE> and <ENDPOINT> are the service and endpoint names, uppercased, with every character
that is not a letter, digit, or underscore replaced by _. If your own env sets one of the
FB_SERVICE_* variables, Fuzzball keeps your value instead. See
Environment variables for endpoints
for details.
Multinode jobs and services
| Variable | Value | Set when |
|---|---|---|
OMPI_MCA_btl_tcp_if_exclude | lo,fb0, which keeps Open MPI off the loopback and the node-local bridge | Any multinode implementation, unless your env sets OMPI_MCA_btl_tcp_if_exclude or OMPI_MCA_btl_tcp_if_include, or your command, args, or script mentions btl_tcp_if_ |
PATH | /multinode is added to the front | Any multinode implementation |
HOSTNAME | The container's hostname, for example myjob-0 | Any multinode implementation, if not already set |
RANK | The number at the end of the hostname, for example 0 | implementation: generic |
MULTINODE_HOSTLIST, MULTINODE_HOSTLIST_NOSLOTS, MULTINODE_TOTAL_SLOTS, MULTINODE_NODE_IP, MULTINODE_SSH_WRAPPER, MULTINODE_RSH_WRAPPER | Host list, slot count, and remote-execution wrapper for the job | implementation: generic, in the command that runs on the first node |
GASNET_SPAWNFN, GASNET_SSH_CMD, GASNET_SSH_SERVERS, GASNET_MASTERIP | GASNet launch settings | implementation: gasnet, on the first node |
See Generic Multinode
for the MULTINODE_* variables,
MPI for
OMPI_MCA_btl_tcp_if_exclude, and PGAS for
GASNet.
Values substituted before a container starts
Fuzzball replaces a few placeholders in a job's or service's command and args before the
container starts. These are text substitutions, not environment variables, so they work even when
no shell runs your command.
| Placeholder | Replaced with | Where |
|---|---|---|
$FB_TASK_ID, ${FB_TASK_ID} | The task number | command and args of a task array |
$FB_NODES, ${FB_NODES} | The number of nodes | command and args of a multinode job or service |
$FB_WORKFLOW_ID | The workflow ID | Volume egress destination URIs |
Any other $NAME in command or args is passed through for a shell to expand, if one runs.
Fuzzball does not substitute anything in env values or in a script. $FB_NODES is only a
placeholder: no FB_NODES environment variable is set.
Script directives
Fuzzball does not read directives from comment lines in a script, unlike #SBATCH in Slurm, #PBS
in PBS, or #BSUB in LSF. Set a job's resources, image, and other options in the Fuzzfile instead
(see the Fuzzfile Syntax Guide), or with
fuzzball run flags such as --cores, --mem, and --image.
The only line Fuzzball reads in a script is the first one: a #! line chooses the interpreter,
and a script without one runs with /bin/sh.
Variables that affect the Fuzzball CLI
Flags
Every fuzzball command-line flag can also be set with an environment variable named FUZZBALL_
followed by the flag's long name, uppercased, with - replaced by _. For example,
FUZZBALL_CA_FILE sets --ca-file and FUZZBALL_OUTPUT sets --output. A flag given on the
command line takes precedence over its environment variable.
Commonly used ones include:
| Variable | Flag | Effect |
|---|---|---|
FUZZBALL_OUTPUT | --output | Output format: json or yaml |
FUZZBALL_CA_FILE | --ca-file | CA certificate file to trust instead of the system trust store |
FUZZBALL_INSECURE | --insecure | Skip TLS certificate verification (development and testing only) |
FUZZBALL_USER | --user | Username for fuzzball context login |
FUZZBALL_PASSWORD | --password | Password for fuzzball context login |
FUZZBALL_DIRECT | --direct | Log in with a username and password instead of a browser |
FUZZBALL_GROUP | --group | Group to use, for commands that take --group |
An environment variable does not satisfy a flag that a command requires; pass required flags on
the command line. The fuzzball cluster docker-compose commands do not read FUZZBALL_* flag
variables, apart from FUZZBALL_CONTAINER_RUNTIME below.
Other variables
| Variable | Effect |
|---|---|
FB_TOKEN, FB_API_HOST | If both are set and no CLI context is active, the CLI connects to FB_API_HOST with FB_TOKEN and saves nothing. Fuzzball sets both inside workflow containers. |
XDG_CONFIG_HOME | The CLI keeps its configuration in $XDG_CONFIG_HOME/fuzzball, or ~/.config/fuzzball if unset. If /etc/fuzzball-cli/config exists, the CLI uses that configuration instead. Docker Compose deployments are always stored under $XDG_CONFIG_HOME/fuzzball (or ~/.config/fuzzball). |
VISUAL, EDITOR | Editor used by commands that open one, such as editing a secret. Defaults to vi. |
FUZZBALL_CONTAINER_RUNTIME | docker or podman for fuzzball cluster docker-compose. Same as --runtime. |
FUZZBALL_DOCS_URL | Base URL of the documentation for fuzzball mcp. Same as --docs-url. |
DEPOT_USER, DEPOT_ACCESS_TOKEN | CIQ Depot credentials for fuzzball cluster cloud deployments, used when the matching flags are not set |
SSL_CERT_FILE, SSL_CERT_DIR | Standard locations of trusted CA certificates. Ignored when --ca-file or --insecure is set. |
HTTPS_PROXY, HTTP_PROXY, NO_PROXY | Standard proxy settings for the CLI's connections |
NO_COLOR | Turns off colored output |
The fuzzball cluster commands for AWS, Azure, Google Cloud, and Oracle Cloud also read their
cloud provider's standard environment variables, such as AWS_PROFILE and AWS_REGION, through
that provider's SDK.