Skip to content

Commit

Permalink
simplify and clarify zrok vpn guidance
Browse files Browse the repository at this point in the history
  • Loading branch information
@qrkourier
qrkourier committed Dec 27, 2024
1 parent 119c7e4 commit 6fdf5e1
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 40 deletions.
3 changes: 2 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.
Expand Down
73 changes: 42 additions & 31 deletions docs/guides/vpn/vpn.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 place `wintun.dll` ([download link](https://www.wintun.net/)) in the same directory as the `zrok.exe` executable.

### Linux

On Linux, you must run zrok VPN commands with the `NET_ADMIN` kernel capability. The simplest way to do this is to run zrok as the root user. 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.

### 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:
Expand All @@ -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>
Expand All @@ -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
Expand All @@ -57,38 +75,34 @@ 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:
[ 0.662] INFO main.(*accessPrivateCommand).run: 10.122.0.1 -> CONNECTED Welcome to zrok VPN
[ 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 [email protected]
Welcome to Ubuntu 23.10 (GNU/Linux 6.5.0-27-generic x86_64)

Expand All @@ -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.
([email protected]) 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 changes: 3 additions & 4 deletions nfpm/zrok-share.bash
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions nfpm/zrok-share.env
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down

0 comments on commit 6fdf5e1

Please sign in to comment.