Skip to content

phenix experiment

Every command on this page also accepts the global flags.

phenix experiment

Experiment management

phenix experiment [flags]

Options

  -h, --help   help for experiment

SEE ALSO

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.
phenix experiment apps [flags]

Options

  -h, --help            help for apps
  -o, --output string   Output format (text, json, yaml) (default "text")

SEE ALSO

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.
phenix experiment capture [flags]

Options

  -h, --help   help for capture

SEE ALSO

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.
phenix experiment capture list <experiment name> [flags]

Options

  -h, --help   help for list

SEE ALSO

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.
phenix experiment capture start <experiment name> [flags]

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 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.
phenix experiment capture stop <experiment name> <capture ID> [flags]

Options

  -h, --help   help for stop

SEE ALSO

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.
phenix experiment captures <experiment name> [flags]

Examples

phenix experiment captures my-exp
phenix experiment captures my-exp -o json

Options

  -h, --help            help for captures
  -o, --output string   Output format (table, json, yaml) (default "table")

SEE ALSO

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}.
phenix experiment create <experiment name> [flags]

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 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.
phenix experiment delete <experiment name> [flags]

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 edit

Edit an experiment

Synopsis

Edit an experiment

  This subcommand is used to edit an experiment using your default editor.
phenix experiment edit <experiment name> [flags]

Options

      --force   override checks
  -h, --help    help for edit

SEE ALSO

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.
phenix experiment files [flags]

Options

  -h, --help   help for files

SEE ALSO

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.
phenix experiment files archive <experiment name> <file>... --output-file <zip file> [flags]

Examples

phenix experiment files archive exp1 web_eth0.pcap db_eth0.pcap -O captures.zip

Options

  -h, --help                 help for archive
  -O, --output-file string   write the zip archive to this path (required)

SEE ALSO

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.
phenix experiment files checksum <experiment name> <file> [flags]

Options

  -h, --help            help for checksum
  -o, --output string   Output format (text, json, yaml) (default "text")

SEE ALSO

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.
phenix experiment files delete <experiment name> <file>... [flags]

Options

      --dry-run   Show what the command would change, and change nothing
  -h, --help      help for delete

SEE ALSO

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.
phenix experiment files get <experiment name> <file> [flags]

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

  -h, --help                 help for get
  -O, --output-file string   write the file to this path instead of stdout

SEE ALSO

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.
phenix experiment files list <experiment name> [flags]

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 list

Display a table of available experiments

phenix experiment list [flags]

Options

  -h, --help            help for list
  -o, --output string   Output format (table, json, yaml) (default "table")

SEE ALSO

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.
phenix experiment netflow [flags]

Options

  -h, --help   help for netflow

SEE ALSO

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.
phenix experiment netflow captures <experiment name> [flags]

Options

  -h, --help            help for captures
  -o, --output string   Output format (table, json, yaml) (default "table")

SEE ALSO

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.
phenix experiment netflow download <experiment name> <capture ID> [flags]

Examples

phenix experiment netflow download exp1 20261028T153012.345Z --format csv -O flows.csv

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 start

Start the netflow capture of a running experiment

phenix experiment netflow start <experiment name> [flags]

Options

  -h, --help   help for start

SEE ALSO

phenix experiment netflow status

Tell whether the netflow capture of an experiment runs

phenix experiment netflow status <experiment name> [flags]

Options

  -h, --help            help for status
  -o, --output string   Output format (text, json, yaml) (default "text")

SEE ALSO

phenix experiment netflow stop

Stop the netflow capture of an experiment

phenix experiment netflow stop <experiment name> [flags]

Options

  -h, --help   help for stop

SEE ALSO

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.
phenix experiment reconfigure <experiment name> [flags]

Options

  -h, --help   help for reconfigure

SEE ALSO

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.
phenix experiment restart <experiment name> [flags]

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 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
phenix experiment schedule <experiment name> <algorithm> [flags]

Options

  -h, --help   help for schedule

SEE ALSO

phenix experiment schedulers

List the schedulers that put the VMs of an experiment on cluster hosts

phenix experiment schedulers [flags]

Options

  -h, --help            help for schedulers
  -o, --output string   Output format (text, json, yaml) (default "text")

SEE ALSO

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.
phenix experiment scorch <experiment name> [flags]

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 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.
phenix experiment soh [<experiment name>] [flags]

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 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.
phenix experiment start <experiment name> [flags]

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 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.
phenix experiment stop <experiment name> [flags]

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 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).
phenix experiment trigger <experiment name> <lifecycle> [<app name> ...] [flags]

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