extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2025-01-05 05:30:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

simplify and clarify zrok vpn guidance

Browse Source
This commit is contained in:
Kenneth Bingham 2024-12-27 15:50:54 -05:00
parent 119c7e4109
commit 6d8728af4f
No known key found for this signature in database
GPG Key ID: 31709281860130B6
4 changed files with 51 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@ -4,6 +4,8 @@
FIX: Docker share examples had incorrect default path for zrok environment mountpoint
CHANGE: Clarify OS requirements for zrok VPN
## v0.4.45
FEATURE: Minimal support for "organizations". Site admin API endpoints provided to create, list, and delete "organizations". Site admin API endpoints provided to add, list, and remove "organization members" (zrok accounts) with the ability to mark accounts as a "organization admin". API endpoints provided for organization admins to list the members of their organizations, and to also see the overview (environments, shares, and accesses) for any account in their organization. API endpoint for end users to see which organizations their account is a member of (https://github.com/openziti/zrok/issues/537)
@ -20,7 +22,6 @@ FIX: Docker reserved private share startup error (https://github.com/openziti/zr
FIX: Correct the download URL for the armv7 Linux release (https://github.com/openziti/zrok/issues/782)
## v0.4.44
FIX: Fix for goreleaser build action to align with changed ARM64 build path.

73
docs/guides/vpn/vpn.md
View File

@ -6,11 +6,27 @@ sidebar_label: VPN
zrok VPN backend allows for simple host-to-host VPN setup.
## Starting VPN server
## Operating System Requirements
zrok VPN requires elevated privileges to manage network devices.
### Windows
On Windows, you must run zrok VPN commands as an administrator and install WinTun by placing `wintun.dll` ([download link](https://www.wintun.net/)) in the same directory as the `zrok.exe` executable.
### Linux
On Linux, the simplest way to grant the necessary privileges is to run zrok VPN commands as root. You can enable a separate environment for root by also running `zrok enable` as the root user, or you can prefix the commands like `sudo -E` to allow zrok running as root to use the zrok environment owned by the current user. The minimum privilege is runing zrok VPN commands and the `ip` command with the `NET_ADMIN` kernel capability. The `zrok-share.service` unit has a commented example to grant `NET_ADMIN` as an Ambient Capability.
### macOS
On macOS, you must run zrok VPN commands as root. You can prefix the zrok command with `sudo -E` to allow zrok running as root to use the zrok environment owned by the current user.
## Start the VPN Server
VPN is shared through the `vpn` backend of `zrok` command.
```
```bash
eugene@hermes $ sudo -E zrok share private --headless --backend-mode vpn
[ 0.542] INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[589d443c-f59d-4fc8-8c48-76609b7fb402]} new service session
[ 0.705] INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:
@ -25,8 +41,9 @@ zrok access private 3rq7torslq3n
By default `vpn` backend uses subnet `10.122.0.0/16` and assigns `10.122.0.1` to the host that stared VPN share.
```
$ ifconfig
Example output from `ifconfig`:
```text
tun0: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST> mtu 16384
inet 10.122.0.1 netmask 255.255.0.0 destination 10.122.0.1
inet6 fe80::705f:24e4:dcfc:a6b2 prefixlen 64 scopeid 0x20<link>
@ -39,16 +56,17 @@ tun0: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST> mtu 16384
```
Default IP/subnet setting can be overridden by adding `<target>` parameter:
```
$ sudo -E zrok share private --headless --backend-mode vpn 192.168.42.12/24
```bash
sudo -E zrok share private --headless --backend-mode vpn 192.168.42.12/24
```
## VPN share reservation
## Reserve a VPN Share Token
Share reservation works the same as with other backend types:
As with all backend modes, you can reserve a share token for a VPN share.
```
eugene@hermes $ zrok reserve private -b vpn
```bash
eugene@hermes $ zrok reserve private --backend-mode vpn
[ 0.297] INFO main.(*reserveCommand).run: your reserved share token is 'k77y2cl7jmjl'
eugene@hermes $ sudo -E zrok share reserved k77y2cl7jmjl --headless
@ -57,14 +75,11 @@ eugene@hermes $ sudo -E zrok share reserved k77y2cl7jmjl --headless
[ 0.463] INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[22c5708d-e2f2-41aa-a507-454055f8bfcc]} new service session
[ 0.641] INFO main.(*shareReservedCommand).run: use this command to access your zrok share: 'zrok access private k77y2cl7jmjl'
[
```
## Accessing VPN share
## Access the VPN Share
Accessing a VPN share works similar to other backends.
```
```bash
eugene@calculon % sudo -E zrok access private --headless k77y2cl7jmjl
[ 0.201] INFO main.(*accessPrivateCommand).run: allocated frontend '50B5hloP1s1X'
[ 0.662] INFO main.(*accessPrivateCommand).run: access the zrok share at the following endpoint: VPN:
@ -72,23 +87,22 @@ eugene@calculon % sudo -E zrok access private --headless k77y2cl7jmjl
[ 0.662] INFO zrok/endpoints/vpn.(*Frontend).Run: connected:Welcome to zrok VPN
```
Starting `zrok access` to a VPN share creates virtual network device/interface:
zrok creates a virtual network device, i.e., a "tun" interface, when you run `zrok access`.
```
eugene@calculon ~ % ifconfig
...
Example output from `ifconfig` run on a VPN client device:
```bash
utun5: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 10.122.0.3 --> 10.122.0.1 netmask 0xff000000
inet6 fe80::ce08:faff:fe8a:7b25%utun5 prefixlen 64 scopeid 0x14
nd6 options=201<PERFORMNUD,DAD>
...
```
At this point a VPN tunnel is active between your server and client.
In the example above server is `hermes(10.122.0.1)` and client is `calculon(10.122.0.3)`.
You can access server from client by using assigned IP address.
At this point a VPN tunnel is active between your server and client.
In the example above server is `hermes(10.122.0.1)` and client is `calculon(10.122.0.3)`.
All devices in the VPN can access one another by IP address.
```
```bash
eugene@calculon ~ % ssh eugene@10.122.0.1
Welcome to Ubuntu 23.10 (GNU/Linux 6.5.0-27-generic x86_64)
@ -107,14 +121,11 @@ eugene@hermes:~$
```
You can also make a reverse(server-to-client) connection:
```
```bash
eugene@hermes:~$ ssh 10.122.0.3
The authenticity of host '10.122.0.3 (10.122.0.3)' can't be established.
<..snip..>
Warning: Permanently added '10.122.0.3' (ED25519) to the list of known hosts.
(eugene@10.122.0.3) Password:
Last login: Tue Apr 16 09:57:28 2024
eugene@calculon ~ % who am i
eugene ttys008 Apr 16 10:06 (10.122.0.1)
eugene@calculon ~ %
```
```

7
nfpm/zrok-share.bash
View File

@ -141,10 +141,9 @@ case "${ZROK_BACKEND_MODE}" in
;;
vpn)
if [[ -n "${ZROK_TARGET}" ]]; then
ZROK_SVC_FILE=/etc/systemd/system/zrok-share.service.d/override.conf
if ! grep -qE '^AmbientCapabilities=CAP_NET_ADMIN' "${ZROK_SVC_FILE}"; then
echo "ERROR: you must uncomment 'AmbientCapabilities=CAP_NET_ADMIN' in '${ZROK_SVC_FILE}'"\
"and run 'systemctl daemon-reload' to enable VPN mode" >&2
if ! systemctl cat zrok-share.service | grep -qE '^AmbientCapabilities=.*CAP_NET_ADMIN' >/dev/null; then
echo "ERROR: you must 'systemctl edit zrok-share.service' and uncomment
'AmbientCapabilities=CAP_NET_ADMIN' to enable VPN mode" >&2
exit 1
fi
fi

8
nfpm/zrok-share.env
View File

@ -67,11 +67,11 @@ ZROK_TARGET="" # e.g., http://127.0.0.1:3000
#ZROK_BACKEND_MODE="udpTunnel"
#ZROK_TARGET="127.0.0.1:53"
# you MUST grant NET_ADMIN capability to the service to enable vpn mode, e.g., run these two commands:
# sed -Ei 's/.*AmbientCapabilities=CAP_NET_ADMIN/AmbientCapabilities=CAP_NET_ADMIN/' /etc/systemd/system/zrok-share.service.d/override.conf
# systemctl daemon-reload
# you MUST grant NET_ADMIN capability to the service to enable vpn mode, e.g., run:
# systemctl edit zrok-share.service
# uncomment 'AmbientCapabilities=CAP_NET_ADMIN'
#ZROK_BACKEND_MODE="vpn"
#ZROK_TARGET="172.16.0.1/12"
#ZROK_TARGET="10.122.0.1/16"
# there is no target for socks mode because the share is only a dynamic exit for the proxy client
#ZROK_BACKEND_MODE="socks"