Self-Hosting Guide for Linux

Walkthrough Video

Before you Begin

This will get you up and running with a self-hosted instance of zrok. I'll assume you have the following:

a Linux server with a public IP
a wildcard DNS record like *.zrok.quigley.com that resolves to the server IP

OpenZiti

OpenZiti (a.k.a. "Ziti") provides secure network backhaul for zrok public and private shares. You need a Ziti Controller and a Ziti Router. You can run everything on the same Linux VPS.

Install the Ziti Controller package by following the Linux controller deployment guide.
Ensure your answer file (/opt/openziti/etc/controller/bootstrap.env) has the FQDN of your Linux server and an admin password defined.
Ensure your firewall allows the controller port from the answer file.
Start the controller service (ziti-controller.service) and check the status.

ziti edge login localhost:1280 -u admin -p <password>

Administratively Create a Ziti Router

ziti edge create edge-router "router1" -o /tmp/router1.jwt

Install the Ziti Router package by following the Linux router deployment guide.
Ensure your answer file (/opt/openziti/etc/router/bootstrap.env) has the FQDN of your Linux server for both controller and router addresses and the enrollment token from the previous step.
Ensure your firewall allows the router port from the answer file.
Start the router service (ziti-router.service) and check the status.
Verify the new router is online.
```
ziti edge list edge-routers
```

Install zrok

Debian and RPM packages are available for zrok.

sudo apt install zrok

Follow the Linux installation guide to install the zrok package from the repository or manually install the binary for your platform.

Configure the Controller

Create a zrok controller configuration file in etc/ctrl.yml. The controller can terminate TLS or you may front the server with a reverse proxy that continually renews the necessary wildcard certificate (e.g., Caddy w/ a DNS provider plugin). This example will expose the non-TLS listener for the controller.

#    _____ __ ___ | | __
#   |_  / '__/ _ \| |/ /
#    / /| | | (_) |   <
#   /___|_|  \___/|_|\_\
# controller configuration

v:                  3

admin:
  # generate these admin tokens from a source of randomness, e.g. 
  #  LC_ALL=C tr -dc _A-Z-a-z-0-9 < /dev/urandom | head -c32
  secrets:
    -               Q8V0LqnNb5wNX9kE1fgQ0H6VlcvJybB1  # be sure to change this!

endpoint:
  host:             0.0.0.0
  port:             18080

invites:
  invites_open:    true

store:
  path:             zrok.db
  type:             sqlite3

ziti:
  api_endpoint:     "https://127.0.0.1:1280"
  username:         admin
  password:         "XO0xHp75uuyeireO2xmmVlK91T7B9fpD"

# you can use certbot to renew the wildcard cert for the controller with a DNS provider API token or front this `zrok` # controller with Caddy
#tls:
#  cert_path: "/Path/To/Cert/zrok.crt"
#  key_path:  "/Path/To/Cert/zrok.key"

The admin section defines privileged administrative credentials and must be set in the ZROK_ADMIN_TOKEN environment variable in shells where you want to run zrok admin.

The endpoint section defines where your zrok controller will listen.

The store section defines the local sqlite3 database used by the controller.

The ziti section defines how the zrok controller should communicate with your OpenZiti installation. When using the OpenZiti quickstart, an administrative password will be generated; the password in the ziti stanza should reflect this password.

note

Be sure to see the reference configuration at etc/ctrl.yml for the complete documentation of the current configuration file format for the zrok controller and service instance components.

See the separate guides on configuring metrics and configuring limits for details about both of these specialized areas of service instance configuration.

Environment Variables

The zrok binaries are configured to work with the global zrok.io service, and default to using api.zrok.io as the endpoint for communicating with the service.

To work with a self-hosted zrok deployment, you'll need to set the ZROK_API_ENDPOINT environment variable to point to the address where your zrok controller will be listening, according to endpoint in the configuration file above.

In my case, I've set:

export ZROK_API_ENDPOINT=http://127.0.0.1:18080

Bootstrap OpenZiti for zrok

With your OpenZiti network running and your configuration saved to a local file (I refer to mine as etc/ctrl.yml in these examples), you're ready to bootstrap the Ziti network.

Use the zrok admin bootstrap command to bootstrap like this:

