Skip to content

Settings & Configuration

phēnix supports dynamic configuration management via the phenix settings command. A running phenix ui applies changes to the log.* settings, ui.logs.level, experiment.disk-check, minimega.read-connections and the users file at once, without restarting. It reads every other setting only at startup.

Configuration Files

phēnix looks for a configuration file (e.g. config.yaml, config.json, config.toml) in the following locations, in order, and reads the first it finds:

When run as root:

  • ./config.yaml (the working directory)
  • /etc/phenix/config.yaml

When run as a regular user:

  • ./config.yaml (the working directory)
  • $HOME/.config/phenix/config.yaml
  • /etc/phenix/config.yaml

It looks for users.yaml in the same locations. sudo phenix searches as the user that runs sudo, so it also searches that user's $HOME/.config/phenix.

Example Configuration

base-dir:
  minimega: /tmp/minimega
  phenix: /phenix
log:
  level: info
  console: stderr
  system:
    path: /var/log/phenix/phenix.log
store:
  endpoint: bolt:///etc/phenix/store.bdb
ui:
  listen-endpoint: 0.0.0.0:3000
  jwt-signing-key: abcde12345
  logs:
    minimega-path: /var/log/minimega/minimega.log

Configuration vs. Data Store

It is important to distinguish between the System Configuration and the Data Store:

  • System Configuration (config.yaml): Configures the phēnix daemon itself. It controls how the service runs (e.g., log levels, API ports, storage backend connection strings).
  • Data Store (BoltDB): Stores the application state. It holds what phēnix manages (e.g., defined experiments, topologies, user accounts, active VM states).

Deleting config.yaml resets daemon behavior to defaults. Deleting the Data Store results in data loss (experiments, users, etc.).

Store Configuration

The phenix tool uses a bbolt key-value data store, a single file with no external dependencies that is only accessible on one machine. Set its path with the bolt:// store endpoint (e.g. bolt:///etc/phenix/store.bdb). phenix no longer supports the etcd:// store endpoint.

Managing Settings

# View all current runtime settings
phenix settings list

# Change log level to debug
phenix settings set log.level debug

# Revert a setting to default
phenix settings unset log.level

# Reset all settings
phenix settings unset --all

phenix settings set gives the value the type of the flag of the setting. For example, log.system.max-size takes an integer, ui.jwt-lifetime takes a duration such as 24h, and ui.users takes a comma-separated list. A string setting, such as ui.jwt-signing-key, keeps the text as it is, so 0123 stays 0123. The command refuses a value that does not have the type of the setting.

phenix settings set and phenix settings unset change only the key. The comments, the key order and the other keys in the file stay. A new key goes at the end of its section. An empty section, such as {}, changes to block style when you set a key in it. When you unset a key that is not in the file, the file does not change.

Checking the Configuration

phenix doctor checks the configuration without a running phenix ui. It runs these checks:

