Skip to main content
Star us on GitHub Star

Host OpenZiti Anywhere

You can absolutely choose to host your network anywhere you like. It is not necessary for the server to be on the open internet. If it works better for you to deploy OpenZiti on your own network, great, do that. The only requirement to be aware of is that every piece of the network will need to be able to communicate to the controller and at least one edge router, which this quickstart will provide.

If you have a Linux server available on the open internet, or you will provision one for use with OpenZiti, that's the ideal scenario. With a zero trust overlay network provided by OpenZiti, you can rest assured that your traffic is safe even when using commodity internet. Furthermore, you do not need to worry about being on a network you trust, as all networks are considered untrustworthy, even your work/home network!

Installation​

When starting out deploying a network, we recommend you follow and use the expressInstall function provided by the OpenZiti project. Once you're familiar with the network and the configuration options available you'll be better equipped to make changes.

Firewall​

The first issue you will need to deal with is opening some ports. A network will consist of at least one controller and at least one edge router. Both of these components will require ports to be open. For the controller you will need to open a range of ports through your firewall:

  • 8440/tcp: edge controller providing router control plane
  • 8441/tcp: edge controller providing client sessions
  • 8442/tcp: edge router providing client connections
  • 8443/tcp: Ziti Admin Console (ZAC) [optional]

These are the arbitrary ports we'll use in this example for convenience when specifying the firewall exception as a port range.

Express Install​

Prerequisites​

note

Make sure you have tar, hostname, jq and curl installed before running the expressInstall one-liner.

expressInstall Setup​

expressInstall may be customized with environment variables. Consider creating a DNS name for this installation before running the script. By default, the quickstart will install your Ziti network's PKI and configuration files in ${HOME}/.ziti/quickstart/$(hostname -s). You may choose a different location by defining ZITI_HOME=/custom/path/to/quickstart. If you do customize ZITI_HOME then you should also make this assignment in your shell RC, e.g., ~/.bashrc for future convenience.

You will almost certainly want to use the public DNS name of your instance. It is possible to use an IP address, but a DNS name is a more flexible option, which will be important if the IP ever changes.

The quickest and easiest thing to do, is find your external DNS name and set it into the EXTERNAL_DNS environment variable. You may skip setting EXTERNAL_DNS if you don't need to configure the advertised DNS Subject Alternative Name (SAN). For example,

export EXTERNAL_DNS="acme.example.com"
export EXTERNAL_IP="$(curl -s eth0.me)"       
export ZITI_CTRL_EDGE_IP_OVERRIDE="${EXTERNAL_IP}"
export ZITI_ROUTER_IP_OVERRIDE="${EXTERNAL_IP}"
export ZITI_CTRL_ADVERTISED_ADDRESS="${EXTERNAL_DNS:-${EXTERNAL_IP}}"
export ZITI_ROUTER_ADVERTISED_ADDRESS="${EXTERNAL_DNS:-${EXTERNAL_IP}}"
export ZITI_CTRL_ADVERTISED_PORT=8440
export ZITI_CTRL_EDGE_ADVERTISED_PORT=8441
export ZITI_ROUTER_PORT=8442

Run expressInstall​

As with any script that is downloaded and run from the internet, we recommend you examine the script before running it locally. This script is provided as a convenience method for installing an environment quickly and easily.

source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/ziti-cli-functions.sh)"; expressInstall

systemd​

This assumes you already ran expressInstall on a Linux server. If it's available on your system, then it is recommended to use systemd to manage your controller and router processes. This is useful to make sure the controller can restart automatically should you shutdown/restart the server. To generate the systemd unit files, run:

createControllerSystemdFile
createRouterSystemdFile "${ZITI_ROUTER_NAME}"

Example output:

$ createControllerSystemdFile
Controller systemd file written to: /home/ubuntu/.ziti/quickstart/ip-172-31-23-18/ip-172-31-23-18-edge-controller.service

$ createRouterSystemdFile "${ZITI_ROUTER_NAME}"
Router systemd file written to: /home/ubuntu/.ziti/quickstart/ip-172-31-23-18/ip-172-31-23-18-edge-router.service

The helper functions vs systemd​

The set of startController/stopController, startRouter/stopRouter are functions declared in the the ziti-cli-function.sh helper script and are useful for running the controller and router directly in your shell. These functions are not meant to work with systemd-enabled installs. If you are enabling systemd, use systemctl to start/stop the components. During the expressInstall, the controller and router were started using the helper scripts to complete the installation. Both should not be running, but before you run the controller and router with systemd you need to stop them if they're currently running:

stopRouter 
stopController

Example output:

$ stopRouter 
INFO: Router stopped.

$ stopController 
INFO: Controller stopped.

After the systemd service units are generated, you can then install them by running:

sudo cp "${ZITI_HOME}/${ZITI_CTRL_NAME}.service" /etc/systemd/system/ziti-controller.service
sudo cp "${ZITI_HOME}/${ZITI_ROUTER_NAME}.service" /etc/systemd/system/ziti-router.service
sudo systemctl daemon-reload
sudo systemctl enable --now ziti-controller
sudo systemctl enable --now ziti-router

Now, both the controller and the edge router will restart automatically if the machine reboots!
After a few seconds you can then run these commands and verify systemd has started the processes and see the status:

sudo systemctl -q status ziti-controller --lines=0 --no-pager
sudo systemctl -q status ziti-router --lines=0 --no-pager

Example output:

$ sudo systemctl -q status ziti-controller --lines=0 --no-pager
● ziti-controller.service - Ziti-Controller
     Loaded: loaded (/etc/systemd/system/ziti-controller.service; disabled; vendor preset: enabled)
     Active: active (running) since Thu 2021-11-11 19:05:46 UTC; 8s ago
   Main PID: 2375 (ziti-controller)
      Tasks: 7 (limit: 1154)
     Memory: 43.7M
     CGroup: /system.slice/ziti-controller.service
             └─2375 /home/ubuntu/.ziti/quickstart/ip-10-0-0-1/ziti-bin/ziti-v0.22.11/ziti-controller run /home/ubuntu/.ziti/quickstart/ip-10-0-0-1/co…

$ sudo systemctl -q status ziti-router --lines=0 --no-pager
● ziti-router.service - Ziti-Router for ip-10-0-0-1-edge-router
     Loaded: loaded (/etc/systemd/system/ziti-router.service; disabled; vendor preset: enabled)
     Active: active (running) since Thu 2021-11-11 19:05:47 UTC; 8s ago
   Main PID: 2385 (ziti-router)
      Tasks: 6 (limit: 1154)
     Memory: 231.4M
     CGroup: /system.slice/ziti-router.service
             └─2385 /home/ubuntu/.ziti/quickstart/ip-10-0-0-1/ziti-bin/ziti-v0.22.11/ziti-router run /home/ubuntu/.ziti/quickstart/ip-10-0-0-1/ip-10…

Adding Environment Variables Back to the Shell​

If you log out and log back in again you can source the *.env file located in ZITI_HOME.

source ~/.ziti/quickstart/$(hostname -s)/$(hostname -s).env

Example output:

$ source ~/.ziti/quickstart/$(hostname -s)/$(hostname -s).env
adding /home/ubuntu/.ziti/quickstart/ip-10-0-0-1/ziti-bin/ziti-v0.20.2 to the path

$ echo $ZITI_HOME
/home/ubuntu/.ziti/quickstart/ip-10-0-0-1

Next Steps​

  • Now that you have your network in place, you probably want to try it out. Head to the Your First Service quickstart and start learning how to use OpenZiti.
  • Install the console (web UI)
  • Add a Second Public Router: In order for multiple routers to form transit links, they need a firewall exception to expose the "link listener" port. The default port is 10080/tcp.
  • Help

    Try the Wizard