Controller Deployment
This article is about deploying a controller as a Linux system service. The controller introduction may be helpful to read first.
We'll cover the following topics:
Install the Controller Package
The controller 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-controller
Manual Package Repo Setup
Configure the package repository and install openziti-controller.
- 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-controller
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 PKI, a config YAML file, and a database.
Generate a Configuration
This is the recommended approach if you are installing a new controller.
Answer Interactively
Run bootstrap.bash to be prompted for the required values.
sudo /opt/openziti/etc/controller/bootstrap.bash
Answer Non-interactively
Set the required values in the answer file /opt/openziti/etc/controller/bootstrap.env.
ZITI_CTRL_ADVERTISED_ADDRESS- control plane permanent DNS name (required)ZITI_CTRL_ADVERTISED_PORT- listener TCP port (default: 1280)ZITI_USER- username (default: admin)ZITI_PWD- password to initialize the database (required)
Run
bootstrap.bashsudo /opt/openziti/etc/controller/bootstrap.bash
Migrate an Existing Configuration
This example illustrates copying the PKI, configuration, and database from a previous installation to the controller service's working directory.
Craft a Configuration
Craft a new configuration by running ziti create config controller.
Review the environment variables, especially those named like ZITI_CTRL_*, that influence the controller configuration with ziti create config environment.
Here's a link to the controller configuration reference.
Starting Up
Run the service now and after every reboot
sudo systemctl enable --now ziti-controller.service
Firewall
The controller listens on a single configurable TCP port: 1280/tcp. Verify that the controller process is listening on this port and create a firewall exception if necessary.
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.
Further Configuration
Customize /var/lib/ziti-controller/config.yml as needed and restart the service.
sudo systemctl restart ziti-controller.service
Here's a link to the configuration reference.
Logging
View the service's output.
journalctl -u ziti-controller.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-controller.service
sudo systemctl reset-failed ziti-controller.service
sudo systemctl clean --what=state ziti-controller.servicePurge the package, including configuration files.
APT - Debian, Ubuntu, etc.
sudo apt-get purge openziti-controllerRPM - RedHat, Fedora, etc.
sudo dnf remove openziti-controllerRemove any firewall exceptions you created.
Troubleshooting
Verify the control plane is reachable by routers. The control plane must terminate TLS for routers because they will authenticate with a client certificate for all post-erollment interactions.
The server certificate must be issued by the controller's edge signer CA (edge.enrollment.signerCert in /var/lib/ziti-controller/config.yml).
Substitute the value of ctrl.options.advertiseAddress from /var/lib/ziti-controller/config.yml:
openssl s_client -connect {ctrl.options.advertiseAddress} -alpn ziti-ctrl -showcerts <>/dev/null \
|& openssl storeutl -certs -noout -text /dev/stdin \
| grep -E '(Subject|Issuer):'
Verify the controller's edge-client web API is reachable by identities and routers. This API must terminate TLS for any identities that enroll because they will authenticate with a client certificate for post-enrollment interactions.
Enrollment tokens are signed with the key of the controller's server certificate that matches the edge.api.address in /var/lib/ziti-controller/config.yml.
Substitute the value of edge.api.address from /var/lib/ziti-controller/config.yml:
openssl s_client -connect {edge.api.address} -alpn h2,http/1.1 -showcerts <>/dev/null \
|& openssl storeutl -certs -noout -text /dev/stdin \
| grep -E '(Subject|Issuer):'