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