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:
Installation
The controller package provides a service unit and, if bootstrapping is enabled, will generate a configuration based on the bootstrapping answer file. The openziti
package provides the ziti
CLI and is installed automatically as a dependency. Run the install script for RPM and Debian distributions or manually configure the package repo and install package openziti-controller
.
Download and run the install script.
wget https://get.openziti.io/install.bash
Install interactively so that you will have an opportunity to answer questions about generating a configuration.
sudo bash ./install.bash openziti-controller
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
Configuration
You must provide or generate a configuration. Configuration consists of a PKI, a config YAML file, and a database.
Generate a Configuration
You can generate a configuration by enabling bootstrapping during an interactive install which prompts for the most relevant answers, or by setting these values in the answer file.
- In
/opt/openziti/etc/controller/service.env
(the answer file for the service)- Set
ZITI_BOOTSTRAP=true
to opt-in to bootstrapping.
- Set
- In
/opt/openziti/etc/controller/bootstrap.env
(the answer file for bootstrapping the controller)- Set
ZITI_CTRL_ADVERTISED_ADDRESS
to the FQDN of the controller. - Set
ZITI_PWD
to the desired management password for useradmin
. You may delete this after bootstrapping.
- Set
Generating a Public Key Infrastructure
The controller service will generate a root CA and issue an intermediate CA cert during the first startup.
The controller needs a CA to issue certificates for edge identities during enrollment. This CA is known as the edge signer. It's a good idea to secure the root in a different location and use an intermediate CA for this purpose. This allows you to recover in a scenario where the intermediate was lost without changing the root of trust and invalidating all edge enrollments. Refer to the article about backing up the controller for more information.
Disable bootstrapping a PKI by setting ZITI_BOOTSTRAP_PKI=false
in /opt/openziti/etc/controller/service.env
.
Check out the PKI page for an overview of these concepts.
Generating a Configuration File
The controller's configuration is loaded from a file (reference). The Linux system service will generate a valid configuration during the first startup unless one already exists.
The filename of the configuration file, relative to the Linux service's working directory (default: /var/lib/ziti-controller/config.yml
). You may override this in /etc/systemd/system/ziti-controller.service.d/override.conf
by re-initializing ExecStart=
with an empty value followed by a second ExecStart
directive specifying the override command.
Disable bootstrapping a configuration by setting ZITI_BOOTSTRAP_CONFIG=false
in /opt/openziti/etc/controller/service.env
.
Bootstrapping the Database
The controller requires a BoltDB database to store its state. The Linux system service will initialize a database with a default admin password during the first startup unless one already exists.
You must specify the management password for the default admin user before starting the service. This is done by setting ZITI_PWD
in /opt/openziti/etc/controller/bootstrap.env
or in the root-only file specified by LoadCredential
in /etc/systemd/system/ziti-controller.service.d/override.conf
. You may delete the password after bootstrapping for security.
Disable bootstrapping the database by setting ZITI_BOOTSTRAP_DATABASE=false
in /opt/openziti/etc/controller/service.env
.
Manual Configuration
You can provide, rather than generate, any or all of the PKI, configuration file, and database. If you plan to provide all three then you can disable bootstrapping entirely by setting ZITI_BOOTSTRAP=false
in /opt/openziti/etc/controller/service.env
.
Provide a Configuration File
Create the file at /var/lib/ziti-controller/config.yml
and set ZITI_BOOTSTRAP_CONFIG=false
in /opt/openziti/etc/controller/service.env
.
Provide a PKI
Place the intermediate CA for the controller's edge enrollment signer in /var/lib/ziti-controller
and set ZITI_BOOTSTRAP_PKI=false
in /opt/openziti/etc/controller/service.env
. The file paths to the intermediate CA are specified in the configuration file.
Provide a Database
Place the BoltDB file in /var/lib/ziti-controller
and set ZITI_BOOTSTRAP_DATABASE=false
in /opt/openziti/etc/controller/service.env
. The file path to the database is specified in the configuration file.
Migration Example
This example illustrates copying the PKI, configuration, and database from a previous installation to the controller service's working directory.
Starting Up
Start the controller service now and enable startup after 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.
systemctl show -p MainPID --value ziti-controller.service \
| xargs -rIPID sudo lsof -Pnp PID |& awk '$5~/IP/'
You may set ZITI_CTRL_ADVERTISED_PORT
in /opt/openziti/etc/controller/bootstrap.env
to bootstrap with a different port.
Logging
View the controller service's output with journalctl -u ziti-controller.service
.
- Log Formats
- Log Levels
Choose the logging format (default: text).
pfxlog
- a human-readable format leveraging ANSI escape codes to colorize log levelsjson
- a machine-readable format targeting automated processes for log aggregationtext
- a human-readable format using plain text (no ANSI escape codes)
ziti controller run config.yml --log-formatter text
The default log level is INFO
. This means that log messages INFO
, WARNING
, ERROR
, and FATAL
will all be emitted. Enable verbose logging by adding --verbose or -v
to the command being executed. Verbose mode will additionally emit DEBUG
log level messages.
ziti controller run config.yml --verbose
Uninstall
sudo systemctl disable --now ziti-controller.service
sudo systemctl clean --what=state ziti-controller.service
Remove any firewall exceptions you created for the service.