conlink 2.0.3 → 2.2.0

package/.github/workflows/push.yml

@@ -13,5 +13,12 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: stub step
-        run: "echo stub stub"
+      - name: npm install
+        run: npm install
+
+      - name: compose build of conlink
+        run: docker compose -f examples/test1-compose.yaml build
+
+      - name: "./run-tests.sh"
+        timeout-minutes: 5
+        run: time ./run-tests.sh

package/Dockerfile

@@ -24,11 +24,11 @@ FROM node:16-slim as run
 RUN apt-get -y update
 # Runtime deps and utilities
 RUN apt-get -y install libpcap-dev tcpdump iproute2 iputils-ping curl \
-                       iptables bridge-utils \
+                       iptables bridge-utils ethtool \
                        openvswitch-switch openvswitch-testcontroller
 
 COPY --from=build /app/ /app/
-ADD link-add.sh link-del.sh /app/
+ADD link-add.sh link-del.sh link-mirred.sh link-forward.sh /app/
 ADD schema.yaml /app/build/
 
 ENV PATH /app:$PATH

package/README.md

@@ -13,6 +13,8 @@ General:
 Other:
 * For Open vSwtich (OVS) bridging, the `openvswitch` kernel module
   must loaded on the host system (where docker engine is running).
+* For patch connections (`bridge: patch`), the kernel must support
+  tc qdisc mirred filtering via the `act_mirred` kernel module.
 * For podman usage (e.g. second part of `test3`), podman is required.
 * For remote connections/links (e.g. `test5`), the `geneve` (and/or
   `vxlan`) kernel module must be loaded on the host system (where
@@ -44,17 +46,28 @@ will also be required for the conlink container. In particular, if the
 container uses systemd, then it will likely use `SYS_NICE` and
 `NET_BROADCAST` and conlink will likewise need those capabilities.
 
-### Bridging: Open vSwtich/OVS or Linux bridge
-
-Conlink creates bridges/switches and connects veth container links to
-those bridges (specified by `bridge:` in the link specification).
-By default, conlink will attempt to create Open vSwitch/OVS bridges
-for these connections, however, if the kernel does not provide support
-(`openvswitch` kernel module loaded), then conlink will fallback to
-using standard Linux bridges. The fallback behavior can be changed by
-setting the `--bridge-mode` option to either "ovs" or "linux". If the
-bridge mode is set to "ovs" then conlink will fail to start if the
-`openvswitch` kernel module is not detected.
+### Bridging: Open vSwtich/OVS, Linux bridge, and patch
+
+Conlink connects container veth links together via a bridge or via a
+direct patch. All veth type links must have a `bridge` property that
+defines which links will be connected together (i.e. the same
+broadcast domain). The default bridge mode is defined by the
+`--default-bridge-mode` parameter and defaults to "auto". If a bridge
+is set to mode "auto" then conlink will check if the kernel has the
+`openvswitch` kernel module loaded and if so it will create an Open
+vSwitch/OVS bridge/switch for that bridge, otherwise it will create a
+regular Linux bridge (e.g. brctl). If any bridges are explicitly
+defined with an "ovs" mode and the kernel does not have support then
+conlink will stop/error on startup.
+
+The "patch" mode will connect two links together using tc qdisc
+ingress filters. This type connection is equivalent to a patch panel
+("bump-in-the-wire") connection and all traffic will be passed between
+the two links unchanged unlike Linux and OVS bridges which typically
+block certain bridge control broadcast traffic). The primary downside
+of "patch" connections is that they limited to two links whereas "ovs"
+and "linux" bridge modes can support many links connected into the
+same bridge (broadcast domain).
 
 ## Network Configuration Syntax
 
@@ -79,28 +92,31 @@ interfaces in the host.
 
 The following table describes the link properties:
 
