extern/zerotier-docker
1
0
Fork 1
mirror of https://github.com/zyclonite/zerotier-docker.git synced 2025-01-31 17:09:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

addresses documentation problems raised in issue 35 (#36)

Browse Source 
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>
This commit is contained in:
Phill 2024-12-05 01:43:22 +11:00 committed by GitHub
parent f1bae68d57
commit 8551038de7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 59 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
README-router.md
View File

@ -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: 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 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. * 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 ### Command line example
``` console ``` console
$ docker run --name zerotier-one --device=/dev/net/tun \ $ docker run --name zerotier-one --device=/dev/net/tun \
--network=host -d \
--cap-add=NET_ADMIN --cap-add=NET_RAW --cap-add=SYS_ADMIN \ --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_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_GATEWAY_MODE=inbound \
--env ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)» \ --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: Note:
@ -35,7 +43,8 @@ Note:
### Compose file example ### Compose file example
``` yaml ``` yaml
version: '3' ---
services: services:
zerotier: zerotier:
image: "zyclonite/zerotier:router" image: "zyclonite/zerotier:router"
@ -55,7 +64,7 @@ services:
- PUID=999 - PUID=999
- PGID=994 - PGID=994
- ZEROTIER_ONE_LOCAL_PHYS=eth0 - ZEROTIER_ONE_LOCAL_PHYS=eth0
- ZEROTIER_ONE_USE_IPTABLES_NFT=false - ZEROTIER_ONE_USE_IPTABLES_NFT=true
- ZEROTIER_ONE_GATEWAY_MODE=inbound - ZEROTIER_ONE_GATEWAY_MODE=inbound
# - ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)» # - ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)»
``` ```
@ -87,9 +96,9 @@ Note:
- PUID=1000 - PUID=1000
- PGID=1000 - PGID=1000
``` ```
If omitted, `PUID` defaults to user ID 999, while `PGID` defaults to group ID 994. 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. 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: * `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: environment:
- ZEROTIER_ONE_LOCAL_PHYS=wlan0 - 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: - If your computer has both Ethernet and WiFi interfaces active and you wish to be able to route through each interface:
``` yaml ``` yaml
environment: environment:
- ZEROTIER_ONE_LOCAL_PHYS=eth0 wlan0 - ZEROTIER_ONE_LOCAL_PHYS=eth0 wlan0
``` ```
This scheme could be appropriate where the physical interfaces were: This scheme could be appropriate where the physical interfaces were:
1. In the same broadcast domain (subnet). Disconnecting Ethernet would fail-over to WiFi. 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. 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
``` ```
environment:
- `false` means the container uses `iptables`. This is the default. - ZEROTIER_ONE_USE_IPTABLES_NFT=true
- `true` means the container uses `iptables-nft`. ```
* `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: * `ZEROTIER_ONE_GATEWAY_MODE` - controls the traffic direction. Examples:
- Only permit traffic *from* the ZeroTier cloud *to* the local physical interfaces: - Only permit traffic *from* the ZeroTier cloud *to* the local physical interfaces:
@ -140,7 +163,7 @@ Note:
environment: environment:
- ZEROTIER_ONE_GATEWAY_MODE=inbound - ZEROTIER_ONE_GATEWAY_MODE=inbound
``` ```
- Only permit traffic *from* the local physical interfaces *to* the ZeroTier cloud: - Only permit traffic *from* the local physical interfaces *to* the ZeroTier cloud:
``` yaml ``` 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. 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. * `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: This variable is *only* effective on first launch. There is no default if it is omitted. Examples:
- to join a single network: - to join a single network:
``` yaml ``` yaml
environment: environment:
- ZEROTIER_ONE_NETWORK_IDS=aaaaaaaaaaaaaaaa - ZEROTIER_ONE_NETWORK_IDS=aaaaaaaaaaaaaaaa
``` ```
Equivalent of running the following command after the container first starts: 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*. 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. 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.