$ zrok admin bootstrap etc/ctrl.yml
[   0.002]    INFO main.(*adminBootstrap).run: {
	...
}
[   0.002]    INFO zrok/controller/store.Open: database connected
[   0.006]    INFO zrok/controller/store.(*Store).migrate: applied 0 migrations
[   0.006]    INFO zrok/controller.Bootstrap: connecting to the ziti edge management api
[   0.039]    INFO zrok/controller.Bootstrap: creating identity for controller ziti access
[   0.071]    INFO zrok/controller.Bootstrap: controller identity: jKd8AINSz
[   0.082]    INFO zrok/controller.assertIdentity: asserted identity 'jKd8AINSz'
[   0.085]    INFO zrok/controller.assertErpForIdentity: asserted erps for 'ctrl' (jKd8AINSz)
[   0.085]    INFO zrok/controller.Bootstrap: creating identity for frontend ziti access
[   0.118]    INFO zrok/controller.Bootstrap: frontend identity: sqJRAINSiB
[   0.119]    INFO zrok/controller.assertIdentity: asserted identity 'sqJRAINSiB'
[   0.120]    INFO zrok/controller.assertErpForIdentity: asserted erps for 'frontend' (sqJRAINSiB)
[   0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id 'sqJRAINSiB'; please use 'zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name' to create a frontend instance
[   0.123]    INFO zrok/controller.assertZrokProxyConfigType: found 'zrok.proxy.v1' config type with id '33CyjNbIepkXHN5VzGDA8L'
[   0.124]    INFO zrok/controller.assertMetricsService: creating 'metrics' service
[   0.126]    INFO zrok/controller.assertMetricsService: asserted 'metrics' service (5RpPZZ7T8bZf1ENjwGiPc3)
[   0.128]    INFO zrok/controller.assertMetricsSerp: creating 'metrics' serp
[   0.130]    INFO zrok/controller.assertMetricsSerp: asserted 'metrics' serp
[   0.134]    INFO zrok/controller.assertCtrlMetricsBind: creating 'ctrl-metrics-bind' service policy
[   0.135]    INFO zrok/controller.assertCtrlMetricsBind: asserted 'ctrl-metrics-bind' service policy
[   0.138]    INFO zrok/controller.assertFrontendMetricsDial: creating 'frontend-metrics-dial' service policy
[   0.140]    INFO zrok/controller.assertFrontendMetricsDial: asserted 'frontend-metrics-dial' service policy
[   0.140]    INFO main.(*adminBootstrap).run: bootstrap complete!

The zrok admin bootstrap command configures the zrok database, the necessary OpenZiti identities, and all of the OpenZiti policies required to run a zrok service.

Notice this warning:

[   0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id 'sqJRAINSiB'; please use 'zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name' to create a frontend instance

If you find it necessary to re-run the zrok admin bootstrap command, you may need to add the --skip-frontend flag to avoid re-creating the default public frontend's Ziti identity and router policy.

Run zrok Controller

The zrok bootstrap process wants us to create a "public frontend" for our service. zrok uses public frontends to allow users to specify where they would like public traffic to ingress from.

The zrok admin create frontend command requires a running zrok controller, so let's start that up first:

$ zrok controller etc/ctrl.yml 
[   0.003]    INFO main.(*controllerCommand).run: {
	...
}
[   0.016]    INFO zrok/controller.inspectZiti: inspecting ziti controller configuration
[   0.048]    INFO zrok/controller.findZrokProxyConfigType: found 'zrok.proxy.v1' config type with id '33CyjNbIepkXHN5VzGDA8L'
[   0.048]    INFO zrok/controller/store.Open: database connected
[   0.048]    INFO zrok/controller/store.(*Store).migrate: applied 0 migrations
[   0.049]    INFO zrok/controller.(*metricsAgent).run: starting
[   0.064]    INFO zrok/rest_server_zrok.setupGlobalMiddleware: configuring
[   0.064]    INFO zrok/ui.StaticBuilder: building
[   0.065]    INFO zrok/rest_server_zrok.(*Server).Logf: Serving zrok at http://[::]:18080
[   0.085]    INFO zrok/controller.(*metricsAgent).listen: started

Create zrok Frontend

With our ZROK_ADMIN_TOKEN and ZROK_API_ENDPOINT environment variables set, we can create our public frontend like this:

$ zrok admin create frontend sqJRAINSiB public http://{token}.zrok.quigley.com:8080
[   0.037]    INFO main.(*adminCreateFrontendCommand).run: created global public frontend 'WEirJNHVlcW9'

The id of the frontend was emitted earlier in by the zrok controller when we ran the bootstrap command. If you don't have that log message the you can find the id again with the ziti CLI like this:

# log in as admin (example)
ziti edge login localhost:1280 -u admin -p XO0xHp75uuyeireO2xmmVlK91T7B9fpD

# list Ziti identities created by the quickstart and bootstrap
ziti edge list identities

The id is shown for the frontend identity named "public."

Nice work! The zrok controller is fully configured now that you have created the zrok frontend.

Configure the Public Frontend

Create an http frontend configuration file in etc/http-frontend.yml.

v:                  3
host_match:         zrok.quigley.com
address:            0.0.0.0:8080

This frontend config file has a host_match pattern that represents the DNS zone you're using with this instance of zrok. Incoming HTTP requests with a matching Host header will be handled by this frontend. You may also specify the interface address where the frontend will listen for public access requests.

The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the Host header supplied by the viewer. This example will expose the non-TLS listener for the frontend.

You can also specify an oauth configuration in this file, full details of are found in OAuth Public Frontend Configuration.

Start Public Frontend

In another terminal window, run:

$ zrok access public etc/http-frontend.yml
[   0.002]    INFO main.(*accessPublicCommand).run: {
	...
}
[   0.002]    INFO zrok/endpoints/public_frontend.newMetricsAgent: loaded 'public' identity

The zrok frontend uses the public identity created during the bootstrap process to securely access zrok backends. to provide public access for the zrok deployment. It is expected that the configured listener for this frontend corresponds to the DNS template specified when creating the public frontend record above.

Create a User Account

With our ZROK_ADMIN_TOKEN and ZROK_API_ENDPOINT environment variables set, we can create our first user account.

zrok admin create account etc/ctrl.yml <email> <password>

The output is the account token you will use to enable each device's zrok environment.

Example output

SuGzRPjVDIcF

Invite Additional Users

Offer this onboarding method to your users if you have configured an email-sending service in your zrok controller configuration.

$ zrok invite
New Email: user@domain.com
Confirm Email: user@domain.com
invitation sent to 'user@domain.com'!

If you look at the console output from your zrok controller, you'll see a message like this:

[ 238.168]    INFO zrok/controller.(*inviteHandler).Handle: account request for 'user@domain.com' has registration token 'U2Ewt1UCn3ql'

You can access your zrok controller's registration UI by pointing a web browser at:

http://localhost:18080/register/U2Ewt1UCn3ql

The UI will ask you to set a password for your new account. Go ahead and do that.

After doing that, I see the following output in my controller console:

[ 516.778]    INFO zrok/controller.(*registerHandler).Handle: created account 'user@domain.com' with token 'SuGzRPjVDIcF'

Keep track of the token listed above (SuGzRPjVDIcF). We'll use this to enable our shell for this zrok deployment.

Enable Your Environment

On another device that can reach your Linux server by FQDN, configure the API endpoint and enable the environment with the account token you received when you created the first user account.

export ZROK_API_ENDPOINT=https://zrok.quigley.com
# or
zrok config set apiEndpoint https://zrok.quigley.com

zrok enable SuGzRPjVDIcF

Example output

zrok environment '2AS1WZ3Sz' enabled for 'SuGzRPjVDIcF'

zrok status --secrets

Example output
Config:

  CONFIG       VALUE                      SOURCE
  apiEndpoint  https://zrok.quigley.com   env

Environment:

  PROPERTY       VALUE
  Secret Token   SuGzRPjVDIcF
  Ziti Identity  2AS1WZ3Sz

Congratulations. You have a working zrok environment!

Walkthrough Video​

Before you Begin​

OpenZiti​

Install zrok​

Configure the Controller​

Environment Variables​

Bootstrap OpenZiti for zrok​

Run zrok Controller​

Create zrok Frontend​

Configure the Public Frontend​

Start Public Frontend​

Create a User Account​

Invite Additional Users​

Enable Your Environment​