Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

addresses documentation problems raised in issue 35 #36

Merged
merged 1 commit into from
Dec 4, 2024
Merged

addresses documentation problems raised in issue 35 #36

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 59 additions & 27 deletions README-router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -35,7 +43,8 @@ Note:
### Compose file example

``` yaml
version: '3'
---

services:
zerotier:
image: "zyclonite/zerotier:router"
Expand All @@ -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)»
```
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -140,7 +163,7 @@ Note:
environment:
- ZEROTIER_ONE_GATEWAY_MODE=inbound
```

- Only permit traffic *from* the local physical interfaces *to* the ZeroTier cloud:

``` yaml
Expand All @@ -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:

```
Expand All @@ -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.

Loading