extern/zerotier-docker
1
0
Fork 1
mirror of https://github.com/zyclonite/zerotier-docker.git synced 2024-12-04 21:40:43 +01:00
Code Issues Packages Projects Releases Wiki Activity

refactor documentation to separate zerotier-router into separate readme

Browse Source 
Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com>
This commit is contained in:
Phill Kelley 2022-07-25 11:13:36 +10:00
parent 41d4501593
commit 1ae368044b
No known key found for this signature in database
GPG Key ID: 73D35B58592A2E98
2 changed files with 174 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
README-router.md Normal file
View File

@ -0,0 +1,172 @@
## zerotier router
### Description
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)
Technically, this 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.
### Command line example
``` console
$ docker run --name zerotier-one --device=/dev/net/tun \
--cap-add=NET_ADMIN --cap-add=NET_RAW --cap-add=SYS_ADMIN \
--env TZ=Etc/UTC --env PUID=999 -env PGID=994 \
--env ZEROTIER_ONE_LOCAL_PHYS=eth0 \
--env ZEROTIER_ONE_USE_IPTABLES_NFT=false \
--env ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)» \
-v /var/lib/zerotier-one:/var/lib/zerotier-one zyclonite/zerotier:router
```
Note:
* Environment variables that can contain multiple values should be enclosed in quotes with the components separated by spaces. Example:
``` console
--env ZEROTIER_ONE_LOCAL_PHYS="eth0 wlan0"
```
### Compose file example
``` yaml
version: '3'
services:
zerotier:
image: "zyclonite/zerotier:router"
container_name: zerotier-one
devices:
- /dev/net/tun
network_mode: host
volumes:
- '/var/lib/zerotier-one:/var/lib/zerotier-one'
cap_add:
- NET_ADMIN
- SYS_ADMIN
- NET_RAW
restart: unless-stopped
environment:
- TZ=Etc/UTC
- PUID=999
- PGID=994
- ZEROTIER_ONE_LOCAL_PHYS=eth0
- ZEROTIER_ONE_USE_IPTABLES_NFT=false
# - ZEROTIER_ONE_NETWORK_IDS=«yourDefaultNetworkID(s)»
```
Note:
* The right hand sides of environment variables should *never* be enclosed in quotes. If you need to pass multiple values, separate them with spaces. Example:
``` yaml
environment:
- ZEROTIER_ONE_LOCAL_PHYS=eth0 wlan0
```
### Environment variables
* `TZ` – timezone support. Example:
``` yaml
environment:
- TZ=Australia/Sydney
```
Defaults to `Etc/UTC` if omitted.
* `PUID` + `PGID` – user and group IDs for ownership of persistent store. Example:
``` yaml
environment:
- 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:
- Use only the physical Ethernet interface (this is also the default of the variable is omitted):
``` yaml
environment:
- ZEROTIER_ONE_LOCAL_PHYS=eth0
```
- If your computer only has WiFi active (eg Raspberry Pi Zero W2):
``` yaml
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:
``` 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`.
Try `true` if NAT does not seem to be working. This is needed on Raspberry Pi Bullseye.
* `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:
```
$ docker exec zerotier zerotier-cli join aaaaaaaaaaaaaaaa
```
- to join a multiple networks:
``` yaml
environment:
- ZEROTIER_ONE_NETWORK_IDS=aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb
```
Equivalent of running the following commands after the container first starts:
```
$ docker exec zerotier zerotier-cli join aaaaaaaaaaaaaaaa
$ docker exec zerotier zerotier-cli join bbbbbbbbbbbbbbbb
```
It does not matter whether you use this environment variable or the `join` command, you still need to use ZeroTier Central to approve the computer for each network it joins.
### Managed route(s)
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.
You configure Managed Routes in ZeroTier Central.

89
README.md
View File

@ -33,95 +33,10 @@ or create an empty file with the network as name
/var/lib/zerotier-one/networks.d/8056c2e21c000001.conf /var/lib/zerotier-one/networks.d/8056c2e21c000001.conf
#### Router mode #### Router mode
It is the implementation of the local network router [paper](https://zerotier.atlassian.net/wiki/spaces/SD/pages/224395274/Route+between+ZeroTier+and+Physical+Networks)
docker run --name zerotier-one --device=/dev/net/tun \ A variation on the container which implements a local network router. See:
--cap-add=NET_ADMIN --cap-add=NET_RAW --cap-add=SYS_ADMIN \
-v /var/lib/zerotier-one:/var/lib/zerotier-one zyclonite/zerotier:router
That will start the zero-one, establish connection and build the NAT+router once the `zt` interface is up. * [router README](./README-router.md)
##### Environment variables
The following environment variables are supported:
* `TZ` – timezone support. Example:
``` yaml
TZ=Australia/Sydney
```
Defaults to `Etc/UTC` if omitted.
* `PUID` + `PGID` – user and group IDs for ownership of persistent store. Example:
``` yaml
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 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` - controls which physical interfaces participate in network address translation (NAT). Examples:
- Use only the physical Ethernet interface (this is also the default of the variable is omitted):
``` yaml
ZEROTIER_ONE_LOCAL_PHYS=eth0
```
- If your computer only has WiFi active:
``` yaml
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 using `docker run`:
``` console
--env ZEROTIER_ONE_LOCAL_PHYS="eth0 wlan0"
```
- if using `docker-compose`:
``` yaml
environment:
- ZEROTIER_ONE_LOCAL_PHYS=eth0 wlan0
```
* `ZEROTIER_ONE_USE_IPTABLES_NFT` - controls the command the container uses to set up NAT forwarding. Example:
``` yaml
ZEROTIER_ONE_USE_IPTABLES_NFT=true
```
Defaults to `false` if omitted. Try `true` if NAT does not seem to be working.
* `ZEROTIER_ONE_NETWORK_IDS` – auto-join network(s). This variable is only effective on first launch. There is no default if it is omitted. Examples:
- if using `docker run`:
``` console
--env ZEROTIER_ONE_NETWORK_IDS="aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb"
```
- if using `docker-compose`:
``` yaml
environment:
- ZEROTIER_ONE_NETWORK_IDS=aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb
```
In each case, it is the equivalent of running the following commands after the container first starts:
```
$ docker exec zerotier zerotier-cli join aaaaaaaaaaaaaaaa
$ docker exec zerotier zerotier-cli join bbbbbbbbbbbbbbbb
```
It does not matter whether you use this environment variable or the `join` command, you still need to authorize the computer for each network in ZeroTier Central.
#### Source #### Source