-| property  | link types | format     | default | description              |
-|-----------|------------|------------|---------|--------------------------|
-| type      | *          | string 1   | veth    | link/interface type      |
-| service   | *          | string     | 2       | compose service          |
-| container | *          | string     |         | container name           |
-| bridge    | veth       | string     |         | conlink bridge / domain  |
-| outer-dev | not dummy  | string[15] |         | conlink/host intf name   |
-| dev       | *          | string[15] | eth0    | container intf name      |
-| ip        | *          | CIDR       |         | IP CIDR (index offset)   |
-| mac       | 3          | MAC        |         | MAC addr (index offset)  |
-| mtu       | *          | number 4   | 9000    | intf MTU                 |
-| route     | *          | string     |         | ip route add args        |
-| nat       | *          | IP         |         | DNAT/SNAT to IP          |
-| netem     | *          | string     |         | tc qdisc NetEm options   |
-| mode      | 5          | string     |         | virt intf mode           |
-| vlanid    | vlan       | number     |         | VLAN ID                  |
+| property  | link types | format         | default | description              |
+|-----------|------------|----------------|---------|--------------------------|
+| type      | *          | string 1       | veth    | link/interface type      |
+| service   | *          | string         | 2       | compose service          |
+| container | *          | string         |         | container name           |
+| bridge    | veth       | string         |         | conlink bridge / domain  |
+| outer-dev | not dummy  | string[15]     |         | conlink/host intf name   |
+| dev       | *          | string[15]     | eth0    | container intf name      |
+| ip        | *          | CIDR           |         | IP CIDR 7                |
+| mac       | 3          | MAC            |         | MAC addr 7               |
+| mtu       | *          | number 4       | 65535   | intf MTU                 |
+| route     | *          | string         |         | ip route add args        |
+| nat       | *          | IP             |         | DNAT/SNAT to IP          |
+| netem     | *          | string         |         | tc qdisc NetEm options   |
+| mode      | 5          | string         |         | virt intf mode           |
+| vlanid    | vlan       | number         |         | VLAN ID                  |
+| forward   | veth       | string array 6 |         | forward conlink ports 7  |
 
 - 1 - veth, dummy, vlan, ipvlan, macvlan, ipvtap, macvtap
 - 2 - defaults to outer compose service
 - 3 - not ipvlan/ipvtap
 - 4 - max MTU of parent device for \*vlan, \*vtap types
 - 5 - macvlan, macvtap, ipvlan, ipvtap
+- 6 - string syntax: `conlink_port:container_port/proto`
+- 7 - offset by scale/replica index
 
 Each link has a 'type' key that defaults to "veth" and each link
 definition must also have either a `service` key or a `container` key.
@@ -122,6 +138,33 @@ than the MTU of the parent (outer-dev) device.
 For the `netem` property, refer to the `netem` man page. The `OPTIONS`
 grammar defines the valid strings for the `netem` property.
 
+The `forward` property is an array of strings that defines ports to
+forward from the conlink container into the container over this link.
+Traffic arriving on the conlink container's docker interface of type
+`proto` and destined for port `conlink_port` is forwarded over this
+link to the container IP and port `container_port` (`ip` is required).
+The initial port (`conlink_port`) is offset by the service
+replica/scale number (minus 1). So if the first replica has port 80
+forwarded then the second replica will have port 81 forwarded.
+For publicly publishing a port, the conlink container needs to be on
+a docker network and the `conlink_port` should match the target port
+of a docker published port (for the conlink container).
+
+### Bridges
+
+The bridge settings currently only support the "mode" setting. If
+the mode is not specified in this section or the section is omitted
+entirely, then bridges specified in the links configuration will
+default to the value of the `--default-bridge-mode` parameter (which
+itself defaults to "auto").
+
+The following table describes the bridge properties:
+
+| property  | format  | description                    |
+|-----------|---------|--------------------------------|
+| bridge    | string  | conlink bridge / domain name   |
+| mode      | string  | auto, ovs, or linux            |
+
 ### Tunnels
 
 Tunnels links/interfaces will be created and attached to the specified
@@ -421,8 +464,10 @@ Start the test7 compose configuration:
 docker-compose -f examples/test7-compose.yaml up --build --force-recreate
 ```
 
-Show the links in both node containers to see that the MAC addresses
-are `00:0a:0b:0c:0d:0*` and the MTUs are set to `4111`.
+Show the links in both node containers to see that on the eth0
+interfaces the MAC addresses are `00:0a:0b:0c:0d:0*` and the MTUs are
+set to `4111`. The eth1 interfaces should have the command line set
+default MTU of `5111`.
 
 ```
 docker-compose -f examples/test7-compose.yaml exec --index 1 node ip link
