Skip to main content
Star us on GitHub Star

Router Configuration

This article expands on the Linux router deployment article with configuration concepts and examples.

Config Management

Edit the generated configuration YAML file or run ziti create config router to generate one from scratch. Run ziti create config environment for descriptions of the environment variables that influence the generated output.

Identity

The identity configuration section defines the paths to the router's identity files: certs, keys, and a bundle of trusted root CA certificates. All of the files will be created in the specified paths at the time of router enrollment. The router will automatically renew its certificates if the path remains writable.

identity:
cert: /var/lib/ziti-router/client.cert
server_cert: /var/lib/ziti-router/server.chain.cert
key: /var/lib/ziti-router/private.key
ca: /var/lib/ziti-router/trusted-root.cas

Private Key

The identity configuration section is common to routers and controllers, but the key sub-property behaves differently for routers. If a private key exists in the path, then it will be used to sign router enrollment certificate requests. If it does not exist, then a private key will be locally generated and stored in that path.

If present, the server_key signs the router's server certificate request. Otherwise, the key sub-property is used for both client and server certificate.

The private keys' values are assumed to be file:// URLs if unspecified. Alternatives include pkcs11:// and parsec:// URLs for hardware keys.

Optional Capabilities

You may enable or disable capabilities of the router by including or omitting their sections in the configuration file. These are a few of the most relevant configuration sections. Refer to the router configuration reference for more complete information.

  • edge - Most routers include this section which configures the router to listen for connections from endpoint identities. This is what makes a router an "edge router." Without this section, the router is a "fabric router" and communicates only with other routers and the control plane.
  • link.listeners - The link section configures the router to dial and listen for other routers that are dialing in to create mesh links. Omitting the listeners sub-section makes a router "private." "Public" routers are presumed reachable and listening for other routers.
  • listeners[?binding == 'tunnel'] - the listeners section may contain a special type of binding that configures the router's built-in tunneling capabilities: binding: tunnel. The tunnel's mode property may be set to tproxy, proxy, or host. Requires edge.
    • tproxy mode requires the CAP_NET_ADMIN capability and that the host's DNS resolver is set to use the nameserver provided by the router. The tproxy mode is useful for transparently proxying services and providing Ziti DNS to non-Ziti applications.

Examples


This is an example of generating a public router configuration with the ziti CLI.


#!/usr/bin/env bash

# working directory for the router
export ZITI_HOME=/var/lib/ziti-router

# address and port of control plane endpoint
export ZITI_CTRL_ADVERTISED_ADDRESS=ctrl.ziti.example.org \
ZITI_CTRL_ADVERTISED_PORT=1280

# address and port of this router
export ZITI_ROUTER_ADVERTISED_ADDRESS=router1.ziti.example.org \
ZITI_ROUTER_PORT=3022 \
ZITI_ROUTER_LISTENER_BIND_PORT=3022

ziti create config router edge \
--routerName router1 \
--tunnelerMode none

Public Router config.yml

v: 3

identity:
cert: "/var/lib/ziti-router/router1.cert"
server_cert: "/var/lib/ziti-router/router1.server.chain.cert"
key: "/var/lib/ziti-router/router1.key"
ca: "/var/lib/ziti-router/router1.cas"

ctrl:
endpoint: tls:ctrl.ziti.example.org:1280

link:
dialers:
- binding: transport
listeners:
- binding: transport
bind: tls:0.0.0.0:3022
advertise: tls:router1.ziti.example.org:3022
options:
outQueueSize: 4

listeners:
- binding: edge
address: tls:0.0.0.0:3022
options:
advertise: router1.ziti.example.org:3022
connectTimeoutMs: 5000
getSessionTimeout: 60

edge:
csr:
country: US
province: NC
locality: Charlotte
organization: NetFoundry
organizationalUnit: Ziti
sans:
dns:
- localhost
- router1.ziti.example.org
ip:
- "127.0.0.1"

forwarder:
latencyProbeInterval: 0
xgressDialQueueLength: 1000
xgressDialWorkerCount: 128
linkDialQueueLength: 1000
linkDialWorkerCount: 32