Skip to content

Configuration Files

phenix currently supports six (6) different configuration file types:

  1. Topology
  2. Scenario
  3. Experiment
  4. Image
  5. User
  6. Role

Typically, users will create Topology and Scenario configuration files by hand, while the rest will be generated by phenix using available commands. However, it is possible to create all configuration file types by hand if necessary.

Tip

Configuration files can also be created, viewed, and deleted via the Web-UI (see Web-UI section below).

Configuration files are versioned using a header section based heavily on what Kubernetes does. Each configuration file will have a header section that looks like the following:

apiVersion: phenix.sandia.gov/v1
kind: Topology
metadata:
  name: foobar
spec:
  ...

In the example above, the kind field represents the type of configuration file (e.g., Topology, Scenario, Image). The apiVersion field represents the version the spec section conforms to (currently there is only v1 for all configuration types except Scenario, which is v2), and the spec section will contain the actual details for the configuration type based on the configuration schema. Note that, at least in the header section, keys are camel-case and begin with a lowercase letter, while values are camel-cased but begin with a capital letter.

Info

Throughout the documentation, we mention creating configurations manually. When we say this, we mean passing a YAML or JSON configuration file of any type to the phenix config create command.

phenix config create, phenix config apply and phenix config diff take files only: each argument is a .json, .yaml or .yml file, and a directory is an error. To read every file of a directory, give dir/* in a shell, such as phenix config create configs/*. The shell replaces dir/* with the files of the directory before phēnix starts. A subdirectory in the match is an error, so use dir/*.yml when the directory has one. Use dir/*.yml when the directory also holds files that are not configurations. The commands refuse a Builder document (see Builder documents and phenix config create).

The metadata section can also hold annotations: text values by key, such as the topology and scenario annotations of an Experiment. The exception is builder-doc, a map of digest, id and path that names the Builder diagram of a Topology (see The builder-doc annotation).

Topology

The Topology configuration is one of the core configuration types for phenix, as it describes a network topology to be deployed in minimega that can be used by one or more experiments to be executed.

A topology is comprised of one or more nodes, which can either be a VM (external: false - the default) or an external node (external: true), each including system descriptions and configurations, as well as any networking settings required to connect all of the nodes in a topology together. This configuration becomes the basis for most of the minimega commands later created in the relevant minimega startup script (at least for internal VMs).

Topologies can also include other topologies, using the includeTopologies key. This feature allows users to include common components from an existing topology. These includes can come from either the phēnix store (by name) or from a file path to a topology on disk. Included topologies are merged into the including topology.

...
includeTopologies:
- /phenix/topologies/foo.yml
- bar-from-store
nodes:
...

Default Settings

If left unmodified or unset, the following are the default settings for each node:

  • external will be set to false
  • memory will be set to 512MB
  • vcpus will be set to 1
  • snapshot will be set to true
  • no network settings will be included

Required Values

Each topology must have a unique name, which should be lowercase and not include spaces. In addition, each node in the topology must:

  • have a specified type — the available types are defined in the schema
  • have a unique hostname
  • have an OS type of linux or windows
  • have a disk image assigned

Warning

Hostnames must be between 2 and 63 characters long, can only contain alphanumeric characters and hyphens, and cannot begin or end with a hyphen. Hostnames should not be used as a FQDN. The 2-character minimum comes from guest operating systems: VyOS and Windows both reject 1-character hostnames.

Optional Values

Optional values for a node in the topology configuration can include:

  • static network configurations
  • specific memory values (e.g., 1-16GB)
  • specific VCPUs values (e.g., 1-4)
  • additional disk storage
  • file injections (and main disk inject partition)
  • labels, which are typically used by phēnix apps
  • routing ruleset(s)
  • delay triggered by user, timer, or c2 (command and control)

Warning

If not specified, the default disk partition to inject files into is 1. This will fail for a disk that is using LVM. In order to use a disk image that's using LVM, set inject_partition: 0 on the first drive to force phēnix to skip disk injections but still snapshot the base image. The startup app will automatically deliver its generated scripts through C2; other files configured for injection are still skipped. See C2 Startup Script Delivery for the requirements and configuration options.

Note

On Windows nodes, injection and deletion paths match existing files regardless of case. The inject partition must be NTFS, and the minimega host needs lowntfs-3g; without it, minimega silently falls back to a case-sensitive mount.

Delay Start

It is possible to delay the start of a VM with the delay value. There are three options available to set, but on only one option can be set:

  1. user is a boolean value and when set to true the VM will require a manual start either through the phēnix UI or command line (the latter can be by phēnix or minimega commands).

  2. timer is a Golang duration string such as 30s, 5m, or 1h30m. A timer that is not a duration is rejected.

  3. c2 requires minimega command and control. Note in the example below that the hostname AD1 will be delayed starting until the VM host-00 has started and checked in with minimega command and control. It is possible to have multiple hostnames included. useUUID is an additional boolean value setting, per hostname, that will watch for the UUID instead of the hostname to register with minimega command and control.

Note

If one or more VMs are set with a delayed start, the UI will display a blue tag in the Delay column next to the Screenshot column. The tag will indicate what type of delay was set. Once all the delayed VMs have started, the Delay column will no longer be visible. For a timer delay, the tag and the VM details card show the time until the VM starts, for example starts in 4m 12s.

While VMs wait for a delayed start, the summary at the top of the running experiment page shows a blue tag, for example 2 delayed VMs waiting, next to the Running status. When a VM waits for a timer, the tag also shows the time until the next VM starts, for example 2 delayed VMs waiting, next starts in 4m 12s. The VMs tile of the summary also shows the number of delayed VMs. To see the tiles, click Details in the summary.

Network Address Translation (NAT)

For nodes of type Router, basic source NAT can be configured to masquerade packets from one or more networks out a specific interface. For example, assume a router has three interfaces — eth0, eth1, eth2. eth0 is connected to the Internet, while eth1, eth2 are connected to networks that use private IP space. To masquerade packets from eth1, eth2 out eth0 the following configuration could be used.

network:
  nat:
    - out: eth0
      in:
        - eth1
        - eth2

External Nodes

There may be cases where an experiment includes external devices (hardware in the loop) that should still be included in the topology for the purposes of the State of Health network diagram, state of health reachability checks, or for use by custom user apps. External nodes can be included in the topology by marking them as external: true. Among other things, this will prevent them from being deployed as a VM in minimega. The configuration schema for an external node in the topology is defined in the external node schema.

Danger

Do not use external: false for internal nodes that should be deployed in minimega. Instead, don't include the external configuration key at all. This is a quirk of how we internally decide which node schema should be used (via oneOf).

An external node still requires a type, general.hostname, and (if you want it to show up connected to anything in the topology graph) a network section, just like a regular node. However, the external_node schema is intentionally simpler than the schema used for minimega-deployed nodes:

  • there is no drives key (external nodes have no disk image to snapshot or inject files into)
  • there is no injections, delay, routes, ospf, rulesets, advanced, or commands support, since none of those apply to a device that phenix doesn't deploy or control
  • network interfaces only support the flat set of fields shown in the external_node schema (name, proto, address, mask, gateway, vlan). There's no oneOf between static/dhcp/serial interface types like there is for minimega nodes
- type: HIL
  external: true
  general:
    hostname: plc-01
    description: Physical PLC on the test bench
  hardware:
    os_type: linux
  network:
    interfaces:
    - name: eth0
      vlan: EXP-1
      address: 192.168.10.50
      mask: 24
      proto: static

Special and Edge Cases

  • Not deployed, not monitored by C2. External nodes are never started in minimega and never run miniccc, so they're excluded from the automated State of Health checks (network config, listening ports, processes, CPU load, etc.) that rely on C2. Their IP address(es) are still gathered from the topology, though, so they can be used as the src or dst of a testCustomReachability entry to ping-test connectivity to/from the external device.
  • skipHosts doesn't apply. Since external nodes are already skipped from C2-based monitoring, the SoH skipHosts setting has no effect on them.
  • Interfaces on the MGMT or MIRROR VLANs are ignored in the graph. The SoH topology graph builder skips any interface whose VLAN is MGMT or MIRROR (case-insensitive) when drawing connections, regardless of whether the node is external or a regular VM.
  • vlan can be omitted, but then the node won't be connected to anything. If an external node's interface doesn't specify a vlan, or the interface is left off entirely, the node will still appear in the SoH topology graph as an isolated node with no lines connecting it to anything else.
  • Getting a line drawn in the graph. To have phenix draw a line between an external node and other nodes in the SoH topology graph, give the external node a network.interfaces[].vlan value that exactly matches the vlan value used on the interface(s) of the node(s) you want it connected to (the VLAN name acts as the shared switch/interface node in the graph). It doesn't matter whether the matching nodes are VMs or other external nodes — any two nodes sharing a VLAN name will be connected in the graph.

Example

A contrived, four node example — three VMs and a router — is given below, and is driven by the topology schema described here.

apiVersion: phenix.sandia.gov/v1
kind: Topology
metadata:
  name: foobar
spec:
  nodes:
  - type: VirtualMachine
    general:
      hostname: host-00
      snapshot: true
    delay:
      user: true
    hardware:
      os_type: linux
      drives:
      - image: ubuntu.qc2
    injections:
      - src: foo/bar/sucka.fish
        dst: /data/sucka.fish
      - src: /foo/bar/sucka/fish.sh
        dst: /data/fish.sh
    network:
      interfaces:
      - name: IF0
        vlan: EXP-1
        address: 192.168.10.1
        mask: 24
        gateway: 192.168.10.254
        proto: static
        type: ethernet
      - name: IF1
        vlan: MGMT
        address: 172.16.10.1
        mask: 16
        proto: static
        type: ethernet
  - type: VirtualMachine
    general:
      hostname: host-01
      snapshot: true
      do_not_boot: false
    delay:
      timer: 5m
    hardware:
      os_type: linux
      drives:
      - image: ubuntu.qc2
    network:
      interfaces:
      - name: IF0
        vlan: EXP-1
        address: 192.168.10.2
        mask: 24
        gateway: 192.168.10.254
        proto: static
        type: ethernet
      - name: IF1
        vlan: MGMT
        address: 172.16.10.2
        mask: 16
        proto: static
        type: ethernet
      - name: S0
        vlan: EXT
        address: 10.0.0.1
        mask: 24
        proto: static
        type: serial
        udp_port: 8989
        baud_rate: 9600
        device: /dev/ttyS0
  - type: VirtualMachine
    general:
      hostname: AD1
      snapshot: true
    delay:
      c2:
      - hostname: host-00
        useUUID: false
    hardware:
      os_type: windows
      drives:
      - image: win-svr-2k8.qc2
    network:
      interfaces:
      - name: IF0
        vlan: EXP-1
        address: 192.168.10.250
        mask: 24
        gateway: 192.168.10.254
        proto: static
        type: ethernet
      - name: IF1
        vlan: MGMT
        address: 172.16.10.3
        mask: 16
        proto: static
        type: ethernet
  - type: Router
    labels:
      ntp-server: "true"
    general:
      hostname: router-00
      snapshot: true
    hardware:
      os_type: linux
      drives:
      - image: vyatta.qc2
    network:
      interfaces:
      - name: IF0
        vlan: EXP-1
        address: 192.168.10.254
        mask: 24
        proto: static
        type: ethernet
        ruleset_in: test
      - name: IF1
        vlan: MGMT
        address: 172.16.10.254
        mask: 16
        proto: static
        type: ethernet
      rulesets:
      - name: test
        default: drop
        rules:
        - id: 10
          action: accept
          protocol: all
          source:
            address: 1.1.1.1
            port: 53

Scenario

The Scenario configuration is used to define and configure one or more phenix apps (default or user) for use with a topology. In this sense, a topology can have one or more scenarios associated with it, but a scenario can only be associated with a single topology.

Apps

A phenix app can be applied to an experiment topology using a single configuration, a per-host configuration, or both. Examples could include:

  • a phenix app that adds a minimega tap to all hosts in the cluster,
  • one that injects the same file into every node in the experiment topology, or
  • one that configures a VPN between two nodes in an experiment using WireGuard.

The first two examples would involve a single configuration, while the last example would use a per-host configuration because (1) only two nodes will be modified, and (2) each of the two nodes will require different configurations (e.g., one will be a WireGuard client and the other a WireGuard server). Each configured app can contain a list of topology nodes to apply the app to, along with custom metadata for the app specific to the topology node.

App Configuration Options

  • assetDir: used by apps to generate absolute path to asset files when relative paths are provided in app metadata. The default is an empty string.

  • fromScenario: name of another scenario config to pull this app config from. This allows for defining complex app configurations in a single base scenario and referencing it from scenarios included in experiments. The default is an empty string.

  • hosts: a list of per-host configurations to apply to the experiment topology. The default is nil.

    • hostname: the name of the experiment VM to apply this per-host metadata to.

    • metadata: app metadata to apply to this experiment VM. The default is nil.

  • metadata: app metadata to apply to this experiment. The default is nil.

  • name: the name of the app being configured. There is no default value; one must be provided.

  • runPeriodically: a Golang duration string) specifying how often to trigger the app's running stage. The default value is an empty string, which means the app's running stage will not be triggered periodically.

Example

The following is an example of a configuration for a scenario named foobar, which can only be applied to an accompanying topology named foobar (while these names are the same in this example, the topology and scenario names do not have to match). Included in this scenario are apps named miniccc-injector, startup, protonuke, and wireguard. Each entry in the list of app hosts includes custom app metadata and the hostname of the topology node to apply the metadata.

apiVersion: phenix.sandia.gov/v2
kind: Scenario
metadata:
  name: foobar
  annotations:
    topology: foobar
spec:
  apps:
  - name: miniccc-injector
    metadata:
      # files to inject into each node in experiment, based on OS type
      linux:
        src: /phenix/injects/miniccc
        dst: /usr/local/bin/miniccc
      windows:
        src: /phenix/injects/miniccc.exe
        dst: phenix/miniccc.exe
  - name: startup
    hosts:
    - hostname: host-00 # hostname of topology node to apply it to
      metadata:
        domain_controller:
          domain: example.com
          ip: 10.0.0.1
          username: admin
          password: SuperSecretPassword
  - name: protonuke
    hosts:
    - hostname: host-01 # hostname of topology node to apply it to
      metadata:
        # protonuke app metadata for this topology node
        args: -logfile /var/log/protonuke.log -level debug -http -https -smtp -ssh 192.168.100.100
  - name: wireguard
    hosts:
    - hostname: AD1 # hostname of topology node to apply it to
      metadata:
        # wireguard app metadata for this topology node
        infrastructure:
          private_key: GLlxWJom8cQViGHojqOUShWIZG7IsSX8
          address: 10.255.255.1/24
          listen_port: 51820
        peers:
          public_key: +joyya2F9g72qbKBtPDn00mIevG1j1OqeN76ylFLsiE=
          allowed_ips: 10.255.255.10/32

Note

The above example includes an app named startup, which is a phēnix default app. Meaning, it is possible to configure default phēnix apps in a scenario configuration, not just user apps.

Info

See Scorch for additional information on Scenario Orchestration

Experiment

Experiment configurations represent the combination of topologies and scenarios to form an experiment (it should be note that an experiments do not require a scenario).

Experiment configurations are created from an existing topology and an optional scenario, with phenix experiment create or the web UI. A configuration file holding only the header below is not enough: its spec must already hold the experiment, so phenix config create rejects it. The header of an experiment named foobar, created from a topology named foobar and a scenario named foobar (none of the names are required to match), looks like this:

apiVersion: phenix.sandia.gov/v1
kind: Experiment
metadata:
  name: foobar
  annotations:
    topology: foobar # this is required
    scenario: foobar # this is optional
spec:
  ...

The experiment configuration has the topology and scenario configurations embedded in it, as well as additional details like cluster host schedules for VMs, VLAN ranges, etc. The advantage of embedding the topology and scenario into the experiment is that they can be modified in the experiment without modifying the originals.

Image

The Image configuration is used to generate VM disk images using a specific and custom version of vmdb2. Representing a disk image in a configuration like this allows for the same disk image to easily be built in different clusters without having to actually move large disk image files.

Warning

The phēnix image capability will only generation Linux based images. It will not generate Windows disk images.

Typically image configurations are created automatically by the phenix image create command, but users can also create them manually using a configuration file similar to the one shown below. This file can then be created in the phēnix store using the phenix cfg create <path-to-file> command.

apiVersion: phenix.sandia.gov/v1
kind: Image
metadata:
  name: foobar
spec:
  format: qcow2
  mirror: http://us.archive.ubuntu.com/ubuntu/
  overlay: []
  packages:
  - initramfs-tools
  - net-tools
  - isc-dhcp-client
  - openssh-server
  - init
  - iputils-ping
  - vim
  - less
  - netbase
  - curl
  - ifupdown
  - dbus
  - linux-image-generic
  - linux-headers-generic
  release: bionic
  size: 5G
  variant: minbase
  scripts:
    POSTBUILD_APT_CLEANUP: |
      apt clean || apt-get clean || echo "unable to clean apt cache"
    POSTBUILD_NO_ROOT_PASSWD: |
      sed -i 's/nullok_secure/nullok/' /etc/pam.d/common-auth
      sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
      sed -i 's/#PermitEmptyPasswords no/PermitEmptyPasswords yes/' /etc/ssh/sshd_config
      sed -i 's/PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
      sed -i 's/PermitEmptyPasswords no/PermitEmptyPasswords yes/' /etc/ssh/sshd_config
      passwd -d root

Warning

If no overlay is used in the image configuration, an empty array must be provided

User

The User configuration tracks phēnix UI user settings (e.g., username, password, and RBAC permissions). Typically user configurations are created automatically when a UI admin creates a new user via the UI, but they can also be created manually using a configuration file similar to the one shown below.

apiVersion: phenix.sandia.gov/v1
kind: User
metadata:
  name: admin@foo.com
spec:
  username: admin@foo.com
  first_name: Admin
  last_name: Istrator
  password: '<encrypted password>'
  rbac:
    roleName: Global Admin
    policies:
    - resourceNames:
      - '*'
      resources:
      - '*'
      - '*/*'
      verbs:
      - '*'
    - resourceNames:
      - admin@foo.com
      resources:
      - users
      verbs:
      - get