@@ -476,6 +521,67 @@ Note: to connect to the vlan node (NODE2_HOST_ADDRESS) you will need
 to configure your physical switch/router with routing/connectivity to
 VLAN 5 on the same physical link to your host.
 
+### test9: bridge modes
+
+This example demonstrates the supported bridge modes.
+
+Start the test9 compose configuration using different bridge modes and
+validate connectivity using ping:
+
+```
+export BRIDGE_MODE="linux"  # "ovs", "patch", "auto"
+docker-compose -f examples/test9-compose.yaml up --build --force-recreate
+docker-compose -f examples/test9-compose.yaml exec node ping 10.0.1.2
+```
+
+### test10: port forwarding
+
+This example demonstrates port forwarding from the conlink container
+to two containers running simple web servers.
+
+Start the test10 compose configuration:
+
+```
+docker-compose -f examples/test10-compose.yaml up --build --force-recreate
+```
+
+Ports 3080 and 8080 are both published on the host by the conlink
+container using standard Docker port mapping. The internal mapping of
+those ports (1080 and 1180 respectively) are both are forwarded to
+port 80 in the node1 container using conlink's port forwarding
+mechanism. The two paths look like this:
+
+```
+host:3080 --> 1080 (in conlink) --> node1:80
+host:8080 --> 1180 (in conlink) --> node1:80
+```
+
+Use curl on the host to query both of these paths to node1:
+
+```
+curl 0.0.0.0:3080
+curl 0.0.0.0:8080
+```
+
+Ports 80 and 81 are published on the host by the conlink container
+using standard Docker port mapping. Then conlink forwards from ports
+80 and 81 to the first and second replica (respectively) of node2,
+each of which listen internally on port 80. The two paths look like
+this:
+
+```
+host:80 -> 80 (in conlink) -> node2_1:80
+host:81 -> 81 (in conlink) -> node2_2:80
+```
+
+Use curl on the host to query both replicas of node2:
+
+```
+curl 0.0.0.0:80
+curl 0.0.0.0:81
+```
+
+
 ## GraphViz network configuration rendering
 
 You can use d3 and GraphViz to create a visual graph rendering of

package/examples/test10-compose.yaml

@@ -0,0 +1,38 @@
+version: "2.4"
+
+services:
+  node1:
+    image: python:3-alpine
+    network_mode: none
+    command: "python3 -m http.server -d /var 80"
+    x-network:
+      links:
+        - {bridge: s2, ip: "10.0.1.1/24", route: "default",
+           forward: ["1080:80/tcp", "1180:80/tcp"]}
+
+  node2:
+    image: python:3-alpine
+    network_mode: none
+    scale: 2
+    command: "python3 -m http.server -d /usr 80"
+    x-network:
+      links:
+        - {bridge: s1, ip: "10.0.2.1/24", route: "default",
+           forward: ["80:80/tcp"]}
+
+  network:
+    build: {context: ../}
+    image: conlink
+    pid: host
+    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
+    ports:
+      - "3080:1080/tcp"
+      - "8080:1180/tcp"
+      - "80:80/tcp"
+      - "81:81/tcp"
+    command: /app/build/conlink.js --compose-file /test/examples/test10-compose.yaml

package/examples/test4-multiple/modes/web/compose.yaml

@@ -1,5 +1,10 @@
 version: "2.4"
 
+services:
+  r0:
+    volumes:
+      - ./scripts:/scripts
+
 x-network:
   commands:
     - {service: r0, command: "python3 -m http.server 80"}

package/examples/test7-compose.yaml

@@ -15,7 +15,7 @@ services:
       - /var/run/docker.sock:/var/run/docker.sock
       - /var/lib/docker:/var/lib/docker
       - ./:/test
-    command: /app/build/conlink.js --compose-file /test/test7-compose.yaml
+    command: /app/build/conlink.js --default-mtu 5111 --compose-file /test/test7-compose.yaml
 
   node:
     image: alpine
