conlink 2.0.0

package/old/conlink.cljs

@@ -0,0 +1,131 @@
+#!/usr/bin/env nbb
+
+(ns conlink
+  (:require [clojure.string :as S]
+            [promesa.core :as P]
+            [cljs-bean.core :refer [->clj]]
+            [conlink.util :refer [parse-opts Eprintln Epprint
+                                  fatal spawn exec read-file]]
+            ["yaml$default" :as yaml]
+            ["dockerode$default" :as Docker]))
+
+(def usage "
+conlink: advanced container linking (networking).
+
+Usage:
+  conlink [options]
+
+Options:
+  -v, --verbose                     Show verbose output (stderr)
+                                    [env: VERBOSE]
+  --project PROJECT                 Docker compose project name
+                                    [env: COMPOSE_PROJECT_NAME]
+  --network-file NETWORK-FILE...    Network configuration file
+  --compose-file COMPOSE-FILE...    Docker compose file
+")
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(defn json-str [obj]
+  (js/JSON.stringify (clj->js obj)))
+
+(defn mangle-network-config 
+  "
+  - Rewrite network config to use actual container names instead of
+    the convenience aliases.
+  - Prune links, interfaces, and commands based on enabled service
+    profiles.
+  "
+  [net-cfg prefix]
+  (let [links (reduce
+                (fn [links {:keys [left right] :as link}]
+                  (let [lname (str prefix (:container left))
+                        rname (str prefix (:container right))]
+                  (conj links
+                        {:left  (assoc left :container lname)
+                         :right (assoc right :container rname)})))
+                [] (:links net-cfg))]
+    (assoc net-cfg :links links)))
+
+
+(defn init-containers-state [net-cfg]
+  (let [state (into {} (for [l (:links net-cfg)
+                             c [(:left l) (:right l)]]
+                         [(:container c) {:state :unconnected :links []}]))]
+    (reduce
+      (fn [cfg {:keys [left right] :as link}]
+        (let [lfn (fn [me you] {:self (dissoc (me link) :container)
+                                :remote (you link)})]
+          (-> cfg
+              (update-in [(:container left)  :links] conj (lfn :left :right))
+              (update-in [(:container right) :links] conj (lfn :right :left)))))
+      state
+      (:links net-cfg)))
+
+(defn handle-container [{:keys [client project config state] :as ctx} cid]
+  (P/let [container (.getContainer client cid)
+          details (P/-> container .inspect ->clj)
+          {Name :Name {Labels :Labels} :Config} details]
+    (Eprintln :handle-container :cid cid)
+    #_(Epprint details)
+    (Epprint (get @state Name))))
+
+(P/let
+  [cfg (parse-opts usage *command-line-args*)
+   _ (when (empty? cfg) (js/process.exit 2))
+   {:keys [verbose project network-file compose-file]} cfg
+   _ (when verbose (Eprintln "Settings:"))
+   _ (when verbose (Epprint cfg))
+   _ (when (not (or network-file compose-file))
+       (fatal 2 "either --network-file or --compose-file is required"))
+
+   raw-network-config (P/-> (first network-file)
+                            (read-file "utf8")
+                            yaml/parse
+                            ->clj)
+   docker (Docker. #js {:socketPath "/var/run/docker.sock"})
+
+   _ (Eprintln "raw-network-config:")
+   _ (Epprint raw-network-config)
+   prefix (if project (str "/" project "_") "/")
+   network-config (mangle-network-config raw-network-config prefix)
+   _ (Eprintln "network-config:")
+   _ (Epprint network-config)
+   state (init-containers-state network-config)
+   _ (Eprintln "state:")
+   _ (Epprint state)
+
+   ctx {:client docker
+        :project project
+        :config network-config
+        :state (atom state)}
+   label-filters (if project
+                   {"label" [(str "com.docker.compose.project=" project)]}
+                   {})
+   ev-filters (merge label-filters
+                     {"event" ["start"]})
+   ev-stream (.getEvents docker #js {:filters (json-str ev-filters)})
+   _ (.on ev-stream "data" (fn [ev]
+                             (let [event (-> ev js/JSON.parse ->clj)] 
+                               (prn :event event)
+                               (handle-container ctx (:id event)))))
+
+   _ (Eprintln "Handling already running containers")
+   containers (P/-> docker
+                    (.listContainers #js {:filters (json-str label-filters)
+                                          :sparse true})
+                    ->clj)
+   #_#__ (Epprint containers)
+   _ (doseq [c containers] (handle-container ctx (:Id c)))
+
+   #_#_res (P/all [(spawn "sleep 1")
+               (spawn "ip link show")
+               (spawn "ip addr show")
+               (spawn "ip route show")])
+   #_#__ (prn :res res)
+   ]
+  (prn :here1)
+  )
+
+
+

package/old/dot_gitignore

@@ -0,0 +1 @@
+*.swp

package/old/examples/test2-compose.yaml

@@ -0,0 +1,32 @@
+# A docker-compose file with an external network configuration file
+# and two docker containers that are connected via a switch. In
+# addition an "internet" host is setup in the network container that
+# is also connected to the switch and is listening on 8.8.8.8.
+
+version: "2.4"
+
+services:
+  network:
+    build: {context: ../}
+    image: conlink.cljs
+    pid: host
+    network_mode: none
+    cap_add: [SYS_ADMIN, NET_ADMIN, SYS_NICE, NET_BROADCAST, IPC_LOCK]
+    security_opt: [ 'apparmor:unconfined' ] # needed on Ubuntu 18.04
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /var/lib/docker:/var/lib/docker
+      - ./:/test
+    command: /sbin/conlink -v --project ${COMPOSE_PROJECT_NAME:?required} --compose-file /test/test2-compose.yaml --network-file /test/test2-network.yaml
+
+  node1:
+    image: alpine
+    cap_add: [NET_ADMIN]
+    network_mode: none
+    command: sleep 864000
+
+  node2:
+    image: alpine
+    cap_add: [NET_ADMIN]
+    network_mode: none
+    command: sh -c 'while ! ip link show eth0 up; do sleep 1; done; sleep 864000'

package/old/examples/test2-network.yaml

@@ -0,0 +1,42 @@
+# "Physical" network interface definitions.
+# This defines container to container links.
+links:
+  - left:  {container: node1_1,   intf:       eth0,  ip: 10.0.1.1/16}
+    right: {container: network_1, intf: node1-eth0}
+  - left:  {container: node2_1,   intf:       eth0,  ip: 10.0.1.2/16}
+    right: {container: network_1, intf: node2-eth0}
+
+# Commands to run in containers after they are connected
+commands:
+  - container: node1_1
+    command: ip route add default via 10.0.0.1
+  - container: node2_1
+    command: ip route add default via 10.0.0.1
+
+# Network container mininet configuration
+# This configuration is used by config_mininet.py inside the network
+# container to define complex network elements (routers, switches,
+# etc).
+mininet-cfg:
+  switches:
+    - name: s1   # the switch between node1, node2, and internet
+  hosts:
+    - name: internet
+      opts: {ip: 10.0.0.1/16}
+  interfaces:
+    - name: node1-eth0
+      node: s1
+    - name: node2-eth0
+      node: s1
+  links:
+    - left: internet
+      right: s1
+
+  commands:
+    # In "internet" listen to 8.8.8.* addresses.
+    - node: internet
+      sync: true
+      command:
+        - ip link add ${DNS_INTF:-gdns} type dummy
+        - ip link set ${DNS_INTF:-gdns} up
+        - ip addr add 8.8.8.8/24 dev ${DNS_INTF:-gdns}

package/old/move-link.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+
+# Copyright (c) 2023, Viasat, Inc
+# Licensed under MPL 2.0
+
+set -e
+
+usage () {
+  echo >&2 "${0} [OPTIONS] TYPE INTF0 INTF1 PID0 PID1"
+  echo >&2 ""
+  echo >&2 "  TYPE:  one of the following values: move, vlan, macvlan,"
+  echo >&2 "         macvtap, ipvlan, or ipvtap. If TYPE is 'move'"
+  echo >&2 "         then INTF0 will be moved directly. For any other"
+  echo >&2 "         TYPE a sub-interface of TYPE will be created on"
+  echo >&2 "         INTF0 and the sub-interface virtual link will be"
+  echo >&2 "         moved instead."
+  echo >&2 "  INTF0: the interface in PID0 to move to PID1"
+  echo >&2 "  INTF1: the interface in PID1 after moving"
+  echo >&2 "  PID0:  the process ID of the first namespace"
+  echo >&2 "  PID1:  the process ID of the second namespace"
+  echo >&2 ""
+  echo >&2 "OPTIONS:"
+  echo >&2 "   --verbose        - Verbose output (set -x)"
+  echo >&2 "   --mode MODE      - Mode setting for *vlan, *vtap TYPEs"
+  echo >&2 "   --vlanid VLANID  - VLAN ID for vlan TYPE"
+  echo >&2 "   --ip IP          - Add IP (CIDR) to the moved interface"
+  echo >&2 "   --route 'ROUTE'  - route to add to the moved interface"
+  echo >&2 "   --nat TARGET     - Stateless NAT traffic to/from TARGET"
+  exit 2
+}
+
+IPTABLES() {
+  local ns=${1}; shift
+  ip netns exec ${ns} iptables -D "${@}" 2>/dev/null || true
+  ip netns exec ${ns} iptables -I "${@}"
+}
+
+VERBOSE=${VERBOSE:-}
+MODE= VLANID= IP= ROUTE= TARGET=
+
+info() { echo "move-link [${PID0}/${IF0} ->> ${PID1}/${IF1}] ${*}"; }
+warn() { >&2 echo "move-link [${PID0}/${IF0} ->> ${PID1}/${IF1}] ${*}"; }
+die()  { warn "ERROR: ${*}"; exit 1; }
+
+# Parse arguments
+positional=
+while [ "${*}" ]; do
+  param=$1; OPTARG=$2
+  case ${param} in
+  --verbose) VERBOSE=1 ;;
+  --mode) MODE="${OPTARG}"; shift ;;
+  --vlanid) VLANID="${OPTARG}"; shift ;;
+  --ip) IP="${OPTARG}"; shift ;;
+  --route) ROUTE="${OPTARG}"; shift ;;
+  --nat) TARGET="${OPTARG}"; shift ;;
+  -h|--help) usage ;;
+  *) positional="${positional} $1" ;;
+  esac
+  shift
+done
+set -- ${positional}
+
+TYPE=$1 IF0=$2 IF1=$3 PID0=$4 PID1=$5 NS0=ns${PID0} NS1=ns${PID1}
+
+[ "${VERBOSE}" ] && set -x || true
+
+# Check arguments
+[ "${$#}" -lt 5 ] && usage
+[ "${TARGET}" -a -z "${IP}" ] && die "--nat requires --ip"
+
+# Sanity checks
+[ ! -d /proc/$PID0 ] && die "PID0 $PID0 is no longer running!"
+[ ! -d /proc/$PID1 ] && die "PID1 $PID1 is no longer running!"
+
+export PATH=$PATH:/usr/sbin
+mkdir -p /var/run/netns
+ln -sf /proc/${PID0}/ns/net /var/run/netns/${NS0}
+ln -sf /proc/${PID1}/ns/net /var/run/netns/${NS1}
+
+info "Moving ${TYPE} link (${IP})"
+
+case "${TYPE}" in
+macvlan|macvtap|ipvlan|ipvtap|vlan)
+  ip -netns ${NS0} link add link ${IF0} name tmp$$ type ${TYPE} \
+    ${MODE:+mode ${MODE}} ${VLANID:+id ${VLANID}}
+  ip -netns ${NS0} link set tmp$$ netns ${NS1} name ${IF1}
+  ;;
+move)
+  ip -netns ${NS0} link set ${IF0} netns ${NS1} name ${IF1}
+  ;;
+esac
+
+info "Setting IP, ROUTE, and up state"
+ip -netns ${NS1} --force -b - <<EOF
+  ${IP:+addr add ${IP} dev ${IF1}}
+  link set ${IF1} up
+  ${ROUTE:+route add ${ROUTE} dev ${IF1}}
+EOF
+
+if [ "${TARGET}" ]; then
+  info "Adding NAT rule to ${TARGET}"
+  IPTABLES ${NS1} PREROUTING  -t nat -i ${IF1} -j DNAT --to-destination ${TARGET}
+  IPTABLES ${NS1} POSTROUTING -t nat -o ${IF1} -j SNAT --to-source ${IP%/*}
+fi
+
+info "Moved ${TYPE} link (${IP})"
+
+# /test/move-link.sh --verbose ipvlan enp6s0 host 1 2500144 --ip 192.168.88.32/24 --nat 10.0.1.2

package/old/net2dot.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env -S python3 -u
+
+# Copyright (c) 2021, Viasat, Inc
+# Licensed under MPL 2.0
+
+import re, sys, yaml
+
+NODE_PROPS = 'shape=box style=filled penwidth=1'
+CONTAINER_PROPS = 'fontsize = 12 style = filled fillcolor = "#e1d5e7" color = "#9673a6"'
+NETWORK_PROPS = '%s penwidth = 2' % CONTAINER_PROPS
+INTF_PROPS = 'width=0.1 height=0.1 fontsize=10 fillcolor="#ffbb9e" color="#d7db00"'
+SWITCH_PROPS = 'fontsize=12 style="rounded,filled" fillcolor="#dae8fc" color="#6c8ebf"'
+HOST_PROPS = 'fontsize=12 fillcolor="#f5f5f5" color="#666666"'
+
+def id(n):
+    return re.sub(r"-", "_", n)
+
+def intfText(cluster, intf):
+    name = intf.get('intf', intf.get('origName', intf.get('name')))
+    if name.startswith('DUMMY_'):
+        return '%s__%s [shape=point style=invis]' % (
+                id(cluster), id(name))
+    else:
+        ip = intf.get('ip', intf.get('opts', {}).get('ip', ''))
+        if ip: ip = "\\n%s" % ip
+        return '%s__%s [label="%s%s" %s]' % (
+                id(cluster), id(name), name, ip, INTF_PROPS)
+
+if __name__ == '__main__':
+
+    networkFile = sys.argv[1]
+    networkName = sys.argv[2]
+
+    netCfg = yaml.full_load(open(networkFile))
+    if 'services' in netCfg:
+        netService = re.sub(r'_1$', '', networkName)
+        netCfg = netCfg['services'][netService]['x-network']
+    mnCfg = netCfg['mininet-cfg']
+
+    links = []
+    containers = {}
+    containers[networkName] = {'nodes': []}
+    namespaces = {}
+
+    for link in netCfg.get('links', []):
+        l, r = link['left'], link['right']
+        clname, crname = l['container'], r['container']
+        ilname, irname = l['intf'], r['intf']
+        links.append([(clname, ilname), (crname, irname)])
+        for cname, intf in [(clname, l), (crname, r)]:
+            if cname not in containers:
+                containers[cname] = {'nodes': []}
+            containers[cname]['nodes'].append(intf)
+
+    for lk in mnCfg.get('links', []):
+        l, r = lk['left'], lk['right']
+        links.append([(networkName, l), (networkName, r)])
+
+    for s in mnCfg.get('switches', []):
+        namespaces[s['name']] = {'interfaces': [], 'type': 'switch', **s}
+    for h in mnCfg.get('hosts', []):
+        namespaces[h['name']] = {'interfaces': [], 'type': 'host', **h}
+
+    for i in mnCfg.get('interfaces', []):
+        nm, nd = i.get('origName', i['name']), i['node']
+        if nd in namespaces:
+            namespaces[nd]['interfaces'].append(i)
+        else:
+            links.append([(networkName, nm), (networkName, nd)])
+
+    # Make sure all namespaces have at least one interface so that
+    # they can be connected by edges (lhead, ltail)
+    for nsname, nsdata in namespaces.items():
+        if not nsdata['interfaces']:
+            nsdata['interfaces'].append({'name': 'DUMMY_%s' % nsname})
+
+    ###
+
+    print('digraph D {')
+    print('  splines = true;')
+    print('  compound = true;')
+    print('  node [%s];' % NODE_PROPS)
+
+    for cname, cdata in containers.items():
+        print('  subgraph cluster_%s {' % id(cname))
+        print('    label = "%s";' % cname)
+        if cname == networkName:
+            print('    %s;' % NETWORK_PROPS)
+        else:
+            print('    %s;' % CONTAINER_PROPS)
+        for node in cdata['nodes']:
+            print('    %s;' % intfText(node['container'], node))
+        # mininet/network interface is processed after container links
+        # so that the mininet/network definitions take precedence
+        if cname == networkName:
+            for nsname, nsdata in namespaces.items():
+                print('    subgraph cluster_%s__%s {' % (
+                    id(cname), id(nsname)))
+                print('      label = "%s";' % nsname)
+                if nsdata['type'] == 'switch':
+                    print('      %s;' % SWITCH_PROPS)
+                else:
+                    print('      %s;' % HOST_PROPS)
+                for intf in nsdata['interfaces']:
+                    print('      %s;' % intfText(cname, intf))
+                print('    }')
+        print("  }")
+
+    for ((lc, ln), (rc, rn)) in links:
+        extra=''
+        if lc == networkName and ln in namespaces:
+            iname = namespaces[ln]['interfaces'][0]['name']
+            extra += ' ltail=cluster_%s__%s' % (id(networkName), id(ln))
+            ln = id(iname)
+        if rc == networkName and rn in namespaces:
+            iname = namespaces[rn]['interfaces'][0]['name']
+            extra += ' lhead=cluster_%s__%s' % (id(networkName), id(rn))
+            rn = id(iname)
+        print('  %s__%s -> %s__%s [dir=none%s];' % (
+            id(lc), id(ln), id(rc), id(rn), extra))
+
+    print("}")

package/old/notes-old.txt

@@ -0,0 +1,97 @@
+- MVP for ViaBox:
+    - [x] compose/x-network file loading
+    - [x] multiple config sources and merging
+    - [x] link route config
+    - [x] filtering on project and workdir
+    - [x] interface and MAC iteration
+    - [x] variable templating
+    - [ ] *vlan type interfaces
+
+- Near term:
+    - [ ] dummy interfaces
+    - [ ] schema validation
+    - [ ] tc/qdisc settings
+    - [ ] arbitrary container commands
+
+- Further term:
+    - [ ] CNI networking support
+    - [ ] tunnel interfaces
+    - [ ] multiple routes
+    - [ ] ovs flow config
+    - [ ] Multiple bridge-modes
+        - bridge-mode as part of the domain definition so that the
+          same conlink instances can support multiple bridge modes
+          simultaneously (with a default for links that don't
+          specify).
+    - [ ] CNI model:
+        - conlink runs in container listening for events on a UDS
+          (intead of docker events)
+        - an outer conlink command is the CNI client that formats
+          events to send over the UDS to the inner conlink
+
+- Also see schema-ish.yaml
+links:
+  - type: TYPE         # Default: domain.
+                       # Others: dummy, tunnel, host, *vlan, etc
+
+    domain: DOMAIN     # ovs switch name
+
+    container: FOO     # full container name
+      # OR
+    service: FOO       # compose service name
+
+    interface: INTF    # internal container interface name
+
+    # --- optional general ---
+
+    ip(s): IP          # starting address, can include net slash to limit max
+    mac: MAC
+    mtu: MTU
+    route(s): ROUTE    # `ip route add ROUTE`, maybe add "dev INTF" automatically
+    tc(s): TC          # tc/qdisc commands/settings
+    flow(s): FLOW      # `ovs-ofctl add-flow DOMAIN FLOW`. With var templating.
+    command(s): CMD    # arbitrary shell cmd. After all links setup for this container
+
+    # --- optional for 'type:' links ---
+
+    host-intf: INTF    # host interface to *vlan or move in
+    mode: MODE         # bridge, etc
+    vlanid: VLANID     # VLAN #
+    nat: NAT           # nat target
+
+
+- type maps to 'ip link' type with default of 'veth'
+- 
+- when type is 'veth', then base default is 'conlink'
+- when type is 'veth' and base is 'conlink', then bridge is required.
+
+- conlink veth link: {type: veth [DEFAULT], base: conlink [DEFAULT], bridge: BRIDGE, dev: DEV}
+
+
+
+Dependencies in python version:
+- argparse
+- shlex (parsing commands)
+- compose_interpolation import TemplateWithDefaults
+- cerberus import Validator
+    - options: joi, ajv, json-schema, and z-schema.
+- docker
+- psutil (pid_exists)
+- json
+- yaml
+- mininet
+
+
+- [deprecated idea] conlink sub-commands:
+    conlink spit
+        - output override docker-compose file with conlink service
+        - figure out volume mounts to get to other compose file(s)
+    conlink dc up ...
+        - generate override docker-compose file with conlink service
+        - run the compose command with override file
+    conlink start 
+        - start inside compose
+    conlink run
+        - start outside compose
+
+

package/old/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "conlink",
+  "dependencies": {
+    "@exodus/schemasafe": "^1.3.0",
+    "ajv": "^8.12.0",
+    "dockerode": "^3.3.4",
+    "joi": "^17.10.2",
+    "nbb": "^1.2.178",
+    "neodoc": "^2.0.2",
+    "yaml": "^2.2.1"
+  },
+  "devDependencies": {
+    "shadow-cljs": "^2.25.7",
+    "source-map-support": "^0.5.21"
+  }
+}

package/old/schema.yaml

@@ -0,0 +1,138 @@
+links:
+  type: list
+  schema:
+    type: dict
+    schema:
+      left:
+        type: dict
+        required: true
+        schema:
+          container: {type: string, required: true}
+          intf:      {type: string, required: true}
+          ip:        {type: string, required: false,
+                      regex: '([0-9]+\.){3}[0-9]+\/[0-9]+'}
+          mac:       {type: string, required: false,
+                      regex: '([0-9A-Fa-f][0-9A-Fa-f]:){5}[0-9A-Fa-f][0-9A-Fa-f]'}
+      right:
+        type: dict
+        required: true
+        schema:
+          container: {type: string, required: true}
+          intf:      {type: string, required: true}
+          ip:        {type: string, required: false,
+                      regex: '([0-9]+\.){3}[0-9]+\/[0-9]+'}
+          mac:       {type: string, required: false,
+                      regex: '([0-9A-Fa-f][0-9A-Fa-f]:){5}[0-9A-Fa-f][0-9A-Fa-f]'}
+
+tunnels:
+  type: list
+  schema:
+    type: dict
+    schema:
+      type:      {type: string, required: true}
+      intf:      {type: string, required: true}
+      vni:       {type: number, required: true}
+      remote:    {type: string, required: true,
+                  regex: '([0-9]+\.){3}[0-9]+'}
+      ip:        {type: string, required: false,
+                  regex: '([0-9]+\.){3}[0-9]+\/[0-9]+'}
+      mac:       {type: string, required: false,
+                  regex: '([0-9A-Fa-f][0-9A-Fa-f]:){5}[0-9A-Fa-f][0-9A-Fa-f]'}
+      link_args: {type: string, required: false}
+
+interfaces:
+  type: list
+  schema:
+    type: dict
+    required: true
+    schema:
+      type:      {type: string, required: true,
+                  allowed: [link, vlan, macvlan, macvtap, ipvlan, ipvtap]}
+      container: {type: string, required: true}
+      host-intf: {type: string, required: true}
+      intf:      {type: string, required: true}
+      mode:      {type: string, required: false,
+                  dependencies: {type: [macvlan, macvtap, ipvlan, ipvtap]}}
+      vlanid:    {type: number, required: false,
+                  dependencies: {type: [vlan]}}
+      ip:        {type: string, required: false,
+                  regex: '([0-9]+\.){3}[0-9]+\/[0-9]+'}
+      nat:       {type: string, required: false,
+                  regex: '([0-9]+\.){3}[0-9]+',
+                  dependencies: ip}
+
+network-settings: {type: string}
+
+commands:
+  type: list
+  schema:
+    type: dict
+    schema:
+      container: {type: string, required: true}
+      command:
+        required: true
+        oneof: [ {type: string}, {type: list, schema: {type: string}} ]
+
+mininet-cfg:
+  type: dict
+  schema:
+
+    switches:
+      type: list
+      required: false
+      schema:
+        type: dict
+        schema:
+          name: {type: string, required: true}
+          opts: {type: dict,   required: false}
+
+    hosts:
+      type: list
+      required: false
+      schema:
+        type: dict
+        schema:
+          name: {type: string, required: true}
+          opts: {type: dict,   required: false}
+
+    containers:
+      type: list
+      required: false
+      schema:
+        type: dict
+        schema:
+          name: {type: string, required: true}
+          opts: {type: dict,   required: false}
+
+    links:
+      type: list
+      required: false
+      schema:
+        type: dict
+        schema:
+          left:  {type: string, required: true}
+          right: {type: string, required: true}
+          opts:  {type: dict,   required: false}
+
+    interfaces:
+      type: list
+      required: false
+      schema:
+        type: dict
+        schema:
+          node:     {type: string, required: true}
+          name:     {type: string, required: true}
+          origName: {type: string, required: false}
+          opts:     {type: dict,   required: false}
+
+    commands:
+      type: list
+      required: false
+      schema:
+        type: dict
+        schema:
+          node: {type: string,  required: true}
+          sync: {type: boolean, required: false}
+          command:
+            required: true
+            oneof: [ {type: string}, {type: list, schema: {type: string}} ]