Router Deployment

This article is about deploying a router as a Linux system service. The router introduction may be helpful to read first.

We'll cover the following topics:

1. Creation
2. Installation
3. Configuration
4. Starting Up

Router Creation

You must create the router in the controller first with the web console or the CLI.

After creating the router, save the enrollment token (JWT) and provide the file path to the router during the configuration step below.

Install the Router Package

The router package provides a systemd service unit and bootstrapping script.

One-liner Install Script

curl -sS https://get.openziti.io/install.bash | sudo bash -s openziti-router

Manual Package Repo Setup

Configure the package repository and install openziti-router.

• Debian
• RedHat

Configure the repository for the Debian family of distributions (Ubuntu, Mint, Pop!_OS)

Install the OpenZiti repository key.

curl -sSLf https://get.openziti.io/tun/package-repos.gpg | sudo gpg --dearmor --output /usr/share/keyrings/openziti.gpg

Ensure the key is readable by all users.

sudo chmod a+r /usr/share/keyrings/openziti.gpg

Create the repository file.

sudo tee /etc/apt/sources.list.d/openziti-release.list >/dev/null <<EOF
deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-stable debian main
EOF

Update the package list.

sudo apt update

Finally, install the package: openziti-router

The openziti package provides the ziti CLI and is installed as a dependency.

Configuration

You must generate, migrate, or craft a configuration. Configuration consists of a config YAML file and router enrollment.

Generate a Configuration

This is the recommended approach if you are deploying a new router.

Answer Interactively

Run bootstrap.bash to be prompted for the required values.

sudo /opt/openziti/etc/router/bootstrap.bash

Answer Non-interactively

1. Set the required values in the answer file /opt/openziti/etc/router/bootstrap.env.

   1. ZITI_CTRL_ADVERTISED_ADDRESS - the control plane DNS name or IP address (required)
   2. ZITI_CTRL_ADVERTISED_PORT - the control plane TCP port (default: 1280)
   3. ZITI_ENROLL_TOKEN - router enrollment token (JWT) as a literal string or path to a file (required)
   4. ZITI_ROUTER_ADVERTISED_ADDRESS - permanent DNS name or IP address of this router (default: localhost)
   5. ZITI_ROUTER_PORT - listener TCP port (default: 3022)

2. Run bootstrap.bash

   sudo /opt/openziti/etc/router/bootstrap.bash

Migrate an Existing Configuration

This example illustrates copying the configuration and identity files from a previous installation to the router service's working directory.

Craft a Configuration

Craft a new configuration by running ziti create config router edge --routerName=router.

Review the environment variables, especially those named like ZITI_ROUTER_*, that influence the router configuration with ziti create config environment.

Here's a link to the router configuration reference.

Starting Up

Run the service now and after every reboot

sudo systemctl enable --now ziti-router.service

Further Configuration

Customize /var/lib/ziti-router/config.yml as needed and restart the service.

sudo systemctl restart ziti-router.service

Here's a link to the configuration reference.

Learn more about managing routers with the CLI.

Firewall

The router's generated configuration uses a single TCP port (default: 3022).

Confirm the router is running and listening on the expected port.

This will list all TCP listeners for "ziti" commands.

sudo ss -tlnp | grep ziti

If you have only one process named like "ziti" running, you will see output similar to this.

Output

LISTEN 0      4096                          *:3022             *:*    users:(("ziti",pid=2166302,fd=8))

Troubleshooting

Verify the edge listener is reachable by identities. The edge listener must terminate TLS for identities because they will authenticate with a client certificate for all interactions.

The server certificate must be issued by the controller's edge signer CA (edge.enrollment.signerCert in the controller's config.yml).

Substitute the value of listeners[?binding == 'edge'].options.advertise from /var/lib/ziti-router/config.yml:

openssl s_client -connect {listeners[?binding == 'edge'].options.advertise} -alpn ziti-edge -showcerts <>/dev/null \
|& openssl storeutl -certs -noout -text /dev/stdin \
| grep -E '(Subject|Issuer):'

Output

Issuer: C=US, L=Charlotte, O=NetFoundry, OU=ADV-DEV, CN=NetFoundry Inc. Intermediate CA 42KvRQxn.
Subject: C=US, ST=NC, L=Charlotte, O=NetFoundry, OU=Ziti, CN=BhCjN2Rkx
Issuer: C=US, L=Charlotte, O=NetFoundry, OU=ADV-DEV, CN=NetFoundry Inc. Certificate Authority IpcOEkAR6
Subject: C=US, ST=NC, L=Charlotte, O=NetFoundry, OU=ADV-DEV, CN=NetFoundry Inc. Intermediate CA 42KvRQxn.

At least one router must provide a link listener if you have multiple routers. Verify all link listeners are reachable by all routers. The link listener must terminate TLS for routers because they will authenticate with a client certificate for all interactions.

The server certificate must be issued by the controller's edge signer CA (edge.enrollment.signerCert in the controller's config.yml).

Substitute the value of link.listeners[?binding == 'transport'].advertise after the tls: prefix from /var/lib/ziti-router/config.yml:

openssl s_client -connect {link.listeners[?binding == 'transport'].advertise} -alpn ziti-link -showcerts <>/dev/null \
|& openssl storeutl -certs -noout -text /dev/stdin \
| grep -E '(Subject|Issuer):'

Output

Issuer: C=US, L=Charlotte, O=NetFoundry, OU=ADV-DEV, CN=NetFoundry Inc. Intermediate CA 42KvRQxn.
Subject: C=US, ST=NC, L=Charlotte, O=NetFoundry, OU=Ziti, CN=BhCjN2Rkx
Issuer: C=US, L=Charlotte, O=NetFoundry, OU=ADV-DEV, CN=NetFoundry Inc. Certificate Authority IpcOEkAR6
Subject: C=US, ST=NC, L=Charlotte, O=NetFoundry, OU=ADV-DEV, CN=NetFoundry Inc. Intermediate CA 42KvRQxn.

Logging

View the service's output.

journalctl -u ziti-router.service

Log Formats

Set a different format in the ZITI_ARGS environment variable and restart the service.

/opt/openziti/etc/router/service.env

ZITI_ARGS='--log-formatter text'

Log Levels

Enable DEBUG log level with the --verbose flag in the ZITI_ARGS environment variable and restart the service.

/opt/openziti/etc/router/service.env

ZITI_ARGS='--verbose'

Learn more in the logging reference.

Uninstall

1. Clean the service state.

   sudo systemctl disable --now ziti-router.service
   sudo systemctl reset-failed ziti-router.service
   sudo systemctl clean --what=state ziti-router.service

2. Purge the package, including configuration files.

   APT - Debian, Ubuntu, etc.

   sudo apt-get purge openziti-router

   RPM - RedHat, Fedora, etc.

   sudo dnf remove openziti-router

3. Remove any firewall exceptions you created.