Role

The Role configuration is used to represent a named set of RBAC permissions that represent a user's role in the UI. When a new user is created, the role that user should have is specified, and using that role name the appropriate RBAC permissions are copied from the role configuration into the user configuration.

There are eight (8) default role configurations that get created automatically: the seven described under default roles, and Disabled, which allows nothing. An example role configuration is shown below for completeness.

apiVersion: phenix.sandia.gov/v1
kind: Role
metadata:
  name: global-admin
spec:
  roleName: Global Admin
  policies:
  - resourceNames:
    - '*'
    - '*/*'
    resources:
    - '*'
    - '*/*'
    verbs:
    - '*'

Resource names are matched with the same Kind/name or experiment/vm shape as the resource they belong to, and a * never crosses the /, which is why this role lists both * and */*. See Resources.

Web-UI

Config Table

The Configs component will initially load with a table presenting all the available configuration files. It is possible to filter in two ways:

  1. There is a pull-down selector, which will allow filtering on a specific Kind of config. Choosing All kinds puts every kind back in the table. Filter on Kind drop-down beside the Find a Config search box.
  2. A separate Find a Config field will allow filtering on Name (if you have filtered on Kind, it will be limited to that kind of config). Find a Config search box with a magnifying-glass icon.

Clicking on the X next to the Find a Config field will reset both filters.

The totals strip above the table counts the configs of each kind. Click the count of a kind to filter on that kind. Click the Configs total, or the count of the kind again, to show all kinds. The Kind selector shows the same filter.

The In Use column shows an icon for a topology or scenario that an experiment uses. An experiment uses the topology or scenario that its topology or scenario annotation names. This includes experiments that are not running. Hold the pointer on the icon to see the names of the experiments. For the other kinds of config, the column is empty.

View a Config

There are two ways to view a specific config:

  1. Clicking the name of the config entry will open a modal to view the config. It is possible to select text and copy from this modal. However, it is not possible to edit the config directly in this view. Instead, there is an Edit Config button, which will open an editor. It is also possible to download a copy of the config. From the keyboard, Tab to the name and press Enter. A topology or scenario name on the Experiments page opens its config in this viewer, too. The annotations of the config show next to its title. Above the text, the viewer shows the kind, name, creation time and update time of the config. Use the YAML and JSON buttons to change the format of the text. Use Wrap lines to wrap long lines, and Copy to copy the text. The viewer of an experiment config has a link to the experiment page. The viewer of a topology or scenario lists the experiments that use it. Config viewer dialog showing the YAML of Role/vm-viewer, with Edit Config, download and Exit buttons.
  2. Selecting the Edit button for a given config will open the editor window. It is possible to edit the config in this window and save the update to the phēnix store. The config will be validated against the schema, and if invalid, an error will be presented. Config editor with the name mirror, the kind Scenario and the YAML format selected, beside the scenario's YAML and Save and Exit buttons.

Topologies with a Builder diagram

A topology with a Builder diagram has the tag builder, and its Edit button opens the Builder, not the editor window, for a role with builder use. Other roles see an alert (see From the Configs page).

Create a Config

There are two ways to create a new config:

  1. Selecting the Upload button located to the far right of the search field will allow you to upload a file from disk. It is possible to drag and drop in the upload modal or click the upload icon to open a file browser. Upload a Config dialog with a drop zone that accepts .yaml, .yml and .json files.

    Note

    Only files with the extensions .yml, .yaml, and .json will be allowed. Any file uploaded will be validated against the schema for a given kind of config, and if invalid, an error will be presented.

  2. Clicking the + button next to the search field will present an editor window where it is possible to create a new file in place. A basic template is provided based on the kind of config selected (see next section for documentation on the editor window features). Once editing a config is completed, clicking the Create button will post it server-side where it will be validated, similar to file upload. If invalid, an error will be presented. New config editor with the placeholder name TODO, no kind selected, the YAML format, and a template config beside Create and Exit buttons.

Editor Window

The editor window allows direct editing of an existing or new config file.

  • From the keyboard, Tab stops on the editor once. Press Enter to type in it, and Escape to stop typing (twice in Vim mode), so that Tab moves on.

  • It is possible to edit a file as YAML or JSON by selecting the relevant radio button under File Format.

  • It is also possible to set keybindings to the Vim editor by enabling them with the sliding selector under Vim Mode. Editor settings with the File Format radio buttons set to YAML and the Vim Mode toggle disabled.

New Config

The editor window for creating a new config will allow editing the filename in a text field to the left or within the config editor directly. Similarly, use the pull-down selector to the left to select the kind of config or within the config editor.

Config Kind drop-down open below the Config Name field, listing Topology, Scenario, Experiment, Image, User and Role.

Selecting the Create button will post the new config server-side for validation and addition to the store. Choosing the Exit button will leave the editor window; nothing will be saved.

Existing Config

Changing the name in an existing config is only available through the editor window.

Editor for an existing Experiment config, with the Config Name and Config Kind fields grayed out beside its YAML.

Selecting the Save button will post any updates server-side for validation and addition to the store. Selecting the Exit button will leave the editor window; nothing will be saved.

Delete a Config

Selecting the delete icon will delete a config. A confirmation dialog will be presented to confirm the selection. Once the config is deleted, it cannot be restored to the store. If an experiment config is deleted, the corresponding experiment will not longer be presented in the Experiments tab.

Edit, download and delete icon buttons from a config row.

Environment Variables

Phēnix supports environment variables in its configuration files. When the CLI reads a config file, such as with phenix config create <file>, it replaces each environment variable placeholder with the value of that variable. Placeholders can be in the format ${VAR} or ${VAR:default}, where VAR is the environment variable name, and default is an optional default value to use if the variable is not set. If the variable is not set and no default is provided, the command stops with an error and changes nothing. Write ${VAR:} for a variable that can be empty. A $VAR without braces is not a placeholder. Write $${VAR} to keep the text ${VAR} in the config.

Note

For a config sent to the REST API or the web UI (POST /configs, PUT /configs/{kind}/{name} and the workflow endpoints), with a JSON or YAML body the server fills in only ${BRANCH_NAME}. It stores every other placeholder as written, so a client cannot read the server environment through a config. Of these, only the workflow endpoints take variables, in the variables part of a multipart/form-data request; the server then also fills in the placeholders from the variables and their defaults (see REST API). POST /configs and PUT /configs/{kind}/{name} do not: a client fills in the other placeholders before it sends a config. The Builder fills in no placeholders. A ${BRANCH_NAME} in these requests is filled in also when the stored config holds it as text. For POST /configs and PUT /configs/{kind}/{name}, the value is the BRANCH_NAME variable of the server, or empty text when it is not set. Write $${BRANCH_NAME} to keep the text.

Example config before parsing environment variables:

  - name: foobar
    metadata:
      baz:
        ip: ${HOST:localhost}

After parsing with HOST=172.1.3.37:

  - name: foobar
    metadata:
      baz:
        ip: 172.1.3.37

Or if HOST env variable isn't found, the default is used:

  - name: foobar
    metadata:
      baz:
        ip: localhost

Variable Sources

These commands read config files and fill in their placeholders: phenix config create, phenix config apply, phenix config diff, phenix experiment create with a file for -t or -s, and phenix workflow apply. phenix experiment create also fills in a topology file that includeTopologies names by a path, and so does the server for phenix workflow apply. A command gets the value of a variable from the first of these sources that has it:

Source Description
-e, --env -e NAME=value sets a variable. -e NAME copies the value of NAME from the shell. Repeat the flag for more variables. If a name is given more than once, the last value is used.
--env-file An env file of NAME=value lines. Repeat the flag for more files. A later file overrides an earlier file. A relative path starts at the working directory. phenix workflow apply reads .env in the topology directory when no --env-file is given.
The shell The environment of the command, without the variables whose names start with PHENIX_. Those variables hold the settings of phēnix. Name one with -e NAME to use it. A variable whose name is not a valid variable name, for example 1A, is not used.
phenix config create topology.yml -e HOST=172.1.3.37
phenix config apply configs/* --env-file site.env -e NODES=3

A command reads every file and checks every variable before it changes anything. It stops, and changes nothing, in these cases:

  • A placeholder has no value and no default.
  • No file uses a variable that -e sets. This is usually a typing mistake.
  • A value or a default contains a line break.

The command replaces the text of a placeholder before it reads the YAML or JSON. Thus a placeholder in a comment is also filled in, and a value can change how YAML reads a line. Put a placeholder in quotes when its value can contain : or #.

phēnix does not have the Docker Compose forms ${VAR:-default} and ${VAR:?error}. For phēnix, the default of ${VAR:-3} is the text -3. The command logs a warning for a default that starts with - or ?.

The log shows the name and the source of each variable that a file uses. It shows the values only with --log.level debug. Debug records can thus hold secrets, also in the log file.

Warning

In earlier releases, a variable that was not set became an empty string, and the CLI used every shell variable. A config that relied on this now stops the command. Give the placeholder a default, such as ${VAR:}, or name a PHENIX_ variable with -e.

Env Files

An env file holds one variable on each line:

# Blank lines and lines that start with "#" are skipped.
SITE=lab
NODES=3
export IMAGE=ubuntu.qc2
MOTD="  the quotes keep the spaces  "
  • A line is NAME=value, with no space before the =. A name starts with a letter or _, and continues with letters, digits and _.
  • export before the name is permitted.
  • A value in single or double quotes is the text between the quotes. The closing quote must be the last character of the line.
  • Any other value is the text as written, a # included, without the spaces and tabs at the end of the line.
  • Nothing in the file is expanded: ${OTHER} and \n stay as written. For a workflow, the server fills in a ${BRANCH_NAME} that a value carries.
  • When a name is on more than one line, the last line is used.
  • Any other line is an error that names the file and the line.

Environment variables using Docker

If phēnix is running in a docker container (or docker compose), environment variables can be passed into the compose file and/or via args in any CLI calls to phēnix, e.g.

    environment:
      HOST: ${HOST}

or

docker exec -it -e BRANCH_NAME=foobar phenix phenix exp create foobar -t topo -s scenario

Tip

Configs sent by phenix workflow apply, or to the /workflow/configs/{branch} and /workflow/apply/{branch} API endpoints, don't need -e BRANCH_NAME: phēnix sets BRANCH_NAME to the workflow branch name itself. The API endpoints keep their other placeholders as written unless the request sends variables, and phenix workflow apply sends its variables with each config (see Variables). The command also copies the topology directory's phenix-injects/ to <base-dir.injects>/<name> (by default /phenix/injects/<name>), so configs can reference injected files as /phenix/injects/${BRANCH_NAME}/<file>. See Workflow.