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:
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 use it to finish configuring the router deployment.
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
Configure the repository for the RedHat family (Fedora, Rocky, Alma)
Create the repository file.
sudo tee /etc/yum.repos.d/openziti-release.repo >/dev/null <<\EOF
[OpenZitiRelease]
name=OpenZiti Release
baseurl=https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch
enabled=1
gpgcheck=0
gpgkey=https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
Update the package list.
sudo dnf 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
Set the required values in the answer file /opt/openziti/etc/router/bootstrap.env.
ZITI_CTRL_ADVERTISED_ADDRESS- the control plane DNS name or IP address (required)ZITI_CTRL_ADVERTISED_PORT- the control plane TCP port (default: 1280)ZITI_ENROLL_TOKEN- router enrollment token (JWT) as a literal string or path to a file (required)ZITI_ROUTER_ADVERTISED_ADDRESS- permanent DNS name or IP address of this router (required)ZITI_ROUTER_PORT- listener TCP port (default: 3022)
Run
bootstrap.bashsudo /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.
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):'
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):'
Logging
View the service's output.
journalctl -u ziti-router.service
- Log Formats
- Log Levels
Set a different format in the ZITI_ARGS environment variable and restart the service.
ZITI_ARGS='--log-formatter text'
Enable DEBUG log level with the --verbose flag in the ZITI_ARGS environment variable and restart the service.
ZITI_ARGS='--verbose'
Learn more in the logging reference.
Uninstall
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.servicePurge the package, including configuration files.
APT - Debian, Ubuntu, etc.
sudo apt-get purge openziti-routerRPM - RedHat, Fedora, etc.
sudo dnf remove openziti-routerRemove any firewall exceptions you created.