phenix experiment¶
Every command on this page also accepts the global flags.
phenix experiment¶
Experiment management
Options¶
SEE ALSO¶
- phenix - A cli application for phēnix
- phenix experiment apps - List the apps that a scenario can add to an experiment
- phenix experiment capture - Experiment capture management
- phenix experiment captures - List the running packet captures of an experiment
- phenix experiment create - Create an experiment
- phenix experiment delete - Delete an experiment
- phenix experiment edit - Edit an experiment
- phenix experiment files - Experiment file management
- phenix experiment list - Display a table of available experiments
- phenix experiment netflow - Netflow capture management
- phenix experiment reconfigure - Reconfigure an experiment
- phenix experiment restart - Restart an experiment
- phenix experiment schedule - Schedule an experiment
- phenix experiment schedulers - List the schedulers that put the VMs of an experiment on cluster hosts
- phenix experiment scorch - Start a Scorch run for experiment
- phenix experiment soh - Show the state of health of experiments
- phenix experiment start - Start an experiment
- phenix experiment stop - Stop an experiment
- phenix experiment trigger - Trigger lifecycle stage for app(s) in experiment
phenix experiment apps¶
List the apps that a scenario can add to an experiment
Synopsis¶
List the apps that a scenario can add to an experiment
Lists the apps that phenix includes and the phenix-app-<name> executables
on this host. The default apps of each experiment are not in the list.
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment capture¶
Experiment capture management
Synopsis¶
Experiment capture management
An experiment capture records the traffic of all the VLANs, or of the given
VLANs, of a running experiment on all its hosts into one file in the
experiment's files directory. It needs minimega 3.4.0 or later on the head
node. phenix refuses a capture command when that minimega is older.
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
- phenix experiment capture list - List the experiment captures of an experiment
- phenix experiment capture start - Start an experiment capture
- phenix experiment capture stop - Stop an experiment capture
phenix experiment capture list¶
List the experiment captures of an experiment
Synopsis¶
List the experiment captures of an experiment
Prints each experiment capture with a row for each host and bridge that it
records, then the Open vSwitch mirror budget of each host and bridge that
the experiment uses.
Options¶
SEE ALSO¶
- phenix experiment capture - Experiment capture management
phenix experiment capture start¶
Start an experiment capture
Synopsis¶
Start an experiment capture
Starts one packet capture of the running experiment's traffic, on every
VLAN or on the VLANs that --vlan gives, and prints its ID, its file and the
Open vSwitch mirror budget warnings. phenix refuses the start when a host
and bridge that the capture needs has 32 mirrors.
Examples¶
phenix experiment capture start exp1
phenix experiment capture start exp1 --vlan EXP_1 --vlan EXP_2 --filter "tcp port 502" --format pcap
Options¶
--filter string BPF filter of the frames to capture
--format string capture file format, pcapng or pcap (default "pcapng")
-h, --help help for start
--name string file name in the experiment's files directory (default <exp>[-<vlan>]-<time>)
--snaplen int most bytes of each frame to keep, from 14 to 65535 (0 keeps 1600)
--vlan stringArray VLAN alias to capture (repeat for more; all VLANs when not given)
SEE ALSO¶
- phenix experiment capture - Experiment capture management
phenix experiment capture stop¶
Stop an experiment capture
Synopsis¶
Stop an experiment capture
Stops the experiment capture and prints its final counters. Its file stays
in the experiment's files directory.
Options¶
SEE ALSO¶
- phenix experiment capture - Experiment capture management
phenix experiment captures¶
List the running packet captures of an experiment
Synopsis¶
List the running packet captures of an experiment
Prints the VM, the interface index and the file of each running packet
capture of the experiment, as phenix vm capture list <experiment name>
does. A stopped experiment has no captures.
Examples¶
Options¶
-h, --help help for captures
-o, --output string Output format (table, json, yaml) (default "table")
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment create¶
Create an experiment
Synopsis¶
Create an experiment
Used to create an experiment from existing configurations; can be a
topology, or topology and scenario, or paths to topology/scenario
configuration files (YAML or JSON). (Optional are the arguments for
scenario or base directory.)
The command fills in the ${NAME} and ${NAME:default} placeholders of each
file before it reads the file. A value comes from -e, else from an env
file of --env-file, else from the shell. The shell gives no PHENIX_
variable unless -e NAME names it. A placeholder with no value and no
default is an error, and so is a -e variable that no file uses: the
command then changes nothing. Write ${NAME:} for an optional variable and
$${NAME} for the literal text ${NAME}.
Examples¶
phenix experiment create <experiment name> -t <topology name or /path/to/filename>
phenix experiment create <experiment name> -t <topology name or /path/to/filename> -s <scenario name or /path/to/filename>
phenix experiment create <experiment name> -t <topology name or /path/to/filename> -s <scenario name or /path/to/filename> -d </path/to/dir/>
phenix experiment create <experiment name> -t <topology name or /path/to/filename> -s <scenario name or /path/to/filename> --disabled-apps "app1,app2"
phenix experiment create <experiment name> -t <topology name> --node-annotation phenix/default-apps=false --annotation phenix.workflow/tags=nightly
phenix experiment create <experiment name> -t </path/to/filename> -e NODES=3 --env-file site.env
Options¶
--annotation stringArray Experiment annotation as key=value; may be repeated
-d, --base-dir string Base directory to use for experiment (optional)
-b, --default-bridge string Default bridge name to use for experiment (optional) (default "phenix")
--disabled-apps strings Comma separated list of apps to disable
-e, --env stringArray set a variable for the ${NAME} placeholders: NAME=value, or NAME to copy the value from the shell (repeatable)
--env-file stringArray read variables from an env file of NAME=value lines; a relative path starts at the working directory (repeatable)
-h, --help help for create
--node-annotation stringArray Annotation for every VM as key=value; true, false and JSON lists or objects keep their type; may be repeated
-s, --scenario string Name of an existing scenario to use (optional)
-t, --topology string Name of an existing topology to use
--vlan-max int VLAN pool maximum
--vlan-min int VLAN pool minimum
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment delete¶
Delete an experiment
Synopsis¶
Delete an experiment
Used to delete an existing experiment; experiment must be stopped.
Using 'all' instead of a specific experiment name will include all
stopped experiments. Use the -f/--force flag to automatically stop
a running experiment before deleting it.
When phenix cannot stop or delete an experiment, it continues with the
other experiments. Then it exits with an error that names each failure.
With --dry-run, phenix shows the experiments that it would stop and
delete, and changes nothing.
Options¶
--dry-run Show what the command would change, and change nothing
-f, --force Stop a running experiment before deleting it
-h, --help help for delete
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment edit¶
Edit an experiment
Synopsis¶
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment files¶
Experiment file management
Synopsis¶
Experiment file management
Lists, gets, archives and deletes the files of an experiment, as the Files
tab of the experiment page does: captures, VM snapshots and the files that
apps and VMs write. A file is its path relative to the experiment's files
directory, as phenix experiment files list shows it. A file that only a
mesh node has is first copied to the head node.
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
- phenix experiment files archive - Write experiment files to a local zip archive
- phenix experiment files checksum - Print the SHA-256 checksum of an experiment file
- phenix experiment files delete - Delete experiment files from every node
- phenix experiment files get - Write an experiment file to stdout or to a local file
- phenix experiment files list - Display a table of the files of an experiment
phenix experiment files archive¶
Write experiment files to a local zip archive
Synopsis¶
Write experiment files to a local zip archive
Archives the files as the Files tab's archive does, with the same limits:
at most 500 files and 2 GiB in total. A file that phenix cannot add is
left out, and the MISSING.txt entry of the archive names it with the
reason; the command then fails after it writes the archive.
Examples¶
Options¶
SEE ALSO¶
- phenix experiment files - Experiment file management
phenix experiment files checksum¶
Print the SHA-256 checksum of an experiment file
Synopsis¶
Print the SHA-256 checksum of an experiment file
The text output has the format of sha256sum: the checksum, two spaces and
the file's path relative to the experiment's files directory. The JSON and
YAML output also give the size and the time of the last change.
Options¶
SEE ALSO¶
- phenix experiment files - Experiment file management
phenix experiment files delete¶
Delete experiment files from every node
Synopsis¶
Delete experiment files from every node
Deletes each file from the head node and from every mesh node that has it.
Refuses a file that is not in the list of the experiment's files, and a
packet capture that minimega still writes. The command deletes the files it
can, names each file it does not delete with the reason, and then fails.
With --dry-run, phenix checks each file as for a delete, shows the files
that it would delete, and deletes nothing.
Options¶
SEE ALSO¶
- phenix experiment files - Experiment file management
phenix experiment files get¶
Write an experiment file to stdout or to a local file
Synopsis¶
Write an experiment file to stdout or to a local file
Refuses a packet capture that minimega still writes: stop the capture
first. With --output-file, phenix writes the file next to the given path
first, and replaces the given path only when the copy is complete.
Without --output-file, phenix does not write a binary file, such as a
packet capture, to a terminal.
Examples¶
# Copy a capture from a sub folder to the current folder
phenix experiment files get exp1 captures/web_eth0.pcap -O web_eth0.pcap
Options¶
SEE ALSO¶
- phenix experiment files - Experiment file management
phenix experiment files list¶
Display a table of the files of an experiment
Synopsis¶
Display a table of the files of an experiment
--filter takes the search syntax of the Files tab: words match the file
name, and "and", "or", "not" and parentheses join them. Comparisons such as
"size > 10mb" and "date >= 2026-01-01" and the categories packet, elf and
vm also select files.
Examples¶
# The packet captures larger than 1 MB
phenix experiment files list exp1 --filter "packet and size > 1mb"
Options¶
--filter string only the files that this search filter selects
-h, --help help for list
-o, --output string Output format (table, json, yaml) (default "table")
SEE ALSO¶
- phenix experiment files - Experiment file management
phenix experiment list¶
Display a table of available experiments
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment netflow¶
Netflow capture management
Synopsis¶
Netflow capture management
Starts, stops and checks the netflow capture of a running experiment, and
lists and downloads its recorded captures, as the Netflow tab of the
experiment page does. The capture runs in the phenix ui server, so these
commands call that server over its unix socket (--unix-socket), which acts
as Global Admin. The server records each capture up to the size that
ui.netflow.max-size sets.
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
- phenix experiment netflow captures - Display a table of the recorded netflow captures of an experiment
- phenix experiment netflow download - Write a recorded netflow capture to stdout or to a local file
- phenix experiment netflow start - Start the netflow capture of a running experiment
- phenix experiment netflow status - Tell whether the netflow capture of an experiment runs
- phenix experiment netflow stop - Stop the netflow capture of an experiment
phenix experiment netflow captures¶
Display a table of the recorded netflow captures of an experiment
Synopsis¶
Display a table of the recorded netflow captures of an experiment
Give the ID of a capture to phenix experiment netflow download. A capture
that the server did not finish has the state interrupted.
Options¶
-h, --help help for captures
-o, --output string Output format (table, json, yaml) (default "table")
SEE ALSO¶
- phenix experiment netflow - Netflow capture management
phenix experiment netflow download¶
Write a recorded netflow capture to stdout or to a local file
Synopsis¶
Write a recorded netflow capture to stdout or to a local file
--format text writes the lines as minimega sent them. csv and jsonl convert
each flow, and skip lines that do not parse. A capture that still records
is written as it was when the download started.
Examples¶
Options¶
--format string format to write (text, csv, jsonl) (default "text")
-h, --help help for download
-O, --output-file string write the capture to this path instead of stdout
SEE ALSO¶
- phenix experiment netflow - Netflow capture management
phenix experiment netflow start¶
Start the netflow capture of a running experiment
Options¶
SEE ALSO¶
- phenix experiment netflow - Netflow capture management
phenix experiment netflow status¶
Tell whether the netflow capture of an experiment runs
Options¶
SEE ALSO¶
- phenix experiment netflow - Netflow capture management
phenix experiment netflow stop¶
Stop the netflow capture of an experiment
Options¶
SEE ALSO¶
- phenix experiment netflow - Netflow capture management
phenix experiment reconfigure¶
Reconfigure an experiment
Synopsis¶
Reconfigure an experiment
Used to rerun the 'configure' stage of all the apps (both default and user)
for the given experiment (as long as it's not running). Using 'all' instead
of a specific experiment name will reconfigure all non-running
experiments.
This differs from 'phenix experiment trigger <experiment name> configure'
in that it re-runs config validation and any registered config hooks, and
always applies to all apps. Use this after editing an experiment's stored
topology, scenario, or deployment settings. Use 'trigger configure' to
manually re-run a specific app's (or apps') configure hook on demand for
debugging; note it does not validate the config, run config hooks, or
guard against running experiments the way 'reconfigure' does.
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment restart¶
Restart an experiment
Synopsis¶
Restart an experiment
Used to restart a running experiment, using 'all' instead of a specific
experiment name will include all running experiments; dry-run will do
everything but call out to minimega.
Before phenix stops the experiment, it checks the disk images and CD-ROM
images of the VMs as 'phenix experiment start' does. A missing file
refuses the restart, and the experiment continues to run. When the
scenario has a user app, the app can change the disks, so this check
only shows warnings, and the check before the start can still refuse it.
The stop of the experiment takes the flags of 'phenix experiment stop'
(--force and --keep-injection-snapshots), and its start takes the flags
of 'phenix experiment start'. With --treat-mm-errors-as-warnings, the
check before the stop shows the problems as warnings.
NOTE: passing the --honor-run-periodically flag will prevent the CLI from
returning. If Ctrl+c is pressed, the experiment will continue to run but
the running stage will no longer continue to be triggered for any apps
configured (via the scenario) to have their running stage triggered
periodically.
Options¶
--dry-run Do everything but actually call out to minimega
-f, --force Mark the experiment stopped even if minimega cannot kill its VMs
-h, --help help for restart
--honor-run-periodically Periodically trigger running stage in apps if configured in scenario
-K, --keep-injection-snapshots Keep VM injection snapshots after stopping
--treat-mm-errors-as-warnings Treat errors from minimega as warnings instead of failing
--vlan-max int VLAN pool maximum for this start (1-4094; 0 keeps the maximum of the experiment)
--vlan-min int VLAN pool minimum for this start (1-4094; 0 keeps the minimum of the experiment)
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment schedule¶
Schedule an experiment
Synopsis¶
Schedule an experiment
Apply an algorithm to a given experiment. Run 'phenix experiment schedulers'
to return a list of algorithms
Options¶
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment schedulers¶
List the schedulers that put the VMs of an experiment on cluster hosts
Options¶
-h, --help help for schedulers
-o, --output string Output format (text, json, yaml) (default "text")
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment scorch¶
Start a Scorch run for experiment
Synopsis¶
Start a Scorch run for an experiment
Used to start the Scorch run that --run selects (0 when not given) for the
given experiment, and to wait until it ends. The command prints the
progress of the run, and exits with an error when the run fails.
When phenix ui is running, the server executes the run, so the web UI
shows it and can cancel it. Ctrl+C cancels the run on the server. When
phenix ui is not running, this command executes the run in its own
process. The web UI does not show that run.
The --status, --cancel, --cleanup and --clear flags need phenix ui. Each
acts on the run that --run selects, and only one can be given:
--status shows the status of each stage and component of the run
--cancel cancels the run on the server
--cleanup runs only the cleanup stage of the run, and waits for it
--clear clears the status of a run that is not executing
-o/--output sets the output format of --status. With --cancel or --clear,
--dry-run checks that the server has the run, shows what phenix would
request, and requests nothing.
Examples¶
# Run Scorch run 1 and wait until it ends
phenix experiment scorch exp1 --run 1
# Show the status of Scorch run 1
phenix experiment scorch exp1 --run 1 --status
# Cancel Scorch run 1 on the server
phenix experiment scorch exp1 --run 1 --cancel
# The status of Scorch run 1 as JSON
phenix experiment scorch exp1 --run 1 --status -o json
Options¶
--cancel Cancel the run on the server (needs phenix ui)
--cleanup Run only the cleanup stage of the run (needs phenix ui)
--clear Clear the status of the run (needs phenix ui)
--dry-run Show what the command would change, and change nothing
-h, --help help for scorch
-o, --output string Output format (text, json, yaml) (default "text")
-r, --run int ID of the Scorch run to act on (defaults to 0)
--status Show the status of the run (needs phenix ui)
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment soh¶
Show the state of health of experiments
Synopsis¶
Show the state of health of experiments
Without an experiment, shows a summary of each experiment on one row, as
the State of Health page does: the state of the soh app, the running VMs,
and the checks that passed in its latest run. With an experiment, shows
each of its VMs with its status and failing checks, then the failing
checks of the latest run. --status shows only the VMs with that status.
Examples¶
# The VMs of exp1 that do not run
phenix experiment soh exp1 --status notrunning
# The summary of each experiment as JSON
phenix experiment soh -o json
Options¶
-h, --help help for soh
-o, --output string Output format (table, json, yaml) (default "table")
--status string only the VMs with this status (running, notrunning, notboot, notdeploy, external)
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment start¶
Start an experiment
Synopsis¶
Start an experiment
Used to start a stopped experiment, using 'all' instead of a specific
experiment name will include all stopped experiments; dry-run will do
everything but call out to minimega.
Before minimega launches a VM, phenix checks that each disk image and
CD-ROM image of the VMs exists, and that the backing chain of each disk
image is complete. A missing file refuses the start and lists each VM,
disk and missing file. With --dry-run or --treat-mm-errors-as-warnings,
phenix shows the problems as warnings. The experiment.disk-check setting
changes this for every start: warn shows the problems as warnings, and
off skips the check.
NOTE: passing the --honor-run-periodically flag will prevent the CLI from
returning. If Ctrl+c is pressed, the experiment will continue to run but
the running stage will no longer continue to be triggered for any apps
configured (via the scenario) to have their running stage triggered
periodically.
Options¶
--dry-run Do everything but actually call out to minimega
-h, --help help for start
--honor-run-periodically Periodically trigger running stage in apps if configured in scenario
--treat-mm-errors-as-warnings Treat errors from minimega as warnings instead of failing
--vlan-max int VLAN pool maximum for this start (1-4094; 0 keeps the maximum of the experiment)
--vlan-min int VLAN pool minimum for this start (1-4094; 0 keeps the minimum of the experiment)
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment stop¶
Stop an experiment
Synopsis¶
Stop an experiment
Used to stop a running experiment, using 'all' instead of a specific
experiment name will include all running experiments. An experiment whose
VMs minimega cannot kill stays running; --force marks it stopped anyway.
Options¶
-f, --force Mark the experiment stopped even if minimega cannot kill its VMs
-h, --help help for stop
-K, --keep-injection-snapshots Keep VM injection snapshots after stopping
SEE ALSO¶
- phenix experiment - Experiment management
phenix experiment trigger¶
Trigger lifecycle stage for app(s) in experiment
Synopsis¶
Trigger an app lifecycle stage in an experiment
Used to manually trigger the "configure", "pre-start", "post-start", "running",
or "cleanup" stage of an app (or apps) for the given experiment on demand.
Using 'all' instead of a specific experiment name triggers the stage for the
given app(s) in all experiments. Providing no apps triggers the stage for all
apps in the experiment(s). The "running" stage is skipped for stopped
experiments.
Triggering the "configure" stage is not the same as
'phenix experiment reconfigure': this command does not validate the
experiment config, run config hooks, or guard against running
experiments. Use 'phenix experiment reconfigure' after
editing an experiment's stored topology, scenario, or deployment settings.
This command runs the stage in its own process. Ctrl+C stops a trigger
that this command runs. --cancel stops the triggers that phenix ui runs,
which the web UI or the REST API started: give no lifecycle with it, and
give app names to stop only those apps. Without app names, --cancel also
ends the scheduled runs of the running stage that phenix ui runs after a
start (the experiments.periodic job). --cancel needs phenix ui. With
--cancel --dry-run, phenix shows the cancels that it would request, and
requests none.
The old argument order, <lifecycle> <experiment name> [<app name> ...],
is deprecated. It still works, with a warning, when no experiment has the
lifecycle as its name.
Valid lifecycles and shorthands: configure (config), pre-start (pre), post-start (post), running (run), cleanup (clean).
Examples¶
# Run the configure stage of every app of exp1
phenix experiment trigger exp1 configure
# Run the running stage of the soh app in every experiment
phenix experiment trigger all running soh
# Stop the soh trigger that phenix ui runs for exp1
phenix experiment trigger exp1 --cancel soh
Options¶
--cancel Stop the triggers that phenix ui runs for the experiment (needs phenix ui)
--dry-run Show what the command would change, and change nothing
-h, --help help for trigger
SEE ALSO¶
- phenix experiment - Experiment management