Configuration File Schemas¶
The following schemas are all represented using the OpenAPIv3 format. There
is one schema file for each config apiVersion, and it holds the schemas of the
kinds stored at that version. phēnix validates each config against the file of
its own apiVersion:
apiVersion |
Schema file | Kinds |
|---|---|---|
phenix.sandia.gov/v0 |
v0.yaml |
Workflow |
phenix.sandia.gov/v1 |
v1.yaml |
Topology, Experiment, Image, User, Role |
phenix.sandia.gov/v2 |
v2.yaml |
Scenario |
A config whose kind is not in the file of its apiVersion, such as a
phenix.sandia.gov/v2 Topology, is rejected. A running phēnix server serves
each file at GET /api/v1/schemas/{version}, and the schema of one kind at
GET /api/v1/schemas/{kind}/{version}. The complete files are shown
below.
Topology Schema¶
The topology schema is largely comprised of nodes, described
here. A topology needs nodes, the includeTopologies key
described in Configuration Files, or both.
Topology:
title: "Topology"
description: "Schema describing the Topology resource."
type: object
anyOf:
- required:
- nodes
- required:
- includeTopologies
properties:
includeTopologies:
title: "Included Topologies"
description: >-
Topology configs or file paths to merge into this topology. A
single value is the same as a list of one value.
nullable: true
anyOf:
- type: array
items:
type: string
- type: string
example:
- /phenix/topologies/common.yml
- shared-topology
nodes:
title: "Nodes"
description: "Nodes that make up the topology."
type: array
items:
oneOf:
- $ref: '#/components/schemas/minimega_node'
- $ref: '#/components/schemas/external_node'
Scenario Schema¶
Scenario:
title: "Scenario"
description: "Schema describing the Scenario resource."
type: object
nullable: true
required:
- apps
properties:
apps:
title: "Apps"
description: "Applications configured for this scenario."
type: array
nullable: true
items:
type: object
required:
- name
properties:
name:
title: "Name"
description: "Name used to identify this resource or entry."
type: string
example: example-app
assetDir:
title: "Asset Directory"
description: "Directory containing assets made available to the application."
type: string
example: /phenix/topologies/example-topo/assets
metadata:
title: "Metadata"
description: "Application-specific settings shared across its hosts."
type: object
nullable: true
additionalProperties: true
example:
setting0: true
setting1: 42
setting2: universe key
runPeriodically:
title: "Run Periodically"
description: "Interval at which the application running stage repeats."
type: string
example: 30s
disabled:
title: "Disabled"
description: "Whether to skip this application."
type: boolean
default: false
example: false
nullable: true
fromScenario:
title: "From Scenario"
description: "Scenario inherited by this application configuration."
type: string
example: base-scenario
hosts:
title: "Hosts"
description: "Host-specific application settings."
type: array
items:
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: "Hostname used to identify the node."
type: string
example: example-host
metadata:
title: "Metadata"
description: "Application-specific settings for this host."
type: object
nullable: true
additionalProperties: true
example:
setting0: true
setting1: 42
setting2: universe key
Experiment Schema¶
The scenario an experiment embeds uses the experiment_scenario schema in
v1.yaml, a copy of the Scenario schema.
Experiment:
title: "Experiment"
description: "Schema describing the Experiment resource."
type: object
required:
- topology
properties:
topology:
title: "Topology"
description: "Topology configuration embedded in or referenced by this resource."
allOf:
- $ref: "#/components/schemas/Topology"
scenario:
$ref: "#/components/schemas/experiment_scenario"
baseDir:
title: "Base Dir"
description: "Working directory used by the experiment."
type: string
example: /phenix/topologies/example-topo
experimentName:
title: "Experiment Name"
description: "Name of the experiment."
type: string
example: example-exp
readOnly: true
vlans:
title: "VLANs"
description: "VLAN IDs and aliases allocated to the experiment."
type: object
nullable: true
properties:
aliases:
title: "Aliases"
description: "Mapping from VLAN aliases to VLAN IDs."
type: object
nullable: true
additionalProperties:
type: integer
example:
MGMT: 200
min:
title: "Min"
description: "Lowest VLAN ID available to the experiment."
example: 1
type: integer
max:
title: "Max"
description: "Highest VLAN ID available to the experiment."
example: 1
type: integer
schedules:
title: "Schedules"
description: "Mapping from VM hostnames to cluster hosts."
type: object
nullable: true
additionalProperties:
type: string
example:
ADServer: compute1
defaultBridge:
title: "Default Bridge"
description: "Bridge used for experiment VM interfaces by default."
type: string
nullable: true
maxLength: 15
example: phenix
deployMode:
title: "Deploy Mode"
description: "Cluster hosts eligible to run experiment VMs."
type: string
nullable: true
enum:
- all
- no-headnode
- only-headnode
example: all
useGREMesh:
title: "Use GRE Mesh"
description: "Whether cluster hosts use a GRE mesh for this experiment."
type: boolean
nullable: true
example: false
Image Schema¶
Image:
title: "Image"
description: "Schema describing the Image resource."
type: object
required:
- format
- mirror
- release
- size
- variant
properties:
compress:
title: "Compress"
description: "Whether to compress the disk image after creating it."
type: boolean
default: false
example: false
components:
title: "Components"
description: "Distribution components from which to install packages."
type: array
nullable: true
items:
type: string
example:
- main
- restricted
kernel:
title: "Kernel"
description: "Kernel command-line arguments included in the image."
type: array
nullable: true
items:
type: string
example:
- net.ifnames=0
no_virtuals:
title: "No Virtuals"
description: "Whether to omit virtual packages when resolving packages."
type: boolean
default: false
example: false
format:
title: "Format"
description: "Format of the output disk image."
type: string
enum:
- raw
- qcow2
- vmdk
- vdi
- vhdx
example: qcow2
mirror:
title: "Mirror"
description: "URL of the distribution mirror used to build the image."
type: string
example: http://us.archive.ubuntu.com/ubuntu/
overlays:
title: "Overlays"
description: "Overlay directories applied while building the image."
type: array
nullable: true
items:
type: string
example:
- /phenix/vmdb/overlays/example-overlay
packages:
title: "Packages"
description: "Additional packages installed in the image."
type: array
nullable: true
items:
type: string
example:
- isc-dhcp-client
- openssh-server
ramdisk:
title: "Ramdisk"
description: "Whether to build a kernel and initrd alongside the disk image."
type: boolean
default: false
example: false
release:
title: "Release"
description: "Distribution release used to build the image."
type: string
example: focal
script_order:
title: "Script Order"
description: "Script names in the order they run during the image build."
type: array
nullable: true
items:
type: string
example:
- POSTBUILD_APT_CLEANUP
scripts:
title: "Scripts"
description: "Named scripts available to the image build."
type: object
nullable: true
additionalProperties:
type: string
example:
POSTBUILD_APT_CLEANUP: |
apt clean || apt-get clean || echo "unable to clean apt cache"
skip_default_packages:
title: "Skip Default Packages"
description: "Whether to omit the default packages of the image builder."
type: boolean
default: false
example: false
size:
title: "Size"
description: "Target size of the generated disk image: a positive number and M or G, such as 10G."
type: string
pattern: '^(0*[1-9][0-9]*(\.[0-9]+)?|0+\.[0-9]*[1-9][0-9]*)[MG]$'
example: 10G
variant:
title: "Variant"
description: "Distribution variant used to build the image."
type: string
example: minbase
User Schema¶
User:
title: "User"
description: "Schema describing the User resource."
type: object
required:
- first_name
- last_name
- username
properties:
first_name:
title: "First Name"
description: "Given name of the user."
type: string
example: John
last_name:
title: "Last Name"
description: "Family name of the user."
type: string
example: Doe
password:
title: "Password"
description: "Password supplied for account creation or sign-in."
type: string
example: '<encrypted password>'
readOnly: true
rbac:
title: "RBAC"
description: "Role-based access control settings assigned to this user."
allOf:
- $ref: "#/components/schemas/Role"
readOnly: true
username:
title: "Username"
description: "Username used to identify the account."
type: string
example: johndoe@example.com
Role Schema¶
Role:
title: "Role"
description: "Schema describing the Role resource."
type: object
required:
- policies
- roleName
properties:
policies:
title: "Policies"
description: "Access policies assigned to this role."
type: array
items:
type: object
properties:
resources:
title: "Resources"
description: "Resource types covered by this policy."
type: array
items:
type: string
resourceNames:
title: "Resource Names"
description: "Resource names covered by this policy."
type: array
items:
type: string
verbs:
title: "Verbs"
description: "Actions allowed on the listed resources."
type: array
items:
type: string
example:
- resources:
- experiments
- experiments/*
resourceNames:
- '*'
verbs:
- list
- get
roleName:
title: "Role Name"
description: "Name assigned to this role."
type: string
example: Example Role
Workflow Schema¶
The workflow config (phenix.yml) is validated against the Workflow schema
in schema version v0. It is documented, with every field, in
Workflow.
Node Schemas¶
minimega_node Schema¶
The minimega_node schema contains references to the interface schema described
here.
minimega_node:
title: "Minimega Node"
description: "Schema describing the Minimega Node resource."
type: object
required:
- type
- general
- hardware
properties:
type:
title: "Type"
description: >-
What the node is. phenix configures Router and Firewall nodes whose OS type is vyatta, vyos or minirouter as
routers, from their interfaces, routes, OSPF settings and rulesets.
type: string
enum:
- VirtualMachine
- Firewall
- Router
- Switch
default: VirtualMachine
example: VirtualMachine
annotations:
title: "Annotations"
description: "Free-form annotations associated with this node."
type: object
nullable: true
additionalProperties: true
example:
app: web
labels:
title: "Labels"
description: "String labels used to select or group nodes."
type: object
nullable: true
additionalProperties:
type: string
example:
tier: frontend
general:
title: "General"
description: "General node settings."
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: >-
Name of the VM in minimega and the host name set in the guest.
The name is unique in the topology.
# 2 to 63 letters, digits, and interior hyphens. Guest operating
# systems phenix configures reject 1-character hostnames.
#
# VyOS and Vyatta validate `system host-name` against
# `[A-Za-z0-9][-.A-Za-z0-9]*[A-Za-z0-9]`, which needs at least 2
# characters:
# https://docs.vyos.io/en/latest/configuration/system/host-name.html
# https://github.com/vyos/vyos-1x/blob/ed218c254d964775ddf24158ac6520972d575faf/interface-definitions/include/constraint/host-name.xml.i
#
# Windows DNS host names have a 2-character minimum:
# https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/naming-conventions-for-computer-domain-site-ou#dns-host-names
type: string
minLength: 2
maxLength: 63
pattern: '^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$'
example: ADServer
description:
title: "Description"
description: 'Free-text notes about the node.'
type: string
example: Active Directory Server
vm_type:
title: "VM Type"
description: >-
How minimega runs the node: kvm for a QEMU/KVM virtual machine, or container. Empty means kvm.
type: string
enum:
- kvm
- container
- ""
default: kvm
example: kvm
snapshot:
title: "Snapshot"
description: >-
Run the VM on a copy-on-write snapshot of its first drive, which phenix creates for the experiment and
injects files into, so the image file itself does not change. phenix turns this on when it is not set.
type: boolean
default: true
example: true
nullable: true
do_not_boot:
title: "Do Not Boot"
description: >-
Leave the node out when the experiment starts: phenix neither creates nor starts its VM. phenix also
sets this when the first drive's image is missing.
type: boolean
default: false
example: false
nullable: true
hardware:
title: "Hardware"
description: "Virtual hardware assigned to the node."
type: object
required:
- os_type
- drives
properties:
cpu:
title: "CPU"
description: 'QEMU CPU model for the VM, such as Broadwell or host.'
type: string
default: Broadwell
example: Broadwell
vcpus:
title: "Virtual CPUs"
description: 'Number of virtual CPUs. phenix uses 1 when it is not set.'
oneOf:
- type: integer
- type: string
default: 1
example: 4
memory:
title: "Memory"
description: 'Memory for the VM, in megabytes. phenix uses 512 when it is not set.'
oneOf:
- type: integer
- type: string
default: 512
example: 8192
os_type:
title: "OS Type"
description: >-
Operating system in the disk image. phenix and its apps choose startup scripts and router configuration
by it.
type: string
enum:
- centos
- linux
- minirouter
- rhel
- vyatta
- vyos
- windows
- other
default: linux
example: windows
drives:
title: "Drives"
description: >-
Disks attached to the VM, in order. The first is the one phenix snapshots and injects files into.
type: array
minItems: 1
items:
type: object
required:
- image
properties:
image:
title: "Image"
description: >-
Disk image file: a name in the phenix image directory, or an absolute path on the host.
type: string
minLength: 1
example: ubuntu.qc2
interface:
title: "Interface"
description: >-
Bus the disk is attached to, such as ide, scsi or virtio. Empty uses minimega's default.
type: string
enum:
- ahci
- ide
- scsi
- sd
- mtd
- floppy
- pflash
- virtio
- ""
default: ide
example: ide
cache_mode:
title: "Cache Mode"
description: >-
QEMU cache mode for the disk. Empty uses writeback for a snapshot, and QEMU's default otherwise.
type: string
enum:
- none
- writeback
- unsafe
- directsync
- writethrough
- ""
default: writeback
example: writeback
inject_partition:
title: "Inject Partition"
description: >-
Partition of the first drive that phenix injects files into. 0 skips disk injection, and phenix
sends its startup scripts through minimega command and control instead. phenix uses 1 when it is
not set.
type: integer
default: 1
example: 2
nullable: true
network:
title: "Network"
description: "Network settings associated with this node."
type: object
nullable: true
required:
- interfaces
properties:
interfaces:
title: "Interfaces"
description: 'Network interfaces, in the order the guest sees them.'
type: array
nullable: true
items:
type: object
oneOf:
- $ref: '#/components/schemas/static_iface'
- $ref: '#/components/schemas/dhcp_iface'
- $ref: '#/components/schemas/serial_iface'
routes:
title: "Routes"
description: 'Static routes phenix configures in the guest.'
type: array
nullable: true
items:
type: object
required:
- destination
- next
properties:
destination:
title: "Destination"
description: 'Network to reach, in CIDR notation such as 192.168.0.0/24.'
type: string
example: 192.168.0.0/24
next:
title: "Next"
description: 'Address of the next hop toward the destination.'
type: string
example: 192.168.1.254
cost:
title: "Cost"
description: 'Route cost, set as the administrative distance on Vyatta and VyOS routers.'
type: integer
default: 1
example: 1
nullable: true
ospf:
title: "OSPF"
description: "Open Shortest Path First routing settings."
type: object
nullable: true
required:
- router_id
- areas
properties:
router_id:
title: "Router Id"
description: 'OSPF router ID, written like an IPv4 address, such as 0.0.0.1.'
type: string
example: 0.0.0.1
areas:
title: "Areas"
description: 'OSPF areas the router takes part in.'
type: array
items:
type: object
required:
- area_id
- area_networks
properties:
area_id:
title: "Area Id"
description: 'OSPF area number. 0 is the backbone area.'
type: integer
example: 1
default: 1
area_networks:
title: "Area Networks"
description: 'Networks the router advertises in the area.'
type: array
items:
type: object
required:
- network
properties:
network:
title: "Network"
description: 'Network in CIDR notation, such as 10.1.25.0/24.'
type: string
example: 10.1.25.0/24
dead_interval:
title: "Dead Interval"
description: >-
Seconds without a hello from a neighbor before the router considers it down. Applies to interfaces
whose protocol is ospf.
type: integer
nullable: true
example: 40
hello_interval:
title: "Hello Interval"
description: 'Seconds between OSPF hello packets. Applies to interfaces whose protocol is ospf.'
type: integer
nullable: true
example: 10
retransmission_interval:
title: "Retransmission Interval"
description: >-
Seconds before the router resends a link-state advertisement that was not acknowledged. Applies to
interfaces whose protocol is ospf.
type: integer
nullable: true
example: 5
rulesets:
title: "Rulesets"
description: >-
Firewall rulesets for Router and Firewall nodes. An interface applies one by naming it as its inbound or
outbound ruleset.
type: array
nullable: true
items:
type: object
required:
- name
- default
- rules
properties:
name:
title: "Name"
description: 'Name interfaces use to apply the ruleset.'
type: string
example: OutToDMZ
description:
title: "Description"
description: 'Describes the ruleset in the router configuration.'
type: string
example: From Corp to the DMZ network
default:
title: "Default"
description: 'What happens to traffic that no rule matches.'
type: string
enum:
- accept
- drop
- reject
example: drop
rules:
title: "Rules"
description: 'Rules of the ruleset.'
type: array
items:
type: object
required:
- id
- action
- protocol
properties:
id:
title: "Id"
description: >-
Rule number, unique in the ruleset. Vyatta and VyOS routers check rules from the lowest
number up.
type: integer
example: 10
description:
title: "Description"
description: 'Describes the rule in the router configuration.'
type: string
example: Allow UDP 10.1.26.80 ==> 10.2.25.0/24:123
action:
title: "Action"
description: 'What happens to traffic the rule matches.'
type: string
enum:
- accept
- drop
- reject
example: accept
protocol:
title: "Protocol"
description: 'Protocol of the traffic the rule matches.'
type: string
enum:
- tcp
- udp
- tcp_udp
- icmp
- esp
- ah
- all
default: tcp
example: tcp
source:
title: "Source"
description: "Source address and optional port matched by this rule."
type: object
nullable: true
required:
- address
properties:
address:
title: "Address"
description: 'Source address or network the rule matches.'
type: string
example: 10.1.24.60
port:
title: "Port"
description: 'Source port the rule matches. Empty or 0 matches any port.'
type: integer
example: 3389
destination:
title: "Destination"
description: "Destination network or address for this route or rule."
type: object
nullable: true
required:
- address
properties:
address:
title: "Address"
description: 'Destination address or network the rule matches.'
type: string
example: 10.1.24.60
port:
title: "Port"
description: 'Destination port the rule matches. Empty or 0 matches any port.'
type: integer
example: 3389
stateful:
title: "Stateful"
description: "Whether the firewall rule tracks connection state."
type: boolean
example: true
nat:
title: "Nat"
description: "Mappings for network address translation on this node."
type: array
nullable: true
items:
type: object
properties:
in:
title: "In"
description: "Names of the internal interfaces whose networks this NAT rule maps."
type: array
items:
type: string
example:
- eth1
out:
title: "Out"
description: "External interface used by this NAT rule."
type: string
example: eth0
injections:
title: "Injections"
description: 'Files phenix copies into the snapshot of the first drive before the VM starts.'
type: array
nullable: true
items:
type: object
required:
- src
- dst
properties:
src:
title: "Source"
description: >-
File on the phenix host: an absolute path, or a path relative to the experiment directory.
type: string
example: foo.xml
dst:
title: "Destination"
description: 'Path the file is written to in the guest.'
type: string
example: /etc/phenix/foo.xml
description:
title: "Description"
description: 'Free-text notes about the file.'
type: string
example: phenix config file
permissions:
title: "Permissions"
description: 'File mode for the copied file, in octal such as 0664.'
type: string
example: '0664'
deletions:
title: "Deletions"
description: "Files to remove from the node disk before boot."
type: array
nullable: true
items:
type: object
required:
- path
properties:
path:
title: "Path"
description: "Path to remove from the node disk."
type: string
minLength: 1
example: /etc/obsolete.conf
description:
title: "Description"
description: "Human-readable description of this resource or entry."
type: string
example: Remove the obsolete configuration file
overrides:
title: "Overrides"
description: "Minimega VM settings overridden for this node."
type: object
nullable: true
additionalProperties:
type: string
example:
memory: "4096"
delay:
title: "Delay"
description: "Conditions that delay the node start."
type: object
nullable: true
properties:
timer:
title: "Timer"
description: 'Start the VM this long after the experiment starts, as a duration such as 30s or 5m.'
type: string
pattern: '^$|^[-+]?(0|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$'
example: 5m
user:
title: "User"
description: >-
Leave the VM stopped until someone starts it from phenix or minimega. Takes precedence over the other
delays.
example: false
type: boolean
c2:
title: "C2"
description: 'Start the VM once each of these hosts has checked in with minimega command and control.'
type: array
nullable: true
items:
type: object
properties:
hostname:
title: "Hostname"
description: 'Host to wait for.'
example: node-01
type: string
useUUID:
title: "Use UUID"
description: 'Wait for the host''s UUID, rather than its hostname, to check in.'
example: false
type: boolean
advanced:
title: "Advanced"
description: 'Extra minimega vm config settings, each a setting name and its value.'
type: object
nullable: true
additionalProperties:
type: string
example:
rtc.utc: "true"
commands:
title: "Commands"
description: 'minimega command and control (cc) commands phenix sends to the VM, such as exec df -h.'
type: array
nullable: true
items:
type: string
example:
- exec df -h
external_node Schema¶
external_node:
title: "External Node"
description: "Schema describing the External Node resource."
type: object
required:
- external
- type
- general
properties:
external:
title: "External"
description: >-
Marks a device phenix does not deploy, such as hardware in the loop. It stays in the topology for State of
Health and apps.
example: true
type: boolean
enum:
- true
annotations:
title: "Annotations"
description: "Free-form annotations associated with this node."
type: object
nullable: true
additionalProperties: true
example:
physical: true
labels:
title: "Labels"
description: "String labels used to select or group nodes."
type: object
nullable: true
additionalProperties:
type: string
example:
tier: endpoint
type:
title: "Type"
description: 'What the device is, such as HIL for hardware in the loop.'
type: string
default: HIL
example: HIL
general:
title: "General"
description: "General node settings."
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: 'Name of the device in the topology.'
type: string
example: ADServer
description:
title: "Description"
description: 'Free-text notes about the device.'
type: string
example: Active Directory Server
vm_type:
title: "VM Type"
description: 'Whether the device is a virtual machine or a container.'
type: string
enum:
- vm
- container
- ""
default: vm
example: vm
hardware:
title: "Hardware"
description: "Virtual hardware assigned to the node."
type: object
nullable: true
required:
- os_type
properties:
cpu:
title: "CPU"
description: 'CPU model of the device.'
type: string
default: Broadwell
example: Broadwell
vcpus:
title: "Virtual CPUs"
description: 'Number of CPUs of the device.'
oneOf:
- type: integer
- type: string
default: 1
example: 4
memory:
title: "Memory"
description: 'Memory of the device, in megabytes.'
oneOf:
- type: integer
- type: string
default: 512
example: 8192
os_type:
title: "OS Type"
description: 'Operating system of the device.'
type: string
enum:
- centos
- linux
- minirouter
- rhel
- vyatta
- vyos
- windows
- other
default: linux
example: windows
network:
title: "Network"
description: "Network settings associated with this node."
type: object
nullable: true
required:
- interfaces
properties:
interfaces:
title: "Interfaces"
description: >-
Network interfaces of the device, for the topology's network diagram and State of Health checks.
type: array
items:
type: object
required:
- name
properties:
name:
title: "Name"
description: 'Interface name, such as eth0.'
type: string
example: eth0
proto:
title: "Protocol"
description: 'How the interface gets its address: static, dhcp, or manual for none.'
type: string
enum:
- static
- dhcp
- manual
- ""
default: dhcp
example: static
address:
title: "Address"
description: 'IPv4 address of the interface.'
type: string
format: ipv4
example: 192.168.1.100
mask:
title: "Mask"
description: 'Network prefix length (CIDR bits), from 0 to 32.'
type: integer
minimum: 0
maximum: 32
default: 24
example: 24
gateway:
title: "Gateway"
description: 'Default gateway of the interface.'
type: string
format: ipv4
example: 192.168.1.1
vlan:
title: "VLAN"
description: 'VLAN (network) the interface is on.'
type: string
example: EXP-1
injections:
title: "Injections"
description: "Files to copy into the node disk before boot."
type: array
nullable: true
items:
type: object
required:
- src
- dst
properties:
src:
title: "Source"
description: "Source file copied into the node disk."
type: string
minLength: 1
example: ./config.txt
dst:
title: "Destination"
description: "Destination path for the injected file."
type: string
minLength: 1
example: /etc/config.txt
description:
title: "Description"
description: "Human-readable description of this resource or entry."
type: string
example: Inject endpoint config
permissions:
title: "Permissions"
description: "File permissions to set on the injected file."
type: string
example: '0644'
deletions:
title: "Deletions"
description: "Files to remove from the node disk before boot."
type: array
nullable: true
items:
type: object
required:
- path
properties:
path:
title: "Path"
description: "Path to remove from the node disk."
type: string
minLength: 1
example: /tmp/obsolete
description:
title: "Description"
description: "Human-readable description of this resource or entry."
type: string
example: Remove obsolete endpoint file
overrides:
title: "Overrides"
description: "Minimega VM settings overridden for this node."
type: object
nullable: true
additionalProperties:
type: string
delay:
title: "Delay"
description: "Conditions that delay the node start."
type: object
nullable: true
properties:
timer:
title: "Timer"
description: "Duration to wait before starting the node, in Go duration syntax such as 5m or 1h30m."
type: string
pattern: '^$|^[-+]?(0|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$'
example: 5m
user:
title: "User"
description: "Whether node start requires user confirmation."
type: boolean
example: true
c2:
title: "C2"
description: "Command-and-control hosts whose availability can release the delay."
type: array
items:
type: object
properties:
hostname:
title: "Hostname"
description: "Hostname used to identify the node."
type: string
example: c2-server
useUUID:
title: "Use UUID"
description: "Whether to match the command-and-control host by UUID."
type: boolean
example: false
advanced:
title: "Advanced"
description: "Additional minimega VM settings."
type: object
nullable: true
additionalProperties:
type: string
commands:
title: "Commands"
description: "Minimega commands to run for this node."
type: array
nullable: true
items:
type: string
example:
- exec hostname
Interface Schema¶
iface:
title: "Interface"
description: "Schema describing the Iface resource."
type: object
required:
- name
- vlan
properties:
name:
title: "Name"
description: 'Interface name, such as eth0, which NAT settings and apps use to refer to it.'
type: string
example: eth0
vlan:
title: "VLAN"
description: 'VLAN (network) the interface is on.'
type: string
example: EXP-1
autostart:
title: "Autostart"
description: >-
Whether the interface should come up when the VM boots. phenix itself does not act on this setting.
example: true
type: boolean
default: true
mac:
title: "MAC"
description: 'MAC address. minimega generates one when it is empty.'
type: string
example: 00:11:22:33:44:55
pattern: '^$|^([0-9a-fA-F]{2}[:-]){5}([0-9a-fA-F]){2}$'
mtu:
title: "MTU"
description: >-
Maximum transmission unit, in bytes. Vyatta and VyOS routers apply values from 68 to 16000; other images
keep their own.
type: integer
default: 1500
example: 1500
bridge:
title: "Bridge"
description: >-
Open vSwitch bridge on the host the interface attaches to. Empty or phenix uses the experiment's default
bridge.
example: phenix
type: string
default: phenix
driver:
title: "Driver"
description: 'Emulated network card, such as e1000 or virtio-net-pci. Empty uses minimega''s default.'
type: string
example: e1000
qinq:
title: "QinQ"
description: >-
Carry the guest's own VLAN tags inside the interface's VLAN (QinQ, 802.1ad). The guest brings the interface
up without an address.
example: false
type: boolean
default: false
iface_address:
title: "Interface Address"
description: "Schema describing the Iface Address resource."
type: object
required:
- address
- mask
properties:
address:
title: "Address"
description: 'IPv4 address of the interface.'
type: string
format: ipv4
example: 192.168.1.100
mask:
title: "Mask"
description: 'Network prefix length (CIDR bits), from 0 to 32.'
type: integer
minimum: 0
maximum: 32
default: 24
example: 24
gateway:
title: "Gateway"
description: 'Default gateway, reached through this interface.'
type: string
format: ipv4
example: 192.168.1.1
dns:
title: "DNS Servers"
description: 'DNS server addresses the guest uses: one address, or a list.'
nullable: true
oneOf:
- type: string
- type: array
items:
type: string
example:
- 192.168.1.1
- 192.168.1.2
iface_rulesets:
title: "Interface Rulesets"
description: "Schema describing the Iface Rulesets resource."
type: object
properties:
ruleset_out:
title: "Ruleset Out"
description: 'Ruleset for traffic going out of this interface, on Router and Firewall nodes.'
type: string
example: OutToInet
pattern: '^[\w-]*$'
ruleset_in:
title: "Ruleset In"
description: 'Ruleset for traffic coming in on this interface, on Router and Firewall nodes.'
type: string
example: InFromInet
pattern: '^[\w-]*$'
static_iface:
title: "Static Interface"
description: "Schema describing the Static Iface resource."
allOf:
- $ref: '#/components/schemas/iface'
- $ref: '#/components/schemas/iface_address'
- $ref: '#/components/schemas/iface_rulesets'
required:
- type
- proto
properties:
type:
title: "Type"
description: 'Kind of interface: ethernet.'
type: string
enum:
- ethernet
default: ethernet
example: ethernet
proto:
title: "Protocol"
description: >-
How the interface is addressed: static for a fixed address, or ospf for a fixed address that also takes part
in OSPF on a router.
type: string
enum:
- static
- ospf
default: static
example: static
dhcp_iface:
title: "DHCP Interface"
description: "Schema describing the Dhcp Iface resource."
allOf:
- $ref: '#/components/schemas/iface'
- $ref: '#/components/schemas/iface_rulesets'
required:
- type
- proto
properties:
type:
title: "Type"
description: 'Kind of interface: ethernet.'
type: string
enum:
- ethernet
default: ethernet
example: ethernet
proto:
title: "Protocol"
description: >-
How the interface is addressed: dhcp to ask a DHCP server, or manual to bring it up with no address.
type: string
enum:
- dhcp
- manual
default: dhcp
example: dhcp
serial_iface:
title: "Serial Interface"
description: "Schema describing the Serial Iface resource."
allOf:
- $ref: '#/components/schemas/iface'
- $ref: '#/components/schemas/iface_address'
- $ref: '#/components/schemas/iface_rulesets'
required:
- type
- proto
- udp_port
- baud_rate
- device
properties:
type:
title: "Type"
description: 'Kind of interface: a serial link, carried over the network between VMs.'
type: string
enum:
- serial
default: serial
example: serial
proto:
title: "Protocol"
description: 'Serial interfaces have a static address.'
type: string
enum:
- static
default: static
example: static
udp_port:
title: "UDP Port"
description: 'UDP port that carries the serial traffic between VMs.'
type: integer
minimum: 0
maximum: 65535
default: 8989
example: 8989
baud_rate:
title: "Baud Rate"
description: 'Speed of the serial line, in bits per second.'
type: integer
enum:
- 110
- 300
- 600
- 1200
- 2400
- 4800
- 9600
- 14400
- 19200
- 38400
- 57600
- 115200
- 128000
- 256000
default: 9600
example: 9600
device:
title: "Device"
description: 'Serial device the guest uses, such as /dev/ttyS0.'
type: string
default: /dev/ttyS0
example: /dev/ttyS0
Complete Schemas¶
v1.yaml¶
# Schemas for the config kinds stored at apiVersion phenix.sandia.gov/v1:
# Topology, Experiment, Image, User and Role. Configs are validated against
# the schema file of their own apiVersion, so a kind appears only in the
# file of the version it is stored at (see version.StoredVersion).
# The "--8<--" comments mark the sections docs/content/schema.md shows; the
# last section runs to the end of the file.
openapi: "3.0.0"
info:
title: phenix config specs
version: "1.0"
paths: {}
components:
schemas:
Image:
title: "Image"
description: "Schema describing the Image resource."
type: object
required:
- format
- mirror
- release
- size
- variant
properties:
compress:
title: "Compress"
description: "Whether to compress the disk image after creating it."
type: boolean
default: false
example: false
components:
title: "Components"
description: "Distribution components from which to install packages."
type: array
nullable: true
items:
type: string
example:
- main
- restricted
kernel:
title: "Kernel"
description: "Kernel command-line arguments included in the image."
type: array
nullable: true
items:
type: string
example:
- net.ifnames=0
no_virtuals:
title: "No Virtuals"
description: "Whether to omit virtual packages when resolving packages."
type: boolean
default: false
example: false
format:
title: "Format"
description: "Format of the output disk image."
type: string
enum:
- raw
- qcow2
- vmdk
- vdi
- vhdx
example: qcow2
mirror:
title: "Mirror"
description: "URL of the distribution mirror used to build the image."
type: string
example: http://us.archive.ubuntu.com/ubuntu/
overlays:
title: "Overlays"
description: "Overlay directories applied while building the image."
type: array
nullable: true
items:
type: string
example:
- /phenix/vmdb/overlays/example-overlay
packages:
title: "Packages"
description: "Additional packages installed in the image."
type: array
nullable: true
items:
type: string
example:
- isc-dhcp-client
- openssh-server
ramdisk:
title: "Ramdisk"
description: "Whether to build a kernel and initrd alongside the disk image."
type: boolean
default: false
example: false
release:
title: "Release"
description: "Distribution release used to build the image."
type: string
example: focal
script_order:
title: "Script Order"
description: "Script names in the order they run during the image build."
type: array
nullable: true
items:
type: string
example:
- POSTBUILD_APT_CLEANUP
scripts:
title: "Scripts"
description: "Named scripts available to the image build."
type: object
nullable: true
additionalProperties:
type: string
example:
POSTBUILD_APT_CLEANUP: |
apt clean || apt-get clean || echo "unable to clean apt cache"
skip_default_packages:
title: "Skip Default Packages"
description: "Whether to omit the default packages of the image builder."
type: boolean
default: false
example: false
size:
title: "Size"
description: "Target size of the generated disk image: a positive number and M or G, such as 10G."
type: string
pattern: '^(0*[1-9][0-9]*(\.[0-9]+)?|0+\.[0-9]*[1-9][0-9]*)[MG]$'
example: 10G
variant:
title: "Variant"
description: "Distribution variant used to build the image."
type: string
example: minbase
Role:
title: "Role"
description: "Schema describing the Role resource."
type: object
required:
- policies
- roleName
properties:
policies:
title: "Policies"
description: "Access policies assigned to this role."
type: array
items:
type: object
properties:
resources:
title: "Resources"
description: "Resource types covered by this policy."
type: array
items:
type: string
resourceNames:
title: "Resource Names"
description: "Resource names covered by this policy."
type: array
items:
type: string
verbs:
title: "Verbs"
description: "Actions allowed on the listed resources."
type: array
items:
type: string
example:
- resources:
- experiments
- experiments/*
resourceNames:
- '*'
verbs:
- list
- get
roleName:
title: "Role Name"
description: "Name assigned to this role."
type: string
example: Example Role
User:
title: "User"
description: "Schema describing the User resource."
type: object
required:
- first_name
- last_name
- username
properties:
first_name:
title: "First Name"
description: "Given name of the user."
type: string
example: John
last_name:
title: "Last Name"
description: "Family name of the user."
type: string
example: Doe
password:
title: "Password"
description: "Password supplied for account creation or sign-in."
type: string
example: '<encrypted password>'
readOnly: true
rbac:
title: "RBAC"
description: "Role-based access control settings assigned to this user."
allOf:
- $ref: "#/components/schemas/Role"
readOnly: true
username:
title: "Username"
description: "Username used to identify the account."
type: string
example: johndoe@example.com
Topology:
title: "Topology"
description: "Schema describing the Topology resource."
type: object
anyOf:
- required:
- nodes
- required:
- includeTopologies
properties:
includeTopologies:
title: "Included Topologies"
description: >-
Topology configs or file paths to merge into this topology. A
single value is the same as a list of one value.
nullable: true
anyOf:
- type: array
items:
type: string
- type: string
example:
- /phenix/topologies/common.yml
- shared-topology
nodes:
title: "Nodes"
description: "Nodes that make up the topology."
type: array
items:
oneOf:
- $ref: '#/components/schemas/minimega_node'
- $ref: '#/components/schemas/external_node'
Experiment:
title: "Experiment"
description: "Schema describing the Experiment resource."
type: object
required:
- topology
properties:
topology:
title: "Topology"
description: "Topology configuration embedded in or referenced by this resource."
allOf:
- $ref: "#/components/schemas/Topology"
scenario:
$ref: "#/components/schemas/experiment_scenario"
baseDir:
title: "Base Dir"
description: "Working directory used by the experiment."
type: string
example: /phenix/topologies/example-topo
experimentName:
title: "Experiment Name"
description: "Name of the experiment."
type: string
example: example-exp
readOnly: true
vlans:
title: "VLANs"
description: "VLAN IDs and aliases allocated to the experiment."
type: object
nullable: true
properties:
aliases:
title: "Aliases"
description: "Mapping from VLAN aliases to VLAN IDs."
type: object
nullable: true
additionalProperties:
type: integer
example:
MGMT: 200
min:
title: "Min"
description: "Lowest VLAN ID available to the experiment."
example: 1
type: integer
max:
title: "Max"
description: "Highest VLAN ID available to the experiment."
example: 1
type: integer
schedules:
title: "Schedules"
description: "Mapping from VM hostnames to cluster hosts."
type: object
nullable: true
additionalProperties:
type: string
example:
ADServer: compute1
defaultBridge:
title: "Default Bridge"
description: "Bridge used for experiment VM interfaces by default."
type: string
nullable: true
maxLength: 15
example: phenix
deployMode:
title: "Deploy Mode"
description: "Cluster hosts eligible to run experiment VMs."
type: string
nullable: true
enum:
- all
- no-headnode
- only-headnode
example: all
useGREMesh:
title: "Use GRE Mesh"
description: "Whether cluster hosts use a GRE mesh for this experiment."
type: boolean
nullable: true
example: false
# experiment_scenario is the scenario an Experiment embeds. It is a copy of
# the Scenario component in v2.yaml, the only version a Scenario config is
# stored at; TestExperimentScenarioMatchesScenario keeps the two identical.
experiment_scenario:
title: "Scenario"
description: "Schema describing the Scenario resource."
type: object
nullable: true
required:
- apps
properties:
apps:
title: "Apps"
description: "Applications configured for this scenario."
type: array
nullable: true
items:
type: object
required:
- name
properties:
name:
title: "Name"
description: "Name used to identify this resource or entry."
type: string
example: example-app
assetDir:
title: "Asset Directory"
description: "Directory containing assets made available to the application."
type: string
example: /phenix/topologies/example-topo/assets
metadata:
title: "Metadata"
description: "Application-specific settings shared across its hosts."
type: object
nullable: true
additionalProperties: true
example:
setting0: true
setting1: 42
setting2: universe key
runPeriodically:
title: "Run Periodically"
description: "Interval at which the application running stage repeats."
type: string
example: 30s
disabled:
title: "Disabled"
description: "Whether to skip this application."
type: boolean
default: false
example: false
nullable: true
fromScenario:
title: "From Scenario"
description: "Scenario inherited by this application configuration."
type: string
example: base-scenario
hosts:
title: "Hosts"
description: "Host-specific application settings."
type: array
items:
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: "Hostname used to identify the node."
type: string
example: example-host
metadata:
title: "Metadata"
description: "Application-specific settings for this host."
type: object
nullable: true
additionalProperties: true
example:
setting0: true
setting1: 42
setting2: universe key
minimega_node:
title: "Minimega Node"
description: "Schema describing the Minimega Node resource."
type: object
required:
- type
- general
- hardware
properties:
type:
title: "Type"
description: >-
What the node is. phenix configures Router and Firewall nodes whose OS type is vyatta, vyos or minirouter as
routers, from their interfaces, routes, OSPF settings and rulesets.
type: string
enum:
- VirtualMachine
- Firewall
- Router
- Switch
default: VirtualMachine
example: VirtualMachine
annotations:
title: "Annotations"
description: "Free-form annotations associated with this node."
type: object
nullable: true
additionalProperties: true
example:
app: web
labels:
title: "Labels"
description: "String labels used to select or group nodes."
type: object
nullable: true
additionalProperties:
type: string
example:
tier: frontend
general:
title: "General"
description: "General node settings."
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: >-
Name of the VM in minimega and the host name set in the guest.
The name is unique in the topology.
# 2 to 63 letters, digits, and interior hyphens. Guest operating
# systems phenix configures reject 1-character hostnames.
#
# VyOS and Vyatta validate `system host-name` against
# `[A-Za-z0-9][-.A-Za-z0-9]*[A-Za-z0-9]`, which needs at least 2
# characters:
# https://docs.vyos.io/en/latest/configuration/system/host-name.html
# https://github.com/vyos/vyos-1x/blob/ed218c254d964775ddf24158ac6520972d575faf/interface-definitions/include/constraint/host-name.xml.i
#
# Windows DNS host names have a 2-character minimum:
# https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/naming-conventions-for-computer-domain-site-ou#dns-host-names
type: string
minLength: 2
maxLength: 63
pattern: '^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$'
example: ADServer
description:
title: "Description"
description: 'Free-text notes about the node.'
type: string
example: Active Directory Server
vm_type:
title: "VM Type"
description: >-
How minimega runs the node: kvm for a QEMU/KVM virtual machine, or container. Empty means kvm.
type: string
enum:
- kvm
- container
- ""
default: kvm
example: kvm
snapshot:
title: "Snapshot"
description: >-
Run the VM on a copy-on-write snapshot of its first drive, which phenix creates for the experiment and
injects files into, so the image file itself does not change. phenix turns this on when it is not set.
type: boolean
default: true
example: true
nullable: true
do_not_boot:
title: "Do Not Boot"
description: >-
Leave the node out when the experiment starts: phenix neither creates nor starts its VM. phenix also
sets this when the first drive's image is missing.
type: boolean
default: false
example: false
nullable: true
hardware:
title: "Hardware"
description: "Virtual hardware assigned to the node."
type: object
required:
- os_type
- drives
properties:
cpu:
title: "CPU"
description: 'QEMU CPU model for the VM, such as Broadwell or host.'
type: string
default: Broadwell
example: Broadwell
vcpus:
title: "Virtual CPUs"
description: 'Number of virtual CPUs. phenix uses 1 when it is not set.'
oneOf:
- type: integer
- type: string
default: 1
example: 4
memory:
title: "Memory"
description: 'Memory for the VM, in megabytes. phenix uses 512 when it is not set.'
oneOf:
- type: integer
- type: string
default: 512
example: 8192
os_type:
title: "OS Type"
description: >-
Operating system in the disk image. phenix and its apps choose startup scripts and router configuration
by it.
type: string
enum:
- centos
- linux
- minirouter
- rhel
- vyatta
- vyos
- windows
- other
default: linux
example: windows
drives:
title: "Drives"
description: >-
Disks attached to the VM, in order. The first is the one phenix snapshots and injects files into.
type: array
minItems: 1
items:
type: object
required:
- image
properties:
image:
title: "Image"
description: >-
Disk image file: a name in the phenix image directory, or an absolute path on the host.
type: string
minLength: 1
example: ubuntu.qc2
interface:
title: "Interface"
description: >-
Bus the disk is attached to, such as ide, scsi or virtio. Empty uses minimega's default.
type: string
enum:
- ahci
- ide
- scsi
- sd
- mtd
- floppy
- pflash
- virtio
- ""
default: ide
example: ide
cache_mode:
title: "Cache Mode"
description: >-
QEMU cache mode for the disk. Empty uses writeback for a snapshot, and QEMU's default otherwise.
type: string
enum:
- none
- writeback
- unsafe
- directsync
- writethrough
- ""
default: writeback
example: writeback
inject_partition:
title: "Inject Partition"
description: >-
Partition of the first drive that phenix injects files into. 0 skips disk injection, and phenix
sends its startup scripts through minimega command and control instead. phenix uses 1 when it is
not set.
type: integer
default: 1
example: 2
nullable: true
network:
title: "Network"
description: "Network settings associated with this node."
type: object
nullable: true
required:
- interfaces
properties:
interfaces:
title: "Interfaces"
description: 'Network interfaces, in the order the guest sees them.'
type: array
nullable: true
items:
type: object
oneOf:
- $ref: '#/components/schemas/static_iface'
- $ref: '#/components/schemas/dhcp_iface'
- $ref: '#/components/schemas/serial_iface'
routes:
title: "Routes"
description: 'Static routes phenix configures in the guest.'
type: array
nullable: true
items:
type: object
required:
- destination
- next
properties:
destination:
title: "Destination"
description: 'Network to reach, in CIDR notation such as 192.168.0.0/24.'
type: string
example: 192.168.0.0/24
next:
title: "Next"
description: 'Address of the next hop toward the destination.'
type: string
example: 192.168.1.254
cost:
title: "Cost"
description: 'Route cost, set as the administrative distance on Vyatta and VyOS routers.'
type: integer
default: 1
example: 1
nullable: true
ospf:
title: "OSPF"
description: "Open Shortest Path First routing settings."
type: object
nullable: true
required:
- router_id
- areas
properties:
router_id:
title: "Router Id"
description: 'OSPF router ID, written like an IPv4 address, such as 0.0.0.1.'
type: string
example: 0.0.0.1
areas:
title: "Areas"
description: 'OSPF areas the router takes part in.'
type: array
items:
type: object
required:
- area_id
- area_networks
properties:
area_id:
title: "Area Id"
description: 'OSPF area number. 0 is the backbone area.'
type: integer
example: 1
default: 1
area_networks:
title: "Area Networks"
description: 'Networks the router advertises in the area.'
type: array
items:
type: object
required:
- network
properties:
network:
title: "Network"
description: 'Network in CIDR notation, such as 10.1.25.0/24.'
type: string
example: 10.1.25.0/24
dead_interval:
title: "Dead Interval"
description: >-
Seconds without a hello from a neighbor before the router considers it down. Applies to interfaces
whose protocol is ospf.
type: integer
nullable: true
example: 40
hello_interval:
title: "Hello Interval"
description: 'Seconds between OSPF hello packets. Applies to interfaces whose protocol is ospf.'
type: integer
nullable: true
example: 10
retransmission_interval:
title: "Retransmission Interval"
description: >-
Seconds before the router resends a link-state advertisement that was not acknowledged. Applies to
interfaces whose protocol is ospf.
type: integer
nullable: true
example: 5
rulesets:
title: "Rulesets"
description: >-
Firewall rulesets for Router and Firewall nodes. An interface applies one by naming it as its inbound or
outbound ruleset.
type: array
nullable: true
items:
type: object
required:
- name
- default
- rules
properties:
name:
title: "Name"
description: 'Name interfaces use to apply the ruleset.'
type: string
example: OutToDMZ
description:
title: "Description"
description: 'Describes the ruleset in the router configuration.'
type: string
example: From Corp to the DMZ network
default:
title: "Default"
description: 'What happens to traffic that no rule matches.'
type: string
enum:
- accept
- drop
- reject
example: drop
rules:
title: "Rules"
description: 'Rules of the ruleset.'
type: array
items:
type: object
required:
- id
- action
- protocol
properties:
id:
title: "Id"
description: >-
Rule number, unique in the ruleset. Vyatta and VyOS routers check rules from the lowest
number up.
type: integer
example: 10
description:
title: "Description"
description: 'Describes the rule in the router configuration.'
type: string
example: Allow UDP 10.1.26.80 ==> 10.2.25.0/24:123
action:
title: "Action"
description: 'What happens to traffic the rule matches.'
type: string
enum:
- accept
- drop
- reject
example: accept
protocol:
title: "Protocol"
description: 'Protocol of the traffic the rule matches.'
type: string
enum:
- tcp
- udp
- tcp_udp
- icmp
- esp
- ah
- all
default: tcp
example: tcp
source:
title: "Source"
description: "Source address and optional port matched by this rule."
type: object
nullable: true
required:
- address
properties:
address:
title: "Address"
description: 'Source address or network the rule matches.'
type: string
example: 10.1.24.60
port:
title: "Port"
description: 'Source port the rule matches. Empty or 0 matches any port.'
type: integer
example: 3389
destination:
title: "Destination"
description: "Destination network or address for this route or rule."
type: object
nullable: true
required:
- address
properties:
address:
title: "Address"
description: 'Destination address or network the rule matches.'
type: string
example: 10.1.24.60
port:
title: "Port"
description: 'Destination port the rule matches. Empty or 0 matches any port.'
type: integer
example: 3389
stateful:
title: "Stateful"
description: "Whether the firewall rule tracks connection state."
type: boolean
example: true
nat:
title: "Nat"
description: "Mappings for network address translation on this node."
type: array
nullable: true
items:
type: object
properties:
in:
title: "In"
description: "Names of the internal interfaces whose networks this NAT rule maps."
type: array
items:
type: string
example:
- eth1
out:
title: "Out"
description: "External interface used by this NAT rule."
type: string
example: eth0
injections:
title: "Injections"
description: 'Files phenix copies into the snapshot of the first drive before the VM starts.'
type: array
nullable: true
items:
type: object
required:
- src
- dst
properties:
src:
title: "Source"
description: >-
File on the phenix host: an absolute path, or a path relative to the experiment directory.
type: string
example: foo.xml
dst:
title: "Destination"
description: 'Path the file is written to in the guest.'
type: string
example: /etc/phenix/foo.xml
description:
title: "Description"
description: 'Free-text notes about the file.'
type: string
example: phenix config file
permissions:
title: "Permissions"
description: 'File mode for the copied file, in octal such as 0664.'
type: string
example: '0664'
deletions:
title: "Deletions"
description: "Files to remove from the node disk before boot."
type: array
nullable: true
items:
type: object
required:
- path
properties:
path:
title: "Path"
description: "Path to remove from the node disk."
type: string
minLength: 1
example: /etc/obsolete.conf
description:
title: "Description"
description: "Human-readable description of this resource or entry."
type: string
example: Remove the obsolete configuration file
overrides:
title: "Overrides"
description: "Minimega VM settings overridden for this node."
type: object
nullable: true
additionalProperties:
type: string
example:
memory: "4096"
delay:
title: "Delay"
description: "Conditions that delay the node start."
type: object
nullable: true
properties:
timer:
title: "Timer"
description: 'Start the VM this long after the experiment starts, as a duration such as 30s or 5m.'
type: string
pattern: '^$|^[-+]?(0|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$'
example: 5m
user:
title: "User"
description: >-
Leave the VM stopped until someone starts it from phenix or minimega. Takes precedence over the other
delays.
example: false
type: boolean
c2:
title: "C2"
description: 'Start the VM once each of these hosts has checked in with minimega command and control.'
type: array
nullable: true
items:
type: object
properties:
hostname:
title: "Hostname"
description: 'Host to wait for.'
example: node-01
type: string
useUUID:
title: "Use UUID"
description: 'Wait for the host''s UUID, rather than its hostname, to check in.'
example: false
type: boolean
advanced:
title: "Advanced"
description: 'Extra minimega vm config settings, each a setting name and its value.'
type: object
nullable: true
additionalProperties:
type: string
example:
rtc.utc: "true"
commands:
title: "Commands"
description: 'minimega command and control (cc) commands phenix sends to the VM, such as exec df -h.'
type: array
nullable: true
items:
type: string
example:
- exec df -h
external_node:
title: "External Node"
description: "Schema describing the External Node resource."
type: object
required:
- external
- type
- general
properties:
external:
title: "External"
description: >-
Marks a device phenix does not deploy, such as hardware in the loop. It stays in the topology for State of
Health and apps.
example: true
type: boolean
enum:
- true
annotations:
title: "Annotations"
description: "Free-form annotations associated with this node."
type: object
nullable: true
additionalProperties: true
example:
physical: true
labels:
title: "Labels"
description: "String labels used to select or group nodes."
type: object
nullable: true
additionalProperties:
type: string
example:
tier: endpoint
type:
title: "Type"
description: 'What the device is, such as HIL for hardware in the loop.'
type: string
default: HIL
example: HIL
general:
title: "General"
description: "General node settings."
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: 'Name of the device in the topology.'
type: string
example: ADServer
description:
title: "Description"
description: 'Free-text notes about the device.'
type: string
example: Active Directory Server
vm_type:
title: "VM Type"
description: 'Whether the device is a virtual machine or a container.'
type: string
enum:
- vm
- container
- ""
default: vm
example: vm
hardware:
title: "Hardware"
description: "Virtual hardware assigned to the node."
type: object
nullable: true
required:
- os_type
properties:
cpu:
title: "CPU"
description: 'CPU model of the device.'
type: string
default: Broadwell
example: Broadwell
vcpus:
title: "Virtual CPUs"
description: 'Number of CPUs of the device.'
oneOf:
- type: integer
- type: string
default: 1
example: 4
memory:
title: "Memory"
description: 'Memory of the device, in megabytes.'
oneOf:
- type: integer
- type: string
default: 512
example: 8192
os_type:
title: "OS Type"
description: 'Operating system of the device.'
type: string
enum:
- centos
- linux
- minirouter
- rhel
- vyatta
- vyos
- windows
- other
default: linux
example: windows
network:
title: "Network"
description: "Network settings associated with this node."
type: object
nullable: true
required:
- interfaces
properties:
interfaces:
title: "Interfaces"
description: >-
Network interfaces of the device, for the topology's network diagram and State of Health checks.
type: array
items:
type: object
required:
- name
properties:
name:
title: "Name"
description: 'Interface name, such as eth0.'
type: string
example: eth0
proto:
title: "Protocol"
description: 'How the interface gets its address: static, dhcp, or manual for none.'
type: string
enum:
- static
- dhcp
- manual
- ""
default: dhcp
example: static
address:
title: "Address"
description: 'IPv4 address of the interface.'
type: string
format: ipv4
example: 192.168.1.100
mask:
title: "Mask"
description: 'Network prefix length (CIDR bits), from 0 to 32.'
type: integer
minimum: 0
maximum: 32
default: 24
example: 24
gateway:
title: "Gateway"
description: 'Default gateway of the interface.'
type: string
format: ipv4
example: 192.168.1.1
vlan:
title: "VLAN"
description: 'VLAN (network) the interface is on.'
type: string
example: EXP-1
injections:
title: "Injections"
description: "Files to copy into the node disk before boot."
type: array
nullable: true
items:
type: object
required:
- src
- dst
properties:
src:
title: "Source"
description: "Source file copied into the node disk."
type: string
minLength: 1
example: ./config.txt
dst:
title: "Destination"
description: "Destination path for the injected file."
type: string
minLength: 1
example: /etc/config.txt
description:
title: "Description"
description: "Human-readable description of this resource or entry."
type: string
example: Inject endpoint config
permissions:
title: "Permissions"
description: "File permissions to set on the injected file."
type: string
example: '0644'
deletions:
title: "Deletions"
description: "Files to remove from the node disk before boot."
type: array
nullable: true
items:
type: object
required:
- path
properties:
path:
title: "Path"
description: "Path to remove from the node disk."
type: string
minLength: 1
example: /tmp/obsolete
description:
title: "Description"
description: "Human-readable description of this resource or entry."
type: string
example: Remove obsolete endpoint file
overrides:
title: "Overrides"
description: "Minimega VM settings overridden for this node."
type: object
nullable: true
additionalProperties:
type: string
delay:
title: "Delay"
description: "Conditions that delay the node start."
type: object
nullable: true
properties:
timer:
title: "Timer"
description: "Duration to wait before starting the node, in Go duration syntax such as 5m or 1h30m."
type: string
pattern: '^$|^[-+]?(0|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$'
example: 5m
user:
title: "User"
description: "Whether node start requires user confirmation."
type: boolean
example: true
c2:
title: "C2"
description: "Command-and-control hosts whose availability can release the delay."
type: array
items:
type: object
properties:
hostname:
title: "Hostname"
description: "Hostname used to identify the node."
type: string
example: c2-server
useUUID:
title: "Use UUID"
description: "Whether to match the command-and-control host by UUID."
type: boolean
example: false
advanced:
title: "Advanced"
description: "Additional minimega VM settings."
type: object
nullable: true
additionalProperties:
type: string
commands:
title: "Commands"
description: "Minimega commands to run for this node."
type: array
nullable: true
items:
type: string
example:
- exec hostname
iface:
title: "Interface"
description: "Schema describing the Iface resource."
type: object
required:
- name
- vlan
properties:
name:
title: "Name"
description: 'Interface name, such as eth0, which NAT settings and apps use to refer to it.'
type: string
example: eth0
vlan:
title: "VLAN"
description: 'VLAN (network) the interface is on.'
type: string
example: EXP-1
autostart:
title: "Autostart"
description: >-
Whether the interface should come up when the VM boots. phenix itself does not act on this setting.
example: true
type: boolean
default: true
mac:
title: "MAC"
description: 'MAC address. minimega generates one when it is empty.'
type: string
example: 00:11:22:33:44:55
pattern: '^$|^([0-9a-fA-F]{2}[:-]){5}([0-9a-fA-F]){2}$'
mtu:
title: "MTU"
description: >-
Maximum transmission unit, in bytes. Vyatta and VyOS routers apply values from 68 to 16000; other images
keep their own.
type: integer
default: 1500
example: 1500
bridge:
title: "Bridge"
description: >-
Open vSwitch bridge on the host the interface attaches to. Empty or phenix uses the experiment's default
bridge.
example: phenix
type: string
default: phenix
driver:
title: "Driver"
description: 'Emulated network card, such as e1000 or virtio-net-pci. Empty uses minimega''s default.'
type: string
example: e1000
qinq:
title: "QinQ"
description: >-
Carry the guest's own VLAN tags inside the interface's VLAN (QinQ, 802.1ad). The guest brings the interface
up without an address.
example: false
type: boolean
default: false
iface_address:
title: "Interface Address"
description: "Schema describing the Iface Address resource."
type: object
required:
- address
- mask
properties:
address:
title: "Address"
description: 'IPv4 address of the interface.'
type: string
format: ipv4
example: 192.168.1.100
mask:
title: "Mask"
description: 'Network prefix length (CIDR bits), from 0 to 32.'
type: integer
minimum: 0
maximum: 32
default: 24
example: 24
gateway:
title: "Gateway"
description: 'Default gateway, reached through this interface.'
type: string
format: ipv4
example: 192.168.1.1
dns:
title: "DNS Servers"
description: 'DNS server addresses the guest uses: one address, or a list.'
nullable: true
oneOf:
- type: string
- type: array
items:
type: string
example:
- 192.168.1.1
- 192.168.1.2
iface_rulesets:
title: "Interface Rulesets"
description: "Schema describing the Iface Rulesets resource."
type: object
properties:
ruleset_out:
title: "Ruleset Out"
description: 'Ruleset for traffic going out of this interface, on Router and Firewall nodes.'
type: string
example: OutToInet
pattern: '^[\w-]*$'
ruleset_in:
title: "Ruleset In"
description: 'Ruleset for traffic coming in on this interface, on Router and Firewall nodes.'
type: string
example: InFromInet
pattern: '^[\w-]*$'
static_iface:
title: "Static Interface"
description: "Schema describing the Static Iface resource."
allOf:
- $ref: '#/components/schemas/iface'
- $ref: '#/components/schemas/iface_address'
- $ref: '#/components/schemas/iface_rulesets'
required:
- type
- proto
properties:
type:
title: "Type"
description: 'Kind of interface: ethernet.'
type: string
enum:
- ethernet
default: ethernet
example: ethernet
proto:
title: "Protocol"
description: >-
How the interface is addressed: static for a fixed address, or ospf for a fixed address that also takes part
in OSPF on a router.
type: string
enum:
- static
- ospf
default: static
example: static
dhcp_iface:
title: "DHCP Interface"
description: "Schema describing the Dhcp Iface resource."
allOf:
- $ref: '#/components/schemas/iface'
- $ref: '#/components/schemas/iface_rulesets'
required:
- type
- proto
properties:
type:
title: "Type"
description: 'Kind of interface: ethernet.'
type: string
enum:
- ethernet
default: ethernet
example: ethernet
proto:
title: "Protocol"
description: >-
How the interface is addressed: dhcp to ask a DHCP server, or manual to bring it up with no address.
type: string
enum:
- dhcp
- manual
default: dhcp
example: dhcp
serial_iface:
title: "Serial Interface"
description: "Schema describing the Serial Iface resource."
allOf:
- $ref: '#/components/schemas/iface'
- $ref: '#/components/schemas/iface_address'
- $ref: '#/components/schemas/iface_rulesets'
required:
- type
- proto
- udp_port
- baud_rate
- device
properties:
type:
title: "Type"
description: 'Kind of interface: a serial link, carried over the network between VMs.'
type: string
enum:
- serial
default: serial
example: serial
proto:
title: "Protocol"
description: 'Serial interfaces have a static address.'
type: string
enum:
- static
default: static
example: static
udp_port:
title: "UDP Port"
description: 'UDP port that carries the serial traffic between VMs.'
type: integer
minimum: 0
maximum: 65535
default: 8989
example: 8989
baud_rate:
title: "Baud Rate"
description: 'Speed of the serial line, in bits per second.'
type: integer
enum:
- 110
- 300
- 600
- 1200
- 2400
- 4800
- 9600
- 14400
- 19200
- 38400
- 57600
- 115200
- 128000
- 256000
default: 9600
example: 9600
device:
title: "Device"
description: 'Serial device the guest uses, such as /dev/ttyS0.'
type: string
default: /dev/ttyS0
example: /dev/ttyS0
v2.yaml¶
# Schemas for the config kinds stored at apiVersion phenix.sandia.gov/v2:
# Scenario. Configs are validated against the schema file of their own
# apiVersion, so a kind appears only in the file of the version it is
# stored at (see version.StoredVersion).
# The "--8<--" comments mark the sections docs/content/schema.md shows; the
# last section runs to the end of the file.
openapi: "3.0.0"
info:
title: phenix config specs
version: "2.0"
paths: {}
components:
schemas:
Scenario:
title: "Scenario"
description: "Schema describing the Scenario resource."
type: object
nullable: true
required:
- apps
properties:
apps:
title: "Apps"
description: "Applications configured for this scenario."
type: array
nullable: true
items:
type: object
required:
- name
properties:
name:
title: "Name"
description: "Name used to identify this resource or entry."
type: string
example: example-app
assetDir:
title: "Asset Directory"
description: "Directory containing assets made available to the application."
type: string
example: /phenix/topologies/example-topo/assets
metadata:
title: "Metadata"
description: "Application-specific settings shared across its hosts."
type: object
nullable: true
additionalProperties: true
example:
setting0: true
setting1: 42
setting2: universe key
runPeriodically:
title: "Run Periodically"
description: "Interval at which the application running stage repeats."
type: string
example: 30s
disabled:
title: "Disabled"
description: "Whether to skip this application."
type: boolean
default: false
example: false
nullable: true
fromScenario:
title: "From Scenario"
description: "Scenario inherited by this application configuration."
type: string
example: base-scenario
hosts:
title: "Hosts"
description: "Host-specific application settings."
type: array
items:
type: object
required:
- hostname
properties:
hostname:
title: "Hostname"
description: "Hostname used to identify the node."
type: string
example: example-host
metadata:
title: "Metadata"
description: "Application-specific settings for this host."
type: object
nullable: true
additionalProperties: true
example:
setting0: true
setting1: 42
setting2: universe key