Check Group Warns when Fails when
config-file, users-file config no config.yaml is found the file does not parse or cannot be read, so phēnix ignores it; for a parse error the row gives the line, never the file's content
config-keys config the config files hold keys that are not phēnix settings, such as a misspelling never
config-paths config phēnix ignores a config or users file on the search path, since it reads only the first of each name; the row lists the directories searched and each file found never
settings-file config phenix settings set would write a file other than the config file phēnix reads, a file that is not YAML, or a file this user cannot write or create never
scenario-hosts config an app in the scenario of a stored experiment names a host (hosts[].hostname) that is not a node of the topology of the experiment. The apps of phēnix find a host by its exact host name, and skip a host that they do not find. A skip row shows when doctor cannot read the store, or when the store file does not exist never
env (one row per set variable, named after it) env a PHENIX_* variable is empty, a flag overrides it, phēnix reads it as a value other than the one written (such as 010 as 8), it holds a log level phēnix ignores, or it names no setting, such as a misspelling; PATH has relative entries; SUDO_USER names no user when root runs phēnix through sudo phēnix would refuse or misread a PHENIX_* value; EDITOR is not a program on PATH
env-overrides env a PHENIX_* variable overrides a different value in the config or users file; the row names the variable, the setting and the file, never a value never
proxy-env env a proxy variable is set, and NO_PROXY or no_proxy does not cover a host of phenix ui. The proxy variables are HTTP_PROXY, HTTPS_PROXY, http_proxy and https_proxy. The hosts are localhost, 127.0.0.1, ::1, the host name and the host of ui.listen-endpoint. Programs that read these variables send their requests for such a host to the proxy. The row reads the forms *, .domain, *.domain, a CIDR range and host:port, as Go does. It names the variables, never their values, because a proxy URL can hold a password never
bridge-mode, deploy-mode, experiment.disk-check, color, log.level, log.system.max-size, log.system.max-backups, log.system.max-age, minimega.read-connections settings log.level is not a level phēnix knows, so it logs at info; a log.system.* value is not a whole number, so phēnix reads 0 (100 MB for max-size, no limit for the others); max-backups or max-age is negative; minimega.read-connections is not a whole number from 3 to 64, so phēnix uses the nearest value in that range bridge-mode, deploy-mode, experiment.disk-check or color is a mode every phēnix command refuses; log.system.max-size is negative, so every write to the system log fails
store.endpoint files never the file cannot be written, or its directory does not exist or cannot be written
store-file (only when the store file exists) files one of its two meta pages is corrupt, so BoltDB reads the other, which may not hold the last write the file is not a BoltDB file, has another format version or byte order, is shorter than its two meta pages, or both meta pages are corrupt
store-owner (only when the store file exists) files another user owns the file and this user is not root; as root under sudo phenix, the file does not belong to the user whose store sudo phenix uses never
store-root (only for the default store of a user other than root) files /etc/phenix/store.bdb exists, or this user cannot see whether it exists, so a phenix ui that runs as root uses a different store never
store-fs files the directory of the store file is on a network filesystem, such as NFS, SMB, CIFS, Ceph, 9p, Lustre, GPFS, GFS2 or AFS. Or it is on a FUSE filesystem, such as sshfs. On these filesystems, the file locks and fsync that BoltDB needs can fail. The row also warns when a store file of more than 100 MiB has more than 50% free pages. bbolt compact makes such a file smaller. doctor reads the free page list from the file without the lock, so it does not wait for phenix ui. doctor reads the filesystem type only on Linux, and gives a skip row when it can check neither part never
log.system.path, log.console files never the file (phenix.log in it when log.system.path is a directory) cannot be written, or created in the nearest directory above it that exists; log.console gets a row only when it names a file
secret-files files a file that holds a secret is readable by its group or by others. These files are the TLS key (ui.tls-key), each config or users file that sets ui.jwt-signing-key or ui.users, and the store file. The store file holds password hashes and tokens. The row also warns when another user owns the TLS key or such a config file. Only root and the user that runs phēnix can own them. doctor reads only the file information, never the contents. On a system without Unix file modes, the row is skip never
inject-sources files the source (src) of a node injection does not exist on this host, so minimega disk inject cannot copy it at the start. For a stored experiment, doctor checks the injections of each VM that gets injects: snapshot: true and an inject partition other than 0. It finds a relative source in the baseDir of the experiment. It does not check an absolute source in the baseDir, because apps write those files at the start. For a stored topology, doctor checks only the absolute sources. A skip row shows when doctor cannot read the store never
base-dir.phenix, base-dir.minimega, base-dir.injects, base-dir.topologies, mount-dir dirs the directory does not exist, is not readable and searchable by this user, is relative, or is one phēnix writes to and is not writable by this user the path is not a directory
base-dir.builder-templates dirs the path is not a directory, the directory is not readable and searchable by this user, or the path is relative. The row also warns when the setting names a path that does not exist, and when phenix ui skips a template file in the directory. The row names each skipped file, at most 5, but never why: phenix ui logs the reason at start. A missing directory passes when the setting is not set, because phenix ui only reads the directory and never makes it never
ui.shutdown-grace-period, ui.netflow.max-size, ui.captures.max-size ui never phenix ui would refuse the value
ui.jwt-signing-key auth the key is empty (no sign-in) or a development key a development key does not name exactly a user and a role, so phenix ui refuses every request
ui.jwt-lifetime auth never phēnix reads the value as under a minute: 24 is 24 nanoseconds, and a value that is not a duration, such as 1d, is 0
ui.users auth an entry's role is not built in, so phenix ui skips the user unless the store holds the role; the list is empty while sign-in is on, so phenix ui creates the default user admin@foo.com an entry is not name:password:role[:resource...], which phenix ui skips without an error, or its role holds a comma; a row names an entry by position and user name, never by its password
proxy-jwt (only with the proxy-jwt key) auth ui.listen-endpoint listens on every address, and phenix ui does not check the signatures of proxy JWTs never
ui.proxy-auth-header (only when set) auth the JWT signing key is empty or a development key, so phenix ui ignores the header the value is not an HTTP header name
rbac-users (only with sign-in on) auth the role (rbac.roleName) of a stored user is not a stored role or a built-in role. Or a role names an experiment, a VM (<experiment>/<vm>) or a user that the store does not have. The row checks each stored role and the copy of the role in each user. The row checks only the names without a glob (*, ?, [) or !. It checks them only in a policy for experiments and VMs, or for users. It never shows a password or a token. A skip row shows when doctor cannot read the store never
ui.tls tls never only one of ui.tls-key and ui.tls-cert is set, so phenix ui serves plain HTTP; a file cannot be read; the key and certificate do not load as a pair
ui.tls-cert (only when both TLS settings are set) tls the certificate expires within 30 days, or it has no DNS or IP names. The row also warns when the names do not cover the host that users reach. That host is the host of ui.listen-endpoint, or the host name when phenix ui listens on every address. A host name without a domain, such as ws42, also matches a name such as ws42.example.com. The row gives the expiry date and the names. A skip row shows when the key pair does not load the certificate expired or is not valid yet
ui.listen-endpoint, ui.file-server-endpoint tls the listen endpoint has no port, so phenix ui listens on a random one phenix ui cannot listen on the value or refuses it
unix-socket socket the path is relative, or holds a file that is not a socket, which phenix ui deletes; this user cannot write the directory, but a socket is there, such as one a phenix ui of another user serves the directory does not exist, this user cannot write it and no socket is there, or the path is too long for a unix socket
unix-socket-gid socket phēnix runs as root and no group has the id phēnix does not run as root, and this user is not in a group of that id, so phenix ui exits when it sets the socket's group
server (with the rows server bridge-mode and server deploy-mode when phenix ui answers) server no phenix ui answers on unix-socket: no socket file, a stale one, a file that is not a socket, or no answer within --timeout; the version of phenix ui is not the version of this phēnix; its bridge-mode or deploy-mode is not the one set here this user may not connect to the socket
stuck-status server the store marks app runs, SCORCH runs or delayed starts of a running experiment as in progress, but no phenix process can own them. That is, no phenix ui answers on unix-socket, and no other phenix process on this host names the experiment. This occurs when phenix ui stops during a start or a run. The row also warns when phēnix could not resume the start of a running experiment, and when the store marks a start as in progress that no phenix process runs. A skip row shows when doctor cannot read the store never
ui-limits (Linux only) server the phenix ui process on this host has more than 80% of its soft limit of open files open. doctor finds the process from the peer of unix-socket, or from its command line in /proc. A skip row shows when no phenix ui runs on this host, or when this user cannot read /proc/<pid> never
minimega minimega never minimega does not give its version on <base-dir.minimega>/minimega within --timeout (3 seconds by default); the row names the likely cause: no socket, a stale one, or a user that may not connect
minimega-env (the rows minimega files, minimega base and minimega mesh; one skip row when minimega gives no version) minimega minimega gives no flags (it is older than 3.0); its -filepath is relative or not writable by this user; its -base is not base-dir.minimega; mesh status fails when -degree is above 0 the -filepath directory does not exist for phēnix or is not readable and searchable by this user
experiment-files minimega <base-dir.phenix>/images is not minimega's -filepath. phēnix keeps the files of each experiment in <base-dir.phenix>/images/<experiment>/files, but the Files tab lists the files in minimega's -filepath. Thus the Files tab does not show the files that phēnix writes, such as VM screenshots. The row names the two paths. Two paths that phēnix finds to be one directory, such as through a symlink, pass. A skip row shows when minimega gives no version, no flags or no absolute -filepath never
minimega-limits (the rows minimega-limits open files and minimega-limits memory; Linux only) minimega the open files row: the soft limit of open files of the minimega process is lower than its VMs on this node need. The estimate is 64 files, and 5 for each VM (QMP, VNC, cc and two qemu output pipes). The row also warns when more than 80% of the limit are open. The memory row: MemAvailable is less than 10% of MemTotal, more than 50% of the swap is in use, or the VMs on this node ask for more memory than the memory and swap together. doctor finds minimega through minimega.pid in its -base. A skip row shows when this user cannot read /proc/<pid>, or when minimega runs in another container never
state-drift (the rows state-drift experiments and state-drift namespaces) minimega the experiments row: the store marks an experiment as running, but minimega has no namespace or no VMs for it, such as after minimega restarted. The namespaces row: a minimega namespace has VMs, but no stored experiment has its name. Both rows are skip rows when doctor cannot read the store or minimega never
vlans (the rows vlans pinned and vlans free) minimega the pinned row: two stored experiments pin the same VLAN ID in vlans.aliases, so they cannot run at the same time. The free row: a stopped experiment cannot get its VLANs now. Its range (vlans.min and vlans.max, else the range of minimega) has fewer free VLANs than the experiment needs. Or its range overlaps the range of another namespace, or another namespace uses a VLAN that it pins never
bridge-trunk (Linux only) minimega minimega's mesh has more than one node, and an experiment bridge on this node has no trunk or tunnel port. An experiment bridge is phenix, or a bridge with VM taps. A trunk is an untagged port of a physical NIC, a bond, a VLAN device or a tunnel, such as the port that minimega bridge trunk adds. With one node, the row is the skip row "one node, no trunk needed". With use-gre-mesh on, the row passes never
schedule-hosts minimega the VM schedules (schedules) of a stored experiment name a cluster node that is not in minimega's mesh (mesh list all). The row compares the names without the hostname-suffixes never
cc-clients minimega a VM of a running experiment has run for 5 minutes or more, phēnix needs a miniccc client in it, and minimega's cc clients has none for it. phēnix needs a client when the startup app sends its scripts through miniccc, when another VM waits for the client at the start (delay.c2), or when the soh app checks the VM. The row also warns when the last MiB of minimega's -logfile shows a miniccc version that differs from the minimega version for a client, in a line logged after the VM of that client launched. doctor does not read a relative -logfile never
qemu-img, vmdb2 tools never the program is not on PATH, or qemu-img --version fails: phēnix commits VMs to disk images with qemu-img, and phenix image build runs vmdb2
filebeat tools the program is not on PATH, so SCORCH starts no Filebeat, even for a component that enables it never
disk (one row per filesystem, such as disk phenix-base) tools the filesystem of base-dir.phenix, the store or minimega's -filepath is 90% full the filesystem is 98% full
kernel-modules (Linux only) tools /lib/modules/<kernel release> does not exist, so modprobe cannot load modules such as nbd and openvswitch; /var/run/reboot-required exists. A container without /lib/modules gives a skip row never
nbd (Linux only) tools the nbd module is not loaded, is part of the kernel (so lsmod does not show it), or has max_part missing or 0; no /dev/nbdN device is free, or a container has no /dev/nbd* device; a device has a lock file in /var/lock and no connection, belongs to a process that is not running, or holds an image for a qemu-nbd that a failed inject can leave, with its mounted partition. minimega disk inject uses these devices for injects at a start and for phenix image inject-miniexe. A row for a missing module points to kernel-modules qemu-nbd is not on PATH
openvswitch (Linux only) tools this user cannot connect to ovsdb-server (permission denied), but minimega runs ovs-vsctl as root; ovs-vswitchd does not run; the openvswitch module is not loaded, and the row points to kernel-modules. The row gives the Open vSwitch version, and tells if the bridge phenix exists or if minimega makes it at the first VM launch. In a container without ovs-vsctl, the row is skip ovs-vsctl is not on PATH; ovs-vsctl show gets no answer from ovsdb-server within --timeout
image-build (the rows image-build tools, image-build root, image-build loop and image-build keyrings; Linux only) tools debootstrap, kpartx, losetup or qemu-img is not on PATH; the process does not have CAP_SYS_ADMIN (not root, or a container that is not privileged); no /dev/loop* device is free and there is no /dev/loop-control; debootstrap has no script for the release of a stored image config, or the keyring that the script names does not exist. The keyrings row reads the image configs from the store read-only, and gives skip when the store is locked for longer than --timeout never
image-configs tools an overlay directory (overlays) of a stored image config does not exist or is not a directory, so phenix image build fails. The row also names each script file of a config that is not on disk, without a warning. The config holds a copy of each script, which the build uses and phenix image update keeps never
disk-chains images a disk image in the images directory has a broken backing chain: a backing file is missing, the chain loops, or the chain is more than 64 images deep; the row names at most 5 such images and counts the rest; the directory cannot be listed; the check does not finish within --timeout never; the images directory is minimega's -filepath, or <base-dir.phenix>/images when minimega gives none, and a skip row shows when it does not exist
disk-formats (a second row when an image needs a later qemu) images a disk image in the images directory is in an old or unsupported format: qcow2 version 2, qcow version 1, vmdk or qed. It also warns about an image that qemu refuses, such as an encrypted or corrupt image, and when the local qemu-img is older than the qemu version that a feature of an image needs. The row names at most 5 such images and counts the rest. It also warns when it cannot list the directory, or when the check does not finish within --timeout. never. It reads the headers that the disk-chains check reads, in the same pass over the images directory, and a skip row shows when that directory does not exist
writable-images images a VM of a stored experiment has snapshot: false, so minimega writes to its drive images. The row warns when another image in the images directory has such an image as a backing file, because the writes break that image. It also warns when more than one VM uses such an image. It reads the experiments from the store, and the backing files from the pass of disk-chains never. A skip row shows when the store cannot be read, or when the store file does not exist
leftovers (the rows leftovers snapshots, leftovers files, leftovers mounts, leftovers taps and leftovers mirrors) images the snapshots row: a snapshot file of this head node in the images directory (<head node>_<experiment>_<VM>_snapshot) belongs to an experiment that the store does not have. The files row: a base directory in <base-dir.phenix>/experiments, or a directory with files, miniccc_responses or a minirouter-<VM> file in the images directory, belongs to such an experiment. The row gives each size and the total. The mounts row: a VM file system mount under mount-dir belongs to such an experiment, or to a VM that minimega does not run. The taps row: a minimega tap (mega_tap*) on this host or on an Open vSwitch bridge has no owner, or a port has no network device. An owner is a VM or a host tap in a minimega namespace, or a capture of a whole bridge. The mirrors row: a minimega mirror (mirror-<tap>) belongs to no capture. The rows keep what belongs to a namespace in which minimega runs a VM. In a container, the taps row checks the taps of this host only when it shows a minimega tap, an Open vSwitch bridge or the ovs-system device. A row that cannot get its data from the store, minimega or ovs-vsctl is a skip row with the reason. A store file that does not exist gives a skip row, because phenix doctor can read a store other than the store of phenix ui never
disk-space (one row for each filesystem, such as disk-space files, and the row disk-space inject dirs) images the filesystem of the images directory, of minimega's -base or of minimega's -logfile has less free space than 10% of its size or 5 GiB, whichever is larger. The row names each filesystem once. It gives the size of the minimega log, and the size of the files that the leftovers rows found. The inject dirs row warns about each dstImg* directory in minimega's -base, which a failed disk inject can leave, and tells which ones are mounted never
image-locks (Linux only) images a qemu-system, qemu-nbd or qemu-img process holds open a drive image of a stopped experiment, or one of its backing files, and is not a VM of a running experiment. qemu then cannot get the lock it needs to start the VM (Failed to get "write" lock). Any open of an image that a VM writes to (snapshot: false) blocks the start. An open of another image blocks it only when the process can write to the file. The row tells how many processes this user cannot read never. A skip row shows in a container that shows no minimega process, because the container can have its own PID namespace
inject-partitions images the inject partition of a VM of a stored experiment is not one that minimega can write files to at a start. The row checks each VM with snapshot: true and an inject_partition other than 0 on its first drive, which gets injects, deletions or the scripts of the startup app. The partition numbers are the numbers that Linux and minimega use: 1 to 4 for MBR primary partitions, 5 and up for logical partitions, and the entry number for GPT. The row warns when the disk has no partition table, when it has no partition 1 (minimega waits for partition 1 before it opens any partition, so the start fails with no partitions found on image), when it has no partition of that number (desired partition N not found), or when the partition is an extended partition. It also warns when the partition holds swap, an LVM physical volume, a LUKS volume, a read-only file system, or no file system that doctor knows. It also warns when the partition is smaller than 1 GiB and the disk has a larger Linux or NTFS partition, such as a Windows System Reserved partition. The row gives the VMs, the image, the partitions it found (number, type, file system and size), and the largest Linux or NTFS partition as the inject_partition to try. It also warns when an NTFS inject partition is dirty or Windows did not shut down fully (hibernation or Fast Startup), or when an ext file system has errors. doctor reads each image once, at most 16 MiB of it and 512 KiB more for the file system states, a qcow2 or qcow image through its backing chain with qemu-img dd -U. never. The row does not check an image that does not exist, a qcow2 image when qemu-img is not installed, or a partition past the part of the disk that doctor reads. A skip row shows when doctor checks no inject partition, or cannot read the store
apps apps never never; the row lists the user apps (phenix-app-*) and SCORCH components (phenix-scorch-component-*) found on PATH
scenario-apps apps an app of a stored scenario or experiment is not built in, and PATH has no phenix-app-<app>. Or a SCORCH component type (its type, else its name) is not built in, and PATH has no phenix-scorch-component-<type>. The built-in apps are ntp, serial, startup, vrouter, tap, soh and scorch. The built-in SCORCH components are break, pause, soh and tap. A skip row shows when doctor cannot read the store never
app-runtimes apps a phenix-app-* or phenix-scorch-component-* program on PATH is not executable by this user, so phēnix does not find it. Its #! line names an interpreter that does not exist or that this user cannot run, or a program that env cannot find on PATH. Its #! line ends in a carriage return (Windows line ends) never
tunneler-download, webshark features downloads/tunneler is not a directory never; the row says whether phenix ui turns the feature on
ui.features features a name is not a feature, such as a misspelling; tunneler-download or file-server is set without what it needs; minimega-captures is set, which has no effect webshark is set without a WebShark build, which phenix ui refuses
minimega-captures features doctor cannot read the version that the minimega check read. A skip row shows when minimega gave no version never; the row says whether minimega supports experiment captures (3.4.0 or later)
ui.logs.minimega-path features the file does not exist or is not readable by this user; the setting is empty while minimega logs to a file (its -logfile, or MM_LOGFILE in the environment) the path is not a regular file

Configuration Precedence

phēnix resolves each setting in the following order (highest to lowest):

  1. Command Line Flags: Arguments passed directly to the binary (e.g., phenix ui --log.level=debug).
  2. Environment Variables: Variables like PHENIX_LOG_LEVEL. An empty variable is ignored.
  3. Config File: Settings in config.yaml (managed via phenix settings set), with users.yaml merged over it.
  4. Defaults: Internal application defaults.

A PHENIX_* variable therefore hides a value that phenix settings set writes to the config file. phenix doctor warns about each one in its env-overrides check; unset the variable to use the file's value.

Global Flags

The following global flags are supported by all phenix subcommands. The CLI reference lists them with every command's own flags.

Flag Type Default Description
--base-dir.builder-templates string <base-dir.phenix>/builder/templates Directory of Builder node template files that phenix ui reads at start. See Template files on the server.
--base-dir.injects string <base-dir.phenix>/injects Directory that phenix workflow apply stages topology injects into. The phenix ui server reports its value to the CLI, and the flag on the phenix workflow apply command line overrides it. See Workflow.
--base-dir.minimega string /tmp/minimega Base minimega directory.
--base-dir.phenix string /phenix Base phēnix directory.
--base-dir.topologies string <base-dir.phenix>/topologies Directory that phenix workflow apply looks up topology directory names in. See Workflow.
--bridge-mode string manual Bridge naming mode for experiments (auto uses experiment name for bridge; manual uses user-specified bridge name, or phenix if omitted). A phenix ui running in auto mode makes the commands that reach it over --unix-socket use auto. See Bridge Mode.
--color string auto When to color the output (auto, on, or off). auto colors only a terminal, and not when NO_COLOR is set or TERM is dumb.
--deploy-mode string — Deploy mode for minimega VMs (all, no-headnode, or only-headnode).
--experiment.disk-check string error What a start does when a VM disk image or CD-ROM image is missing, or its backing chain is broken (error, warn, or off).
-h, --help — — Display help information for the command.
--hostname-suffixes string -minimega,-phenix Hostname suffixes to strip.
--log.console string stderr Destination output for console logs in text format (stderr, stdout, or a file path).
--log.level string info Level to log messages at (debug, info, warn, error).
--log.system.max-age int 90 Maximum number of days to retain old log files.
--log.system.max-backups int 3 Maximum number of old log files to retain.
--log.system.max-size int 100 Maximum size in megabytes of the system log file before rotation.
--log.system.path string /var/log/phenix/phenix.log Path to persistent system log in JSON Lines format, with one JSON object per line.
--minimega.read-connections int 16 Maximum number of read-only commands that phēnix sends to minimega at the same time, from 3 to 64. phēnix keeps 2 of them for reads of the head node.
--mount-dir string <base-dir.phenix>/mounts Base directory for VM filesystem mounts.
--store.endpoint string bolt:///etc/phenix/store.bdb BoltDB store endpoint (bolt://<path>).
--unix-socket string /tmp/phenix.sock phēnix unix socket to listen on (ui subcommand) or connect to.
--use-gre-mesh bool false Use GRE tunnels between mesh nodes for VLAN trunking. See GRE Mesh.

Settings Reference

Setting Key Environment Variable Default Description
bridge-mode PHENIX_BRIDGE_MODE manual Bridge naming mode for experiments. auto uses the experiment name as the bridge name; manual uses the user-specified bridge name, or phenix if not specified. See Bridge Mode.
experiment.disk-check PHENIX_EXPERIMENT_DISK_CHECK error What a start does when a VM disk image or CD-ROM image is missing, or its backing chain is broken. error refuses the start, warn starts the experiment and shows each problem as a warning, and off does not check the images. It applies to every start: the CLI, the web UI, the REST API, phenix workflow apply, and the bulk start and restart of VMs. phēnix refuses another value. phenix ui applies a change at once.
use-gre-mesh PHENIX_USE_GRE_MESH false Enable Layer 2 GRE tunnels for the default bridge of experiments created or updated with this setting. See GRE Mesh for usage, server inheritance, and MTU requirements. phenix ui reads this setting at startup. (Restart Required)
log.level PHENIX_LOG_LEVEL info Global log verbosity (debug, info, warn, error).
color PHENIX_COLOR auto When phēnix colors its output: statuses in tables, phenix doctor rows, warnings and errors. auto colors only a terminal, and not when NO_COLOR is set or TERM is dumb. on and off ignore both variables. JSON and YAML output never have color. phēnix refuses another value.
log.console PHENIX_LOG_CONSOLE stderr Destination for console logs (stderr, stdout, or a file path). Uses Text/Human-Readable format. Note: Setting this to a file path will prevent console logs from appearing in docker logs.
log.system.path PHENIX_LOG_SYSTEM_PATH /var/log/phenix/phenix.log Path to the persistent system log file (used by UI). Uses JSON format. This is independent of log.console and is always active.
log.system.max-size PHENIX_LOG_SYSTEM_MAX_SIZE 100 Max size in MB before rotation.
log.system.max-backups PHENIX_LOG_SYSTEM_MAX_BACKUPS 3 Number of old log files to retain.
log.system.max-age PHENIX_LOG_SYSTEM_MAX_AGE 90 Max age in days to retain old logs.
ui.logs.level PHENIX_UI_LOGS_LEVEL "" Log level for the web UI stream (defaults to log.level).
minimega.read-connections PHENIX_MINIMEGA_READ_CONNECTIONS 16 Maximum number of read-only commands, such as vm info, that phēnix sends to minimega at the same time. Each command uses a connection of its own, which phēnix opens when it needs one and closes after 5 minutes without use. The value must be from 3 to 64. phēnix uses the nearest value in that range for a value outside it, and logs a warning. phēnix keeps 2 connections for reads of the head node only, and lets screenshots use at most 4 fewer than the maximum. It applies to phenix ui and to every CLI command. phenix ui applies a change in the config file at once, unless a flag or an environment variable sets the value. The Settings page of the web UI also changes it.
ui.logs.minimega-path PHENIX_UI_LOGS_MINIMEGA_PATH "" Path to the minimega log file to display in the UI and offer for download on the Logs page. (Restart Required)
ui.features PHENIX_UI_FEATURES "" Optional UI features to enable. Separate them with commas in the --features flag and with spaces in PHENIX_UI_FEATURES. Use a YAML list in the configuration file. Currently supports vm-mount, which enables transferring files to and from a running VM (see Mount a VM). phenix ui turns on webshark, tunneler-download, file-server and minimega-captures itself, and refuses to start with webshark set but no WebShark build. (Restart Required)
ui.file-server-endpoint PHENIX_UI_FILE_SERVER_ENDPOINT 0 (disabled) Address (port or host:port) for the separate experiment file-upload server. A port-only value binds to 127.0.0.1. Also works with the vm-mount feature - see Uploading Experiment Files from the phēnix Server. If it is set and the address cannot be listened on, phenix ui exits with an error. (Restart Required)
ui.shutdown-grace-period PHENIX_UI_SHUTDOWN_GRACE_PERIOD 5 How many seconds stopping phenix ui may take to finish requests and jobs and close connections, as a whole number such as 10. 0 closes everything without waiting; a negative value, or one that is not a whole number of seconds (such as 10s or 1.5), is refused at startup. Also phenix ui --shutdown-grace-period. (Restart Required)
ui.netflow.max-size PHENIX_UI_NETFLOW_MAX_SIZE 100 Maximum size in megabytes of each recorded netflow capture, as a whole number. A capture that reaches it stops recording and is marked truncated, while the live view goes on. 0 does not record captures; a negative value, or one that is not a whole number, is refused at startup. Also phenix ui --netflow.max-size. (Restart Required)
ui.captures.max-size PHENIX_UI_CAPTURES_MAX_SIZE 10240 Maximum size in megabytes of each packet capture file that minimega writes, as a whole number. 0 sets no limit; a negative value, or one that is not a whole number, is refused at startup. Also phenix ui --captures.max-size. (Restart Required)
mount-dir PHENIX_MOUNT_DIR <base-dir.phenix>/mounts Base directory used for VM filesystem mounts created via phenix vm mount. See Mount a VM.
base-dir.injects PHENIX_BASE_DIR_INJECTS <base-dir.phenix>/injects Directory that phenix workflow apply stages a topology directory's phenix-injects/ into, as <base-dir.injects>/<name>. The phēnix server's value is used unless --base-dir.injects is given; see Workflow. Use an absolute path. (Restart Required)
base-dir.topologies PHENIX_BASE_DIR_TOPOLOGIES <base-dir.phenix>/topologies Directory where phenix workflow apply NAME looks for NAME when NAME isn't an existing path. Use an absolute path. See Workflow.
base-dir.builder-templates PHENIX_BASE_DIR_BUILDER_TEMPLATES <base-dir.phenix>/builder/templates Directory of Builder node template files (*.yaml, *.yml, *.json) that phenix ui reads at start as read-only server collections. Use an absolute path. See Template files on the server. (Restart Required)

Web UI Session Timeout

The web UI's Settings page (admin-only) can also automatically log out idle users. Unlike the settings above, this is stored in the data store and takes effect immediately when saved — no config.yaml or restart involved.

Setting Default Description
Log out idle users Disabled Enables the idle timeout.
Idle timeout (minutes) 30 Minutes of inactivity before an idle user is logged out. The minimum is 0.5.
Warning before logout (minutes) 3 How long before logout to warn the user. This value must be less than the idle timeout.

phēnix Apps Environment Variables

Apps (phenix-apps) run as subprocesses and read their configuration from the environment. phēnix sets these itself when it launches an app:

Environment Variable Value Description
PHENIX_DIR base-dir.phenix Base phēnix data directory.
PHENIX_FILES_DIR experiment files directory Where the app reads and writes experiment files.
PHENIX_LOG_LEVEL phēnix's own value, else DEBUG App log verbosity.
PHENIX_LOG_FILE stderr App logs stream back to phēnix rather than to a file.
PHENIX_DRYRUN true / false Whether the run is a dry run.
PHENIX_STORE_ENDPOINT store.endpoint Data store endpoint (user apps only).
PHENIX_SCORCH_STARTTIME run start time Scorch components only.

The rest are inherited from the phēnix process:

Environment Variable Default Description
PHENIX_TEMP_DIR /tmp/phenix App temporary directory.
MM_FILEPATH /phenix/images Base minimega file path.
MM_SOCKET_PATH /tmp/minimega/minimega minimega command socket.

miniccc (cc) Timing

Apps drive VMs over minimega's cc command-and-control channel. These bound how long an app waits, in seconds.

Environment Variable Default Description
PHENIX_CC_POLL_RATE 2.0 Interval between cc polls.
PHENIX_CC_CLIENT_GRACE 300.0 Wait for a miniccc client to register before failing.
PHENIX_CC_SEND_GRACE 300.0 Wait for a file send or component start to be acknowledged.
PHENIX_CC_CMD_GRACE 0.0 Wait for a command response. 0 waits indefinitely, supervised by client liveness instead.
PHENIX_CC_EXITCODE_GRACE 10.0 Wait for an exit code once the response is counted.
PHENIX_CC_LIVENESS_INTERVAL 10.0 Interval between client-liveness checks during an unbounded wait.
PHENIX_CC_LOG_INTERVAL 10.0 Delay before the first "still waiting" log line.
PHENIX_CC_LOG_MAX_INTERVAL 320.0 Ceiling for that interval, which doubles each time.