conlink 2.5.2 → 2.5.4

package/docs/reference/network-configuration-syntax.md

@@ -0,0 +1,143 @@
+# Network Configuration Syntax
+
+Network configuration can either be loaded directly from configuration
+files using the `--network-config` option or it can be loaded from
+`x-network` properties contained in docker-compose files using the
+`--compose-file` option. Multiple of each option may be specified and
+all the network configuration will be merged into a final network
+configuration. Both options also support colon separated lists.
+
+The network configuration can have four top level keys: `links`,
+`bridges`, `tunnels`, and `commands`.
+
+## Links
+
+Each link defintion specifies an interface that will be configured in
+a container. Most types have some sort of connection to either the
+conlink/network container or the host network namespace. For example,
+"veth" type links always have their peer end connected to a bridge in
+the conlink/network container and vlan types are children of physical
+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 7                |
+| mac       | 3          | MAC            |         | MAC addr 7               |
+| mtu       | *          | number 4       | 65535   | intf MTU                 |
+| route     | *          | strings 8      |         | ip route add args        |
+| nat       | *          | IP             |         | DNAT/SNAT to IP          |
+| netem     | *          | strings 8      |         | tc qdisc NetEm options   |
+| mode      | 5          | string         |         | virt intf mode           |
+| vlanid    | vlan       | number         |         | VLAN ID                  |
+| forward   | veth       | strings 6 8    |         | forward conlink ports 7  |
+| ethtool   | veth       | strings 8      |         | ethtool settings         |
+
+- 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
+- 8 - either a single string or an array of strings
+
+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.
+If the link is defined in the service of a compose file then the value
+of `service` will default to the name of that service.
+
+The `container` key is a fully qualified container name that this link
+will apply to. The `service` key is the name of a docker-compose
+service that this link applies to. In the case of a `service` link, if
+more than one replica is started for that service, then the mac, and
+ip values in the link definition will be incremented by the service
+index - 1.
+
+All link definitions support the following optional properties: dev,
+ip, mtu, route, nat, netem. If dev is not specified then it will
+default to "eth0".  For `*vlan` type interfaces, mtu cannot be larger
+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).
+
+For the `ethtool` property, refer to the `ethtool` man page. The
+syntax for each ethtool setting is basically the ethtool command line
+arguments without the "devname. So the equivalent of the ethtool
+command `ethtool --offload eth0 rx off` would be link configuration
+`{dev: eth0, ethtool: ["--offload rx off"], ...}`.
+
+## 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
+bridge. Any containers with links to the same bridge will share
+a broadcast domain with the tunnel link.
+
+The following table describes the tunnel properties:
+
+| property  | format  | description                |
+|-----------|---------|----------------------------|
+| type      | string  | geneve or vxlan            |
+| bridge    | string  | conlink bridge / domain    |
+| remote    | IP      | remote host addr           |
+| vni       | number  | Virtual Network Identifier |
+| netem     | string  | tc qdisc NetEm options     |
+
+Each tunnel definition must have the keys: type, bridge, remote, and
+vni. The netem optional property also applies to tunnel interfaces.
+
+## Commands
+
+Commands will be executed in parallel within the matching container
+once all links are succesfully configured for that container.
+
+The following table describes the command properties:
+
+| property  | format           | description                |
+|-----------|------------------|----------------------------|
+| service   | string           | compose service            |
+| container | string           | container name             |
+| command   | array or string  | command or shell string    |
+
+Each command defintion must have a `command` key and either
+a `service` or `container` key. The `service` and `container` keys are
+defined the same as for link properties.
+
+If the `command` value is an array then the command and arguments will
+be executed directly. If the `command` is a string then the string
+will be wrapped in `sh -c STRING` for execution.

package/docs/usage-notes.md

@@ -0,0 +1,50 @@
+# Usage Notes
+
+Conlink runs as another container in the Docker Compose project. As a
+result, there are some important things to know when using conlink
+instead of the default Docker Compose networking.
+
+## Asynchronous startup
+
+The conlink managed container links are created after the main process
+in the container starts executing. This is different from normal
+docker behavior where the interfaces are created and configured before
+the main process starts. This means the interfaces for those
+links will not be immediately present and the container process will
+need to account for this asynchronous interface behavior. The `node`
+service in `examples/test2-compose.yaml` shows a simple example of
+a container command that will wait for an interface to appear before
+continuing with another command.
+
+## System Capabilities/Permissions
+
+The conlink container needs to have a superset of the network related
+system capabilities of the containers that it will connect to. At
+a minimum `SYS_ADMIN` and `NET_ADMIN` are required but depending on
+what the other containers require then those additional capabilities
+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, 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).

package/mdc

@@ -22,6 +22,7 @@ which ${RESOLVE_DEPS} >/dev/null 2>/dev/null \
 
 # Resolve mode directory paths
 
+MDC_CLI="${0} ${*}"
 MODE_SPEC="${1}"; shift
 RESOLVED_MODES="$(${RESOLVE_DEPS} --path "${MODES_DIR}" --format=paths ${MODE_SPEC})"
 
@@ -29,8 +30,8 @@ RESOLVED_MODES="$(${RESOLVE_DEPS} --path "${MODES_DIR}" --format=paths ${MODE_SP
 # to the same root directory.  Create files dir.
 
 COMPOSE_FILE=./.compose-empty.yaml
-cat /dev/null > ${ENV_FILE}-mdc-tmp
-echo -e "version: '2.4'\nservices: {}" > ./.compose-empty.yaml
+echo "### mdc command line: ${MDC_CLI}" > ${ENV_FILE}-mdc-tmp
+echo -e "services: {}" > ./.compose-empty.yaml
 
 vecho "Removing ${MDC_FILES_DIR}"
 case "$(basename ${MDC_FILES_DIR})" in
@@ -73,6 +74,8 @@ for resolved in ${RESOLVED_MODES}; do
     for efile in ${efiles}; do
         if [ -e "${efile}" ]; then
             echo "### mdc begin mode ${mode} (${efile})" >> ${ENV_FILE}-mdc-tmp
+            # Add MDC_MODE_ prefixed environment variable for each mode
+            echo "MDC_MODE_${mode//[^a-zA-Z]/_}=enabled" >> ${ENV_FILE}-mdc-tmp
             vecho "cat ${efile} >> ${ENV_FILE}-mdc-tmp"
             cat ${efile} >> ${ENV_FILE}-mdc-tmp
             echo >> ${ENV_FILE}-mdc-tmp

package/net2dot.cljs

@@ -57,11 +57,12 @@
   (let [graph (digraph {:splines true :compound true})
         host (subgraph graph "cluster_host" "host system" HOST-PROPS)
         conlink (subgraph host "cluster_conlink" "conlink/network" CONLINK-PROPS)
+        links (->> network-config :services vals (map :links) (apply concat))
         bridges (reduce
                   #(->> (subgraph conlink (str "cluster_bridge_" %2)
                                   %2 BRIDGE-PROPS)
                         (assoc %1 %2))
-                  {} (map :bridge (keep :bridge (:links network-config))))
+                  {} (keys (:bridges network-config)))
         services (reduce
                    #(->> (subgraph host (str "cluster_service_" (dot-id %2))
                                    (str "service '" (name %2) "'") SVC-PROPS)
@@ -73,7 +74,7 @@
                            (assoc %1 %2))
                      {} (keys (:containers network-config)))]
 
-    (doseq [link (:links network-config)]
+    (doseq [link links]
       (let [{:keys [service container dev outer-dev bridge base]} link
             cname (or service container)
             cnode (get (if service services containers) (keyword cname))
@@ -85,7 +86,7 @@
                                    "-" (name dev)))
                 out-id (str "out-" outer-dev)
                 out-parent (condp = (keyword base)
-                             :conlink (get bridges (:bridge bridge))
+                             :conlink (get bridges (keyword (:bridge bridge)))
                              :host host)
                 {:keys [type vlanid]} link
                 [elabel iprops] (if (= "host" base)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conlink",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "conlink -  Declarative Low-Level Networking for Containers",
   "repository": "https://github.com/LonoCloud/conlink",
   "license": "SEE LICENSE IN LICENSE",
@@ -14,8 +14,12 @@
     "yaml": "^2.2.1"
   },
   "devDependencies": {
-    "@lonocloud/dctest": "0.1.1",
+    "@lonocloud/dctest": "^0.3.1",
+    "docsify-cli": "^4.4.4",
     "shadow-cljs": "^2.25.7",
     "source-map-support": "^0.5.21"
+  },
+  "scripts": {
+    "serve-docs": "docsify serve ./docs"
   }
 }

package/src/conlink/core.cljs

@@ -615,17 +615,9 @@ General Options:
   if no container ID can be determined (e.g. we are probably not
   running in a container)"
   []
-  (P/let [[cgroup mountinfo]
-          , (P/catch (P/all [(read-file "/proc/self/cgroup" "utf8")
-                             (read-file "/proc/self/mountinfo" "utf8")])
-              #(vector "" ""))
-          ;; docker
-          d-cgroups (map second (re-seq #"/docker/([^/\n]*)" cgroup))
-          ;; podman (root)
-          p-cgroups (map second (re-seq #"libpod-([^/.\n]*)" cgroup))
-          ;; general fallback
-          o-mounts (map second (re-seq #"containers/([^/]{64})/.*/etc/hosts" mountinfo))]
-    (first (concat d-cgroups p-cgroups o-mounts))))
+  (P/->> (P/catch (read-file "/proc/self/mountinfo" "utf8") (constantly ""))
+         (re-find #".*containers/([^/]{64})/.*/etc/hosts")
+         second))
 
 (defn list-containers
   "Return a sequence of container objects optionally limited to those
@@ -906,7 +898,7 @@ General Options:
      docker-eth0-addresses (when docker-eth0? (intf-ipv4-addresses "eth0"))
      _ (swap! ctx merge {:kmod-ovs? kmod-ovs?
                          :kmod-mirred? kmod-mirred?
-                         :docker-eth0? docker-eth0?
+                         :docker-eth0? (or docker-eth0? show-config)
                          :docker-eth0-address (first docker-eth0-addresses)})
      network-config (P/-> (load-configs compose-file network-file)
                           (interpolate-walk env)
@@ -979,7 +971,9 @@ General Options:
                (P/let
                  [event-filter {"event" ["start" "die"]}
                   ;; Listen for docker and/or podman events
-                  _ (docker-listen client event-filter handle-event)
+                  ;; NOTE: sometimes (podman on macos) this blocks
+                  ;; until the first event. Wrap it to skip await.
+                  _ [(docker-listen client event-filter handle-event)]
                   containers ^obj (list-containers client)]
                  ;; Generate fake events for existing containers
                  (P/all (for [container containers