@@ -29,3 +29,6 @@ services:
           mac: 00:0a:0b:0c:0d:01
           mtu: 4111
           netem: "delay 40ms rate 10mbit"
+        - bridge: s2
+          ip: 100.0.1.1/16
+          dev: eth1

package/examples/test9-compose.yaml

@@ -0,0 +1,32 @@
+# This file demonstrates using different bridge modes and
+# usage of the --default-brige-mode parameter.
+
+version: "2.4"
+
+services:
+  network:
+    build: {context: ../}
+    image: conlink
+    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
+    environment:
+      - BRIDGE_MODE
+    command: /app/build/conlink.js --default-bridge-mode linux --compose-file /test/test9-compose.yaml
+
+  node:
+    image: alpine
+    network_mode: none
+    scale: 2
+    command: sleep Infinity
+
+x-network:
+  links:
+    - {bridge: s1, service: node, ip: 10.0.1.1/24}
+  bridges:
+    - {bridge: s1, mode: "${BRIDGE_MODE:-auto}"}

package/link-add.sh

@@ -45,6 +45,8 @@ usage () {
   echo >&2 ""
   echo >&2 "  --netem NETEM            - tc qdisc netem OPTIONS (man 8 netem)"
   echo >&2 "  --nat TARGET             - Stateless NAT traffic to/from TARGET"
+  echo >&2 "                             (in primary/PID0 netns)"
+  echo >&2 ""
   exit 2
 }
 

package/link-forward.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+# Copyright (c) 2024, Equinix, Inc
+# Licensed under MPL 2.0
+
+set -e
+
+usage () {
+  echo >&2 "${0} [OPTIONS] <add|del> INTF_A INTF_B PORT_A:IP:PORT_B/PROTO"
+  echo >&2 ""
+  echo >&2 "Match traffic on INTF_A that has destination port PORT_A and"
+  echo >&2 "protocol PROTO (tcp or udp). Forward/DNAT traffic to IP:PORT_B "
+  echo >&2 "via INTF_B."
+  exit 2
+}
+
+info() { echo "link-forward [${LOG_ID}] ${*}"; }
+
+IPTABLES() {
+  case "${action}" in
+    add) iptables -C "${@}" 2>/dev/null || iptables -I "${@}" ;;
+    del) iptables -D "${@}" 2>/dev/null || true;;
+  esac
+}
+
+action=$1; shift || usage
+intf_a=$1; shift || usage
+intf_b=$1; shift || usage
+spec=$1;   shift || usage
+read port_a ip port_b proto <<< "${spec//[:\/]/ }"
+
+[ "${action}" -a "${intf_a}" -a "${intf_b}" ] || usage
+[ "${port_a}" -a "${ip}" -a "${port_b}" -a "${proto}" ] || usage
+
+LOG_ID="${spec}"
+
+info "${action^} forwarding ${intf_a} -> ${intf_b}"
+
+IPTABLES PREROUTING -t nat -i ${intf_a} -p ${proto} --dport ${port_a} -j DNAT --to-destination ${ip}:${port_b}
+IPTABLES POSTROUTING -t nat -o ${intf_b} -j MASQUERADE
+
+case "${action}" in
+  add) ip route replace ${ip} dev ${intf_b} ;;
+  del) ip route delete ${ip} dev ${intf_b} || true;;
+esac

package/link-mirred.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+
+# Copyright (c) 2024, Equinix, Inc
+# Licensed under MPL 2.0
+
+set -e
+
+usage () {
+  echo >&2 "${0} [OPTIONS] INTF0 INTF1"
+  echo >&2 ""
+  echo >&2 "Create traffic mirror/redirect between INTF0 and INTF1."
+  echo >&2 ""
+  echo >&2 "Positional arguments:"
+  echo >&2 "  INTF0 is the first interface name"
+  echo >&2 "  INTF1 is the second interface name"
+  echo >&2 ""
+  echo >&2 "INTF0 must exist, but if INTF1 is missing, then exit with 0."
+  echo >&2 "Each interface will be checked for correct ingress/mirred config"
+  echo >&2 "and configured if the configuration is missing."
+  echo >&2 "These two aspect make this script idempotent. It can be called"
+  echo >&2 "whenever either interface appears and when the second appears,"
+  echo >&2 "the mirror/redirect action will be setup fully/bidirectionally."
+  echo >&2 ""
+  echo >&2 "OPTIONS:"
+  echo >&2 "  --verbose                - Verbose output (set -x)"
+  exit 2
+}
+
+info() { echo "link-mirred [${LOG_ID}] ${*}"; }
+warn() { >&2 echo "link-mirred [${LOG_ID}] ${*}"; }
+die()  { warn "ERROR: ${*}"; exit 1; }
+
+# Idempotently add ingress qdisc to an interface
+add_ingress() {
+  local IF=$1 res=
+
+  res=$(tc qdisc show dev ${IF} 2>&1)
+  case "${res}" in
+    *"qdisc ingress ffff:"*)
+      info "${IF0} already has ingress qdisc"
+      ;;
+    ""|*"qdisc noqueue"*)
+      info "Adding ingress qdisc to ${IF}"
+      tc qdisc add dev "${IF}" ingress \
+        || die "Could not add ingress qdisc to ${IF}"
+      ;;
+    *)
+      die "${IF} has invalid ingress qdisc or could not be queried"
+      ;;
+  esac
+}
+
+# Idempotently add mirred filter redirect rule to an interface
+add_mirred() {
+  local IF0=$1 IF1=$2 res=
+
+  res=$(tc filter show dev ${IF0} parent ffff: 2>&1)
+  case "${res}" in
+    *"action order 1: mirred (Egress Redirect to device ${IF1}"*)
+      info "${IF0} already has filter redirect action"
+      ;;
+    "")
+      info "Adding filter redirect action from ${IF0} to ${IF1}"
+      tc filter add dev ${IF0} parent ffff: protocol all u32 match u8 0 0 action \
+        mirred egress redirect dev ${IF1} \
+        || die "Could not add filter redirect action from ${IF0} to ${IF1}"
+      ;;
+    *)
+      die "${IF0} has invalid filter redirect action or could not be queried"
+      ;;
+  esac
+}
+
+# Parse arguments
+VERBOSE=${VERBOSE:-}
+positional=
+while [ "${*}" ]; do
+  param=$1; OPTARG=$2
+  case ${param} in
+  --verbose)        VERBOSE=1 ;;
+  -h|--help)        usage ;;
+  *)                positional="${positional} $1" ;;
+  esac
+  shift
+done
+set -- ${positional}
+IF0=$1 IF1=$2
+
+[ "${VERBOSE}" ] && set -x || true
+
+# Sanity check arguments
+[ "${IF0}" -a "${IF1}" ] || usage
+
+LOG_ID="mirred ${IF0}:${IF1}"
+
+# Sanity checks
+if ! ip link show ${IF0} >/dev/null; then
+  die "${IF0} does not exist"
+fi
+if ! ip link show ${IF1} >/dev/null; then
+  info "${IF1} missing, exiting"
+  exit 0
+fi
+
+### Do the work
+
+info "Creating filter rediction action between ${IF0} and ${IF1}"
+
+add_ingress ${IF0}
+add_ingress ${IF1}
+add_mirred ${IF0} ${IF1}
+add_mirred ${IF1} ${IF0}
+
+info "Created filter rediction action between ${IF0} and ${IF1}"

package/mdc

@@ -17,6 +17,7 @@ LS=$(which ls)
 RESOLVE_DEPS="${RESOLVE_DEPS-./node_modules/@lonocloud/resolve-deps/resolve-deps.py}"
 DOCKER_COMPOSE="${DOCKER_COMPOSE:-docker-compose}"
 
+[ -f "${RESOLVE_DEPS}" ] || die "Missing ${RESOLVE_DEPS}. Perhaps 'npm install'?"
 MODE_SPEC="${1}"; shift
 if [ "${RESOLVE_DEPS}" ]; then
     MODES="$(${RESOLVE_DEPS} "${MODES_DIR}" ${MODE_SPEC})"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conlink",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "conlink -  Declarative Low-Level Networking for Containers",
   "repository": "https://github.com/LonoCloud/conlink",
   "license": "SEE LICENSE IN LICENSE",