Skip to main content
Star us on GitHub Star

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:

  1. Installation
  2. Configuration
  3. Starting Up

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.

  1. In /opt/openziti/etc/controller/service.env (the answer file for the service)
    1. Set ZITI_BOOTSTRAP=true to opt-in to bootstrapping.
  2. In /opt/openziti/etc/controller/bootstrap.env (the answer file for bootstrapping the controller)
    1. Set ZITI_CTRL_ADVERTISED_ADDRESS to the FQDN of the controller.
    2. Set ZITI_PWD to the desired management password for user admin. You may delete this after bootstrapping.

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.

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/'
Output
ziti    2694474 ziti-controller    8u     IPv6          222078013       0t0       TCP *:1280 (LISTEN)

You may set ZITI_CTRL_ADVERTISED_PORT in /opt/openziti/etc/controller/bootstrap.env to bootstrap with a different port.

Logging​

View the service's output.

journalctl -u ziti-controller.service

Set a different format in the override file's ExecStart directive.


/etc/systemd/system/ziti-controller.service.d/override.conf
[Service]
ExecStart=
ExecStart=/opt/openziti/etc/controller/entrypoint.bash run config.yml --log-formatter text


Learn more in the logging reference.

Uninstall​

  1. Clean the service state.

    sudo systemctl disable --now ziti-controller.service
    sudo systemctl clean --what=state ziti-controller.service

  2. Purge the package, including configuration files.

    APT - Debian, Ubuntu, etc.

    sudo apt-get purge openziti-controller

    RPM - RedHat, Fedora, etc.

    sudo dnf remove openziti-controller

  3. Remove any firewall exceptions you created.