ziti/doc/004-controller-pki.md

# Overview

This tutorial covers composing the controller PKI and minimal controller and router configs from scratch. [The previous tutorial](./003-local-deploy.md) guided you to run a controller with the demo PKI checked in to this repo under `./etc/ca` and with annotated and complete controller and router configs generated with the `ziti create config` command.

You will configure:

- 1x Ziti Controller + Edge
- 1x Ziti Fabric Router
- 1x Ziti Edge Router
- 1x Ziti Tunneler
- 1x Ziti Service (a demo netcat service)

It will also include provisioning and running a Ziti Tunneler with a demo netcat service. The services will use Ziti
router egress.  The full connection will be:

    SDK -> Edge Router -> Router -> Service

## A Note About Windows

These commands require a running BASH shell. Windows users will need to use WSL, [cygwin](https://www.cygwin.com/), a Linux virtual machine, or some other environment that supports BASH. The easiest thing might just be to use the shell that comes with [git bashfor windows](https://gitforwindows.org/). WSL is maturing more and more: [Mintty and WSL](https://github.com/mintty/wsltty).

Also note that the `ziti`command may need to have the `.exe` suffix appended to the example commands.

## Hosts File

This document assumes that the following hostnames will resolve on your local system:

- up-and-running-ctrl.ziti.netfoundry.io
- up-and-running-er01.ziti.netfoundry.io
- up-and-running-r01.ziti.netfoundry.io

This means that temporarily adding these to your system hosts file (outlined below) is required for this guide.

- Windows: `windows: %windir%\system32\drivers\etc\hosts`
- Linux: `/etc/hosts`

    127.0.0.1   up-and-running-ctrl.ziti.netfoundry.io
    127.0.0.1   up-and-running-er01.ziti.netfoundry.io
    127.0.0.1   up-and-running-r01.ziti.netfoundry.io

If you are deploying on multiple machines with their own resolvable hostnames, this is not required. However, it will
be necessary to alter the Environment Variable DNS San values to match your environment. Also, all generated Ziti
Identities (server, client, and private keys), configuration files, and binaries will need to be copied to the correct
hosts.

## Establish Environment Variables

The environment variables ZITI_HOME and ZITI_NETWORK will be used to boostrap an environment configuration file and directory structure to hold the various certificate, private keys, configuration files, and enrollment tokens that will be generated in this guide. This will help keep them separated on your file system for easy deletion later.

After these are defined an environment folder and 'env' file will be generated that can easily reset these values.

1. Define the boot strap environment variables

    ```bash
    export ZITI_NETWORK=up-and-running
    export ZITI_HOME=~/.ziti
    ```

    For Windows users: if a bash shell is being used some absolute paths may not work (i.e. /mnt/c/myziti). Using paths that start with `~` are generally safer. Using `.` will make configuration files and `env` files sensitive to the current working directory, but should work as long as the correct current working directory is maintained.

1. Generate the base directory structure and `env` file

    ```bash
    mkdir -p $ZITI_HOME
    
    cat <<SHELL > ${ZITI_HOME}/env
    export ZITI_HOME=${ZITI_HOME}
    export ZITI_NETWORK=${ZITI_NETWORK}
    export ZITI_ID="${ZITI_HOME}/identities.yml"
    export ZITI_CA_NAME="${ZITI_NETWORK}"
    export ZITI_PKI="${ZITI_HOME}/pki"
    export ZITI_CA_FILE="${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_CA_NAME}.cert"
    export ZITI_CTRL_HOSTNAME="${ZITI_NETWORK}-ctrl.ziti.netfoundry.io"
    export ZITI_ER01_HOSTNAME="${ZITI_NETWORK}-er01.ziti.netfoundry.io"
    export ZITI_R01_HOSTNAME="${ZITI_NETWORK}-r01.ziti.netfoundry.io"
    export ZITI_EDGE_API_PORT=1280
    export ZITI_EDGE_API_HOSTNAME="${ZITI_CTRL_HOSTNAME}:${ZITI_EDGE_API_PORT}"
    mkdir -p $ZITI_HOME/db
    mkdir -p $ZITI_PKI
    SHELL
    ```

    This file generated by the above snippet can be sourced any time to switch between working with multiple environments
    generated by this document or when starting new terminal windows.

    Source the newly created `env` file: `source ${ZITI_HOME}/env` or if the defaults were used `source .ziti/env`

    - `ZITI_HOME` - The root directory that should be consider the "HOME" directory (defaults to ~ if not set)
    - `ZITI_NETWORK` - The name of the network being worked with, this value is used as the basis for other file names. Should not contain spaces
    - `ZITI_PKI` - The location of the PKI used by `ziti pki` via the `--pki-root` option
    - `ZITI_CA_NAME` - The name of the signing CA that will be used for certificate generation and controller configuration. Defaults to the name of the network.
    - `ZITI_CA_FILE` - Location of the CA signing cert for ease of use using `ziti` CLI commands
    - `ZITI_CTRL_HOSTNAME` - DNS SANs for controller certificate generation, should match hosts file changes
    - `ZITI_ER01_HOSTNAME` - DNS SANs for edge router configuration, should match hosts file changes
    - `ZITI_R01_HOSTNAME` - DNS SANs for router certificate generation, should match hosts file changes
    - `ZITI_EDGE_API_PORT` - The port the Edge API will be available on
    - `ZITI_EDGE_API_HOSTNAME` - The hostname/port combination for the Ziti Edge API, used with `ziti edge` commands

## Create A Certificate Authority

All communication between Ziti components is secured using mutual TLS. In order to get a ziti environment running a certificate authority is required. This document guides the reader through creating a Root Certificate Authority (Root CA). It does not cover setups that should utilize Intermediate Certificate Authorities for production environments.

The `ziti` CLI will be significantly streamline and reduce the prerequisite knowledge required to generate a Root CA and signed certificates for client and server usage. Specifically the `ziti pki` command will do most of the heavy lifting.

1. Ensure that the `env` file is sourced if you are using a new terminal.

1. Create the CA

    ```bash
    ziti pki create ca --pki-root="${ZITI_PKI}" --ca-file="${ZITI_CA_NAME}"
    ```

    Additional certificate common name and subject fields can be set as needed. Run `ziti pki create ca -h` for options.

1. (Optional) Verify the output

    ```bash
    ls -l $ZITI_PKI/$ZITI_CA_NAME
    ```

    Example:

    ```bash
    total 0
    drwxr-xr-x 1 cd cd 512 Jan 28 16:39 certs
    drwx------ 1 cd cd 512 Jan 28 16:39 crls
    drwx------ 1 cd cd 512 Jan 28 16:39 keys
    -rw-r--r-- 1 cd cd   3 Jan 28 16:39 crlnumber
    -rw-r--r-- 1 cd cd 162 Jan 28 16:39 index.txt
    -rw-r--r-- 1 cd cd  20 Jan 28 16:39 index.txt.attr
    -rw-r--r-- 1 cd cd   3 Jan 28 16:39 serial
    ```

## Configure and Run a Controller

The following steps outline how to configure and start the Ziti Controller.

1. Ensure that the `env` file is sourced if you are using a new terminal.

1. Generate the controller Ziti Identity (server, client, and private key)

    Server

    ```bash
    ziti pki create server \
        --pki-root=$ZITI_PKI \
        --ca-name $ZITI_CA_NAME \
        --server-file "${ZITI_NETWORK}-ctrl-server" \
        --dns "${ZITI_CTRL_HOSTNAME}" \
        --ip "127.0.0.1" \
        --server-name "${ZITI_NETWORK} Controller"
    ```

    Client

    ```bash
    ziti pki create client \
        --pki-root=$ZITI_PKI \
        --ca-name ${ZITI_CA_NAME} \
        --client-file "${ZITI_NETWORK}-ctrl-client" \
        --key-file "${ZITI_NETWORK}-ctrl-server" \
        --client-name "${ZITI_NETWORK} Controller"
    ```

    Note: The client cert uses the controller server key as specified by `--key-file`.

    Additional certificate common name and subject fields can be set as needed. Run `ziti pki create server -h` or
     `ziti pki create client -h` for options.

    The Ziti Identity files are output in the following locations

    ```bash
    $ZITI_PKI/$ZITI_CA_NAME/certs/${ZITI_NETWORK}-ctrl-server.cert
    $ZITI_PKI/$ZITI_CA_NAME/certs/${ZITI_NETWORK}-ctrl-client.cert
    $ZITI_PKI/$ZITI_CA_NAME/keys/${ZITI_NETWORK}-ctrl-server.key
    ```

1. Generate the controller configuration file

    ```bash
    cat <<YAML > $ZITI_HOME/controller.yaml
    v: 3
    db:                     $ZITI_HOME/db/ctrl.db
    
    identity:
        cert:                 ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-ctrl-client.cert
        server_cert:          ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-ctrl-server.cert
        key:                  ${ZITI_PKI}/${ZITI_CA_NAME}/keys/${ZITI_NETWORK}-ctrl-server.key
        ca:                   ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}.cert
    
    ctrl:
        listener:             tls:127.0.0.1:6262
    
    mgmt:
        listener:             tls:127.0.0.1:10000    
    edge:
        api:
        listener:  0.0.0.0:1280
        advertise: ${ZITI_EDGE_API_HOSTNAME}
        sessionTimeoutMinutes: 30
        enrollment:
        signingCert:
            cert: ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}.cert 
            key:  ${ZITI_PKI}/${ZITI_CA_NAME}/keys/${ZITI_NETWORK}.key
        edgeIdentity:
            durationMinutes: 5
        edgeRouter:
            durationMinutes: 5
    YAML
    ```

1. Initialize the database if this is the first time you are going to start the controller

    ```bash
    # if needed, initialize the controller
    ziti controller edge init $ZITI_HOME/controller.yaml -u admin -p admin
    
    # run the controller
    ziti controller run $ZITI_HOME/controller.yaml
    ```

    Note that running this command will commandeer your current terminal. Use `screen` or multiple terminals by using
    `source` on the `env` file.

## Configure and Run a Fabric Router

This section outlines the steps necessary to configure and connect a router to the Ziti Controller. The router will be
named `r01` which is represented in the Common Name field of the certificates for the router. Routers join a controller
and create a mesh to provide long-haul transport.

To enroll a Ziti Router, the command line utility `ziti fabric` will be used that requires its own Ziti Identity in order
to connect to and control the fabric.

1. The `ziti fabric` command will be used to manage the fabric, a Ziti Identity must be generated to do that:

    ```bash
    ziti pki create client \
        --pki-root="${ZITI_PKI}" \
        --ca-name="${ZITI_CA_NAME}" \
        --client-file="${ZITI_NETWORK}-dotzeet" \
        --client-name "${ZITI_NETWORK} Management"
    ```

1. Generate a fabric identity that references the Ziti Identity:

    ```bash
    ziti fabric add-identity \
        --cli-identity "${ZITI_NETWORK} Management" \
        --ca-cert ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}.cert \
        --client-cert ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-dotzeet.cert \
        --client-key ${ZITI_PKI}/${ZITI_CA_NAME}/keys/${ZITI_NETWORK}-dotzeet.key
    ```

1. Login

    ```bash
    ziti edge login --cli-identity "${ZITI_NETWORK} Management"
    ```

1. Verify the identity works:

    ```bash
    ziti fabric list routers
    ```

1. Generate the Ziti Router identity

    Server

    ```bash
    ziti pki create server \
        --pki-root=$ZITI_PKI \
        --ca-name ${ZITI_CA_NAME} \
        --server-file "${ZITI_NETWORK}-r01-server" \
        --dns "${ZITI_R01_HOSTNAME}" \
        --ip 127.0.0.1 \
        --server-name r01
    ```

    Client

    ```bash
    ziti pki create client \
        --pki-root=$ZITI_PKI \
        --ca-name ${ZITI_CA_NAME} \
        --client-file "${ZITI_NETWORK}-r01-client" \
        --key-file "${ZITI_NETWORK}-r01-server" \
        --client-name r01
    ```

1. Generate the router configuration file:

    ```bash
    cat <<YAML > $ZITI_HOME/r01.yaml
    v: 2
       
       identity:
         cert:                 ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-r01-client.cert
         server_cert:          ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-r01-server.cert
         key:                  ${ZITI_PKI}/${ZITI_CA_NAME}/keys/${ZITI_NETWORK}-r01-server.key
         ca:                   ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-r01-server.chain.pem
       
       ctrl:
         endpoint:             tls:${ZITI_CTRL_HOSTNAME}:6262
       
       link:
         listener:             quic:127.0.0.1:6002
       
       listeners:
         - binding:            transport
           address:            tls:0.0.0.0:7002
    YAML
    ```

1. Enroll the Ziti Router identity with the controller

    ```bash
    ziti fabric create router "${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-r01-client.cert"
    ```

    Verify:

    ```bash
    ziti fabric list routers
    ```

    Should show 1 router named `r01`.

1. Start the router:

    ```bash
    ziti router run $ZITI_HOME/r01.yaml
    ```

    Note that running this command will commandeer your current terminal. Use `screen` or multiple terminals by using
    `source` on the `env` file.

## Configure and Run an Edge Router

A Ziti Edge Router allows the Ziti SDK to ingress to a Ziti overlay network. A Ziti Edge Router is a Ziti Router that has the `edge`
section of the configuration defined and has gone through the Edge Router Enrollment process instead of the Ziti Router
enrollment process. Ziti Edge Routers and Ziti Routers are run from the same binary `ziti router`.

Ensure that the `env` file is sourced if you are using a new terminal.

1. Authenticate w/ the controller if not authenticated

    ```bash
    #update username / password if the default admin password has been updated
    ziti edge login ${ZITI_EDGE_API_HOSTNAME} -u admin -p admin
    ```

1. Create a edge router and output the JWT to a file:

    ```bash
    ziti edge create edge-router er01 cluster01 -o $ZITI_HOME/er01.jwt
    ```

1. Create the edge router configuration file

    ```bash
    cat <<YAML > $ZITI_HOME/er01.yaml
    v: 2
    
    identity:
        cert:                 ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-er01-client.cert
        server_cert:          ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-er01-server.cert
        key:                  ${ZITI_PKI}/${ZITI_CA_NAME}/keys/${ZITI_NETWORK}-er01-server.key
        ca:                   ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-er01-server.chain.cert
    
    ctrl:
        endpoint:             tls:${ZITI_CTRL_HOSTNAME}:6262
    
    edge:         
        csr:
        country: US
        province: NC
        locality: Charlotte
        organization: NetFoundry
        organizationalUnit: Ziti
        sans:
            dns:
            - ${ZITI_NETWORK}-er01.ziti.netfoundry.io
            ip:
            - "127.0.0.1"

    dialers:
        - binding: udp
        - binding: transport
    
    listeners:
        - binding: edge
        address: tls:0.0.0.0:3022
        options:
            advertise: ${ZITI_NETWORK}-er01.ziti.netfoundry.io:3022
        - binding: transport
        address: tls:0.0.0.0:7099    
    YAML
    ```

1. Complete the enrollment process with the controller

    ```bash
    ziti router enroll $ZITI_HOME/er01.yaml --jwt $ZITI_HOME/er01.jwt
    ```

1. Start the edge router:

    ```bash
    ziti router run $ZITI_HOME/er01.yaml
    ```

    Note that running this command will commandeer your current terminal. Use `screen` or multiple terminals by using
    `source` on the `env` file.