Settings & Configuration

phēnix supports dynamic configuration management via the phenix settings command. Changes made via this command are applied immediately (hot-swapped) without restarting the service.

Configuration Files

phēnix looks for a configuration file (e.g. config.yaml, config.json, config.toml) in the following locations:

When run as root: * /etc/phenix/config.yaml

When run as a regular user: * $HOME/.config/phenix/config.yaml * /etc/phenix/config.yaml

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/etcd): 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 key-value data store. By default it uses bbolt but also supports etcd.

• bbolt (Default): No external dependencies, but only accessible on a single machine.
• etcd: Allows running phenix on multiple machines accessing the same data, but requires an external etcd service.

To use etcd, configure the store endpoint (e.g. etcd://localhost:2379) via the config file or phenix settings set.

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

Configuration Precedence

phēnix resolves configuration settings 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. Config File: Settings defined in config.yaml (managed via phenix settings set).
3. Environment Variables: Variables like PHENIX_LOG_LEVEL.
4. Defaults: Internal application defaults.

Settings Reference

Setting Key	Environment Variable	Default	Description
log.level	PHENIX_LOG_LEVEL	info	Global log verbosity (debug, info, warn, error).
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).
ui.logs.minimega-path	PHENIX_UI_LOGS_MINIMEGA_PATH	""	Path to the minimega log file to display in the UI. (Restart Required)
ui.features	PHENIX_UI_FEATURES	""	Comma-separated list of optional UI features to enable. Currently supports vm-mount, which enables transferring files to and from a running VM. See Mount a VM. (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. (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.
Warning before logout (minutes)	3	How long before logout to warn the user.

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.