Skip to content

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