Skip to main content
Star us on GitHub Star

Router Deployment

The Ziti Router is the entry point for Ziti-based clients. It is responsible for authenticating incoming connections by verifying the connecting client has a valid network session. It also routes traffic to whatever the destination is for the given service. In simple deployments can have a single router as is the case with the Ziti Network Quickstart.

Deployment​

This article describes the process of deploying a router. It covers what attributes can be updated, removed, and added after the deployment is completed.

Notes

The life cycle of a router does not allow for the advertised, external DNS name or IP address to change. A new router must be created.

Process of Deployment​

It is advisable to generate private keys on the same host where they'll be used. This minimizes the risk of losing custody of the private key material.

Note

Ensure you are logged in for managing routers with the CLI


The ziti CLI will help you get a session from the controller's management API. You will be prompted to trust any new server certificates. Your session cache and trust store are managed by the CLI in your home directory.

# implies https://localhost:1280
ziti edge login -u admin -p admin
# implies https://
ziti edge login ziti.example.com:8441 -u admin -p admin

Download Binaries​

You will need the ziti-router executable from OpenZiti Releases.

Create Config File​

The router loads its configuration from a YAML file. You may use the ziti create config router command to generate a config file, influencing the contents with options and variables. Here are some practical examples representing common deployment scenarios.

The identity.key field in the config behaves differently for routers. If a file exists in the path indicated by key then the key will be used during router enrollment. If it does not exist then a unique key will be generated.

identity:
    cert:                 "~/.ziti/config/certs/router01.zitinetwork.example.org.cert"
    server_cert:          "~/.ziti/config/certs/router01.zitinetwork.example.org.server.chain.cert"
    key:                  "~/.ziti/config/certs/router01.zitinetwork.example.org.key"
    ca:                   "~/.ziti/config/certs/router01.zitinetwork.example.org.cas"

Create Router​

The life cycle of a router begins by calling the controller's management API to create a router. You can do this with the REST API or the ziti CLI.

Enroll Router​

Creating a router yields a one-time enrollment token that you may store as a JWT file. Enrollment consumes the token and facilitates issuing a client certificate for the router, establishing cryptographic trust with the controller.

ziti-router enroll config.yaml --jwt token.jwt

Run Router​

ziti-router run config.yaml
# /etc/systemd/system/ziti-router.service
[Unit]
Description=Ziti Router
After=network.target

[Service]
User=root
WorkingDirectory=/etc/openziti/router
ExecStart=/usr/local/sbin/ziti-router run /etc/openziti/router/config.yml --log-formatter pfxlog
Restart=always
RestartSec=2
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Manage Router​

You can manage a router's role attributes, tags, etc. with the REST API or the ziti CLI for more details

Configure Logging​

All Ziti components log to standard output and standard error file descriptors.

Output from Ziti components comes in three distinct styles. Choose the style of logging that is right for you.

  • pfxlog - a human-readable format leveraging ascii escape codes to display colorized log level
  • json - a machine-readable format targeting automated processes for log aggregation/searching
  • text - a human-readable format using plain text (no ascii escape codes)
ziti-router run ./router.yml --log-formatter pfxlog