From 8551038de70bae4edf96acb2a2f7bcdd32b42fa5 Mon Sep 17 00:00:00 2001 From: Phill <34226495+Paraphraser@users.noreply.github.com> Date: Thu, 5 Dec 2024 01:43:22 +1100 Subject: [PATCH] addresses documentation problems raised in issue 35 (#36) Responses to #35: 1. Revises `docker run` example: * places container in host mode * runs container detached (so it does not appear to stall) * passes the user and group IDs for the local user (so persistent storage is owned by the local user) * changes default mechanism for net-filter rules to `iptables-nft` * places image reference on a separate line 2. Revises `docker compose` service definition: * removes deprecated `version` clause, substituting the "here comes YAML" `---` signature * changes default mechanism for net-filter rules to `iptables-nft` 3. Re-writes explanation of `ZEROTIER_ONE_USE_IPTABLES_NFT` to make it clear that `true` is usually the correct option for all implementations (not just Raspberry Pi). Also adds explicit test to confirm that the container's net-filters are getting into the host's tables. Opportunistic changes: 1. Updates URLs for ZeroTier Knowledge Base article (avoids redirects when following those links). 2. Clarifies that it is the ZeroTier Knowledge Base article which implements a half-router, and summarises the additional capabilities of `zerotier-router`. 3. Adds cross-reference to IOTstack documentation (IMO this is more comprehensive than anything in the ZeroTier Knowledge Base). 4. Removes extraneous `0x09` characters. Fixes #35 Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> --- README-router.md | 86 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 59 insertions(+), 27 deletions(-) diff --git a/README-router.md b/README-router.md index 533d034..4bedc9f 100644 --- a/README-router.md +++ b/README-router.md @@ -4,24 +4,32 @@ This is a variation built on top of the zyclonite/zerotier container which implements a local network router. It is based upon the ZeroTier Knowledge Base article: -* [Route between ZeroTier and Physical Networks](https://zerotier.atlassian.net/wiki/spaces/SD/pages/224395274/Route+between+ZeroTier+and+Physical+Networks) +* [Route between ZeroTier and Physical Networks](https://docs.zerotier.com/route-between-phys-and-virt/) -Technically, this could be described as a *half-router*: +Technically, the above approach could be described as a *half-router*: * You can initiate connections *from* a remote client *to* devices on the LAN; but * You can't initiate connections *to* the remote client *from* devices on the LAN. +This implementation extends the concept so that you have a choice of: + +* Permitting remote clients to initiate connections with a devices on your LAN; or +* Permitting clients on your LAN to initiate connections with remote devices reachable across your ZeroTier Cloud network; or +* Both of the above (ie a full router). + ### Command line example ``` console $ docker run --name zerotier-one --device=/dev/net/tun \ + --network=host -d \ --cap-add=NET_ADMIN --cap-add=NET_RAW --cap-add=SYS_ADMIN \ - --env TZ=Etc/UTC --env PUID=999 --env PGID=994 \ + --env TZ=Etc/UTC --env PUID=$(id -u) --env PGID=$(id -g) \ --env ZEROTIER_ONE_LOCAL_PHYS=eth0 \ - --env ZEROTIER_ONE_USE_IPTABLES_NFT=false \ + --env ZEROTIER_ONE_USE_IPTABLES_NFT=true \ --env ZEROTIER_ONE_GATEWAY_MODE=inbound \ --env ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)» \ - -v /var/lib/zerotier-one:/var/lib/zerotier-one zyclonite/zerotier:router + -v /var/lib/zerotier-one:/var/lib/zerotier-one \ + zyclonite/zerotier:router ``` Note: @@ -35,7 +43,8 @@ Note: ### Compose file example ``` yaml -version: '3' +--- + services: zerotier: image: "zyclonite/zerotier:router" @@ -55,7 +64,7 @@ services: - PUID=999 - PGID=994 - ZEROTIER_ONE_LOCAL_PHYS=eth0 - - ZEROTIER_ONE_USE_IPTABLES_NFT=false + - ZEROTIER_ONE_USE_IPTABLES_NFT=true - ZEROTIER_ONE_GATEWAY_MODE=inbound # - ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)» ``` @@ -87,9 +96,9 @@ Note: - PUID=1000 - PGID=1000 ``` - + If omitted, `PUID` defaults to user ID 999, while `PGID` defaults to group ID 994. - + These variables are only used to ensure consistent ownership of persistent storage on each launch. They do not affect how the container *runs.* Absent a `user:` directive, the container runs as root and does not downgrade its privileges. * `ZEROTIER_ONE_LOCAL_PHYS` - a space-separated list of physical interfaces that should be configured to participate in NAT-based routing. Examples: @@ -107,31 +116,45 @@ Note: environment: - ZEROTIER_ONE_LOCAL_PHYS=wlan0 ``` - + - If your computer has both Ethernet and WiFi interfaces active and you wish to be able to route through each interface: - + ``` yaml environment: - ZEROTIER_ONE_LOCAL_PHYS=eth0 wlan0 ``` - + This scheme could be appropriate where the physical interfaces were: - + 1. In the same broadcast domain (subnet). Disconnecting Ethernet would fail-over to WiFi. 2. In different broadcast domains, such as if you allocated different subnets for Ethernet and WiFi. -* `ZEROTIER_ONE_USE_IPTABLES_NFT` - controls the command the container uses to set up NAT forwarding. Example: +* `ZEROTIER_ONE_USE_IPTABLES_NFT` - controls the command the container uses to set up net-filter rules to implement packet forwarding. Example: - ``` yaml - environment: - - ZEROTIER_ONE_USE_IPTABLES_NFT=true ``` - - - `false` means the container uses `iptables`. This is the default. - - `true` means the container uses `iptables-nft`. + environment: + - ZEROTIER_ONE_USE_IPTABLES_NFT=true + ``` + + * `false` means the container uses `iptables-legacy`. This is the default if the variable is omitted but that is only to maintain backwards compatibility. + * `true` means the container uses `iptables-nft`. This is *generally* what you need. + + The way to be absolutely certain is to start the container and then run the following command: + + ``` console + $ sudo nft list ruleset | grep -c "zt*" + ``` + + Ignore any lines that start with the `#` character. + + There are three possible responses: + + 1. An error saying that the `nft` command has not been found. Docker uses `iptables-nft` to construct its own net-filter rules so it installs the `iptables` package as a dependency which, in turn, installs `nftables` as its own dependency. For that reason, not being able to find the `nft` command generally indicates an improper installation of Docker. + 2. A line-count of zero. This means the container has not been able to configure net-filter rules on the host. If that happens, try the opposite setting for this environment variable (eg `true` instead of `false`). + 3. A non-zero line-count. That means the container has been able to propagate net-filter rules into the host's tables, which is what you want. The actual number is not important, just something other than zero. + + The container will always come up. Once you've authorised the client in ZeroTier Central, it will be able to join your ZeroTier Cloud network. Tests like `ping` and `traceroute` that you run on the same host will always work. However, if the container is not able to propagate its net-filter rules into the host's tables, traffic *beyond* the host where the container is running will not work properly. The problem is quite subtle so it's always a good idea to check that the host has the expected net-filters. - Try `true` if NAT does not seem to be working. This is needed on Raspberry Pi Bullseye. - * `ZEROTIER_ONE_GATEWAY_MODE` - controls the traffic direction. Examples: - Only permit traffic *from* the ZeroTier cloud *to* the local physical interfaces: @@ -140,7 +163,7 @@ Note: environment: - ZEROTIER_ONE_GATEWAY_MODE=inbound ``` - + - Only permit traffic *from* the local physical interfaces *to* the ZeroTier cloud: ``` yaml @@ -156,18 +179,18 @@ Note: ``` Defaults to `inbound` if omitted. Note that you will probably need one or more static routes configured in your local LAN router so that traffic originating in a local host which is not running the ZeroTier client can be directed to the gateway host. - + * `ZEROTIER_ONE_NETWORK_IDS` – a space-separated list of ZeroTier network IDs. This variable is *only* effective on first launch. There is no default if it is omitted. Examples: - + - to join a single network: ``` yaml environment: - ZEROTIER_ONE_NETWORK_IDS=aaaaaaaaaaaaaaaa ``` - + Equivalent of running the following command after the container first starts: ``` @@ -194,6 +217,15 @@ Note: For each ZeroTier container that is configured as a router, ZeroTier needs at least one *Managed Route*. -The [ZeroTier Wiki](https://zerotier.atlassian.net/wiki/spaces/SD/pages/224395274/Route+between+ZeroTier+and+Physical+Networks#Configure-the-ZeroTier-managed-route) explains how to design managed routes. +The [ZeroTier Wiki](https://docs.zerotier.com/route-between-phys-and-virt/#configure-the-zerotier-managed-route) explains how to design managed routes. You configure Managed Routes in ZeroTier Central. + +### Detailed examples + +See: + +* [SensorsIot/IOTstack - ZeroTier](https://sensorsiot.github.io/IOTstack/Containers/ZeroTier/) + +You do not have to use IOTstack just to get ZeroTier running. However, the IOTstack documentation explores several network models and is a useful guide to the concepts involved and decisions you will need to make. +