From 0969b5fc726ec06bb861a5f54d18e1f58d910d36 Mon Sep 17 00:00:00 2001 From: Andrew Martinez Date: Wed, 18 Dec 2019 16:17:51 -0500 Subject: [PATCH] netfoundry/ziti-cmd#15 moves some doc to ziti-cmd --- doc/001-overview.md | 84 ------- doc/002-local-dev.md | 194 --------------- doc/003-local-deploy.md | 536 ---------------------------------------- 3 files changed, 814 deletions(-) delete mode 100644 doc/001-overview.md delete mode 100644 doc/002-local-dev.md delete mode 100644 doc/003-local-deploy.md diff --git a/doc/001-overview.md b/doc/001-overview.md deleted file mode 100644 index 95388d926..000000000 --- a/doc/001-overview.md +++ /dev/null @@ -1,84 +0,0 @@ -# Ziti Overview - -Ziti is split into two main domains that run in the same process space: - -- Ziti Fabric -- Ziti Edge - -## Fabric & Edge -The Ziti Fabric is a core set of features used to support defining and managing services, routers, and -sessions to route traffic across a robust and secure overlay network. Ziti Fabric features are always enabled and -cannot be disabled. - -The Ziti Edge is a set of features that can be enabled on top of the Ziti Fabric features to enable enrollment -and management of endpoints that make use of the Ziti SDK. The Ziti SDK can be built into applications to provide -ingress and egress to the Ziti overlay network as well as to provide application specific networking to an individual -application. Enabling the Edge features is optional. - -Both the Fabric and Edge features are built into the ziti-controller and ziti-router binaries. - -## Ziti Controller -The Ziti Controller (ziti-controller) is the main server component of a Ziti environment. It is the first piece of Ziti -that must be setup and configured. The controller houses all the router, service, and management data necessary -to run a Ziti environment. There is one, and only one, controller per Ziti environment. - -The Ziti Controller can optionally host the Ziti Edge features. The Fabric features within the controller -supports managing routers, services, and creating circuits across a mesh network to route traffic, but does not support -accepting connections from endpoints utilizing the Ziti SDK, provide a configurable policy management for endpoint -connectivity, and endpoint enrollment. - -## Ziti Router - The Ziti Router binary (ziti-router) is deployed multiple times to stand up multiple ingress and egress - points for a Ziti overlay network. Each router has its own identity and must be enrolled with the controller. - A Ziti environment requires one or more routers. - - If the Ziti Edge features are enabled, routers may optionally be enrolled as an "edge router". Edge routers allow Ziti - SDK enabled applications, Ziti Applications, to access services or host services that have been configured within Ziti - as overlay services. - -# Ziti Applications - -Below is an outline of all the applications that are generated from this repository. - -## Servers - -The following binaries are used to deploy long running servers that route traffic and manage the -configuration of a Ziti environment. - -| Binary Name | Description| -|-------------------| -----------| -| ziti-controller | Runs a central server necessary for Ziti environments| -| ziti-router | Runs a server capable of ingress'ing and egress'ing Ziti traffic standalone or as a mesh| - - -## Tools -The following binaries provide utility or testing functionality. - -| Binary Name | Description| -|-------------------| -----------| -| ziti-enroller | Provides enrollment processing features for executables that do not directly support enrollment -| ziti-fabric-gw | Provides JSON RCP web service access to Ziti fabric management features -| ziti-fabric-test | The Ziti Fabric Toolbox which is used to test deployed fabric components| - - -## Management - -The following binaries are used to configure and manage a Ziti environment via command line interactions. - -| Binary Name | Description| -|-------------------| -----------| -| ziti-fabric | Provides command line access to Ziti Fabric management features| -| ziti | Provides command line access to Ziti Edge management features| - -# Endpoint Clients -The following binaries are Ziti endpoint clients which have the Ziti SDK built into them and can connected to an -edge router. Endpoint clients can be application specific or act as a bridge to other applications, hosts, or underlay -networks. - -| Binary Name | Description| -|-------------------| -----------| -| ziti-proxy | Provides the ability to proxy connections across a Ziti| -| ziti-tunnel | Provides the ability to intercept traffic to route traffic across Ziti| - - -All of the above binaries are cross platform compatible, except ziti-tunnel which is currently Linux only. \ No newline at end of file diff --git a/doc/002-local-dev.md b/doc/002-local-dev.md deleted file mode 100644 index aa270303a..000000000 --- a/doc/002-local-dev.md +++ /dev/null @@ -1,194 +0,0 @@ -# Overview - -This README aims to allow the setup of a development local environment as quick as possible. It uses predefined -configuration files that are maintained with the source code as well as Docker to run ancillary services (such as -databases). - -# Dependencies - -- Go 1.12+ -- PostgresSQL v10+ (if running Ziti Edge) - - -# Debugging - -This guide can be used to run all of the Ziti applications via command line or in the debugger of an IDE. The only -requirement is that the CLI start in/the debuggers current working directory is assumed to be your $GOPATH. - - -# Get Started - -### Checkout & Build - -Checkout the entire `ziti` repot to a `$GOPATH/src/bitbucket.org/netfoundry` directory. - -Build the entire project and all binaries or just the Ziti Edge portion: - -To install all: ```go install bitbucket.org/netfoundry/ziti/...``` - -...which will build and install the binaries into `$GOPATH/bin`. All future `ziti` commands will run binaries from here. - -### Start PostgreSQL - -If Ziti Edge functionality will be used it will be necessary to start a PostgreSQL database. This database can be on -any machine, but the default configuration file assume that the database is running on localhost. - -``` -docker run -it --name local-postgres -e POSTGRES_PASSWORD=ztpassword -p 5432:5432 postgres -``` - -Please note that the default `ztpassword` exists in the `edge.router.yml` file used below to start a router -running with Edge functionality enabled. - -### Starting the Controller - -If you wish to start the controller with the Ziti Fabric and Ziti Edge enabled: - -``` -ziti-controller run $GOPATH/src/github.com/netfoundry/ziti-fabric/etc/ctrl.with.edge.yml -``` - - -If you wish to start the Ziti Fabric standalone: - -``` -ziti-controller run $GOPATH/src/github.com/netfoundry/ziti-fabric/etc/ctrl.yml -``` - -Please note that if you start the controller without the Ziti Edge enabled, the Ziti SDK, and edge router functionality -will not be usable. The controller can be started and stopped both ways without issue. The only requirement is that the -PostgrSQL database must be running if the Ziti Edge functionality is enabled. - - -# Starting Routers - -The Ziti Fabric requires at least one router (fabric router or edge router). There are four predefined configuration files -for running routers in `ziti/fabric/etc/` named `001.yml` to `004.yml`. - -Each configuration file refers to certificate and private keys kept in `ziti/fabric/etc/ca/intermediate/certs` and -`ziti/fabric/etc/ca/intermediate/private/`. The steps for starting the router is to first register the router then -start it. - -Register: - -``` -ziti-fabric create router $GOPATH\src\bitbucket.org\netfoundry\ziti\fabric\etc\ca\intermediate\certs\XXX-client.cert.pem -``` - -Where `XXX` is replaced with `001` through `004`. - -Run: - -``` -ziti-router run $GOPATH/src/github.com/netfoundry/ziti-fabric/etc/XXX.yml -``` - -Where `XXX` is replaced with `001` through `004`. - -# Starting Router As An Edge Router - -Edge routers are routers that have the Edge functionality enabled and allow Ziti SDK enabled application to connect to -Ziti. Starting an edge eouter requires that the controller be running with the Edge functionality -enabled. This requires the use of the `ctrl.with.edge.yml` configuration to run the controller (see example above). - -To start an edge router the Edge REST API will be used to prime the enrollment process and the -`ziti-router enroll` command will be used to finalize the process. The enrollment command will handle adding the fabric -and edge router entries necessary. Using the `ziti-fabric create router` command should not and can not be run. - - -There is only one example configuration file for an edge router: -`ziti/fabric/etc/edge.router.yml`. Additional configuration files can be created by copying and altering the -file. Specifically the identity section needs to point to unique file locations that do not collide with other identity -file and the listening ports need to not be in use. - -### Authenticate w/ the Ziti Edge API - -``` -POST /authenticate?method=password -{ - "username": "admin", - "password": "admin" -} -``` - -Authentication will return a session token that should be supplied either as a cookie (also returned) or a HTTP header -called `zt-session`. All subsequent requests will either need to set the HTTP set `zt-session` or provide the cookie in -every request. - - -### Create a Cluster / List Clusters - -A `cluster id` is necessary to create an edge router. A cluster must be created or if one already exists, it can be used. - -List: - -``` -GET /clusters -``` - -Create: - -``` -POST /clusters -{ - "name": "My Cluster", -} -``` - -### Create A Cluster - -``` -POST /clusters -{ - "name": "My Cluster", -} -``` - -A `clustet id` will be provided in the response as `id`. Retain for later use. - -### Create An Edge Router -``` -POST /edge-routers -{ - "name": "My Edge Router", - "clusterId": "" -} -``` - -...where `cluster id` is replaced with a valid cluster id that already exists or was created. It can be re-retrieved by -listing the existing clusters via `GET /clusers`. The response from creating an edge router should contain an id in -the `id` field. Retain for later use. - -### Retrieve the Edge Router Enrollment Token - -``` -GET /edge-routers/ -``` - -...where `id` is provided in the response to creating an edge router. It can be re-retrieved by listing the existing -edge routers via `GET /edge-routers`. The response from retrieving a edge router should contain an enrollment JWT in the -`enrollmentJwt` field. Retain the enrollment JWT in a text file named `enrollment.jwt`. - -### Enroll the Edge Router - -``` -ziti-router enroll --jwt $GOPATH/src/github.com/netfoundry/ziti-fabric/etc/edge.router.yml -``` - -...where `path to enrollment.jwt` is the enrollment JWT for the edge router. - -### Start Ziti Edge Router - -``` -ziti-router run $GOPATH/src/github.com/netfoundry/ziti-fabric/etc/edge.router.yml -``` - -# Further Exploration - -At this point the controller should be running with some number of routers running. It is now possible -to explore the Ziti Fabric capabilities via the `ziti-fabric` executable. - -If the controller was started with the Edge -functionality enabled the Ziti Edge API can be explored. A POSTMAN collection can be found in - `ziti/edge/controller/postman` and the Ziti SDK can be found in `ziti/sdk`. Additionally the `ziti-enroller`, `ziti-tunnel` and - `ziti-proxy` have the Ziti SDK embedded within them to act as a starting point for using Ziti end-to-end. \ No newline at end of file diff --git a/doc/003-local-deploy.md b/doc/003-local-deploy.md deleted file mode 100644 index 5029fbac4..000000000 --- a/doc/003-local-deploy.md +++ /dev/null @@ -1,536 +0,0 @@ -# Overview - -This document covers how to deploy Ziti from the ground up on a single local machine. After following this guide, it -should be possible to extrapolate the setup to multiple machines. This setup includes both the Fabric and optional -Edge components: - -- 1x Ziti Controller + Edge -- 1x Ziti Edge Router -- 1x Ziti 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 - -It is also possible to host a service and thus avoid egress through a router: - - Client SDK -> Edge Router -> Routers (0...1) -> Edge Router -> Server SDK - -This document will guide the former. - -For binaries, this guide provides instructions to build them for your local environment. It is also possible to acquire -pre-built binaries from the [NetFoundry Artifactory repository](https://netfoundry.jfrog.io/netfoundry/webapp/#/artifacts/browse/tree/General/ziti-release/ziti-all) -which does require a NetFoundry login. Extract the contents an use the binaries for your platform - ensuring that they -are on your path. - -## Build Requirements -If building your own binaries - -- A Golang environment (1.12 or later) -- A NetFoundry email address tied to a Bitbucket account with SSH keys - -## Quick steps to a Building Binaries - -It is not possible to simply use `go get bitbucket.org/netfoundry/ziti` as `go get` does not support specifying an -identity file (i.e. SSH keys). Instead the repo must first be retrieved by `git clone`. - -### Linux/MacOS - - repo_dir=~/repos/nf - mkdir ${repo_dir} - cd ${repo_dir} - git clone git@bitbucket.org:netfoundry/ziti.git - cd ziti - export GOPATH=$(pwd)/build - go install ./fabric/... ./edge/... ./cli/... - -### Windows - - set repo_dir=%userprofile%\repos\nf - mkdir %repo_dir% - cd /d %repo_dir% - git clone git@bitbucket.org:netfoundry/ziti.git - cd /d %repo_dir%\ziti - set GOPATH=%cd%\build - go install ./fabric/... ./edge/... ./cli/... - -After you have cloned your repository and ensured it can build, change to $GOPATH or -%GOPATH% and execute `bin/ziti`. If everything is working properly you should be greeted -with the ziti command line help. - -## Setting up your first environment - -Now that you have ziti cloned and compiling, the next step is to get your very first -environment running. These steps will bring you through setting up your first environment -with ziti. We will: - -* [Requirements](#Requirements) -* [Establish Environment Variables](#Establish-Environment-Variables) -* [Create A Certificate Authority](#Create A Certificate Authority) -* [Configure & Run A Ziti Controller](#Configure-&-Run-A-Ziti-Controller) -* [Configure & Run A Ziti Router](#Configure-&-Run-A-Ziti-Router) -* [Configure & Run A Ziti Edge Router](#Configure-&-Run-A-Ziti-Edge-Router) -* [Configure A Service & Ziti Tunneler](#Configure-A-Service-&-Ziti-Tunneler) -* [Configuring a hosted service](#Configuring-A-Hosted-Service) - -## Requirements - -### Required Tooling - -- A bash shell -- nc (netcat) - -### A note on Windows -These commands all require a running bash shell. Windows users this means you'll need to use -WSL, [cygwin](https://www.cygwin.com/), a Linux virtual machine, or some other environment that supports a bash compliant -shell. 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 commands for `ziti`, `ziti-fabric`, `ziti-controller`, and `ziti-router` may need to have the `.exe` -suffix added into the command provided in this document. - -### 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 - - 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 - - mkdir -p $ZITI_HOME - - echo -e "export ZITI_HOME=${ZITI_HOME}\n\ - export ZITI_NETWORK=${ZITI_NETWORK}\n\ - export ZITI_ID=\"\${ZITI_HOME}/identities.yml\"\n\ - export ZITI_CA_NAME=\"\${ZITI_NETWORK}\"\n\ - export ZITI_PKI=\"\${ZITI_HOME}/pki\"\n\ - export ZITI_CA_FILE=\"\${ZITI_PKI}/\${ZITI_CA_NAME}/certs/\${ZITI_CA_NAME}.cert\"\n\ - export ZITI_CTRL_HOSTNAME=\"\${ZITI_NETWORK}-ctrl.ziti.netfoundry.io\"\n\ - export ZITI_ER01_HOSTNAME=\"\${ZITI_NETWORK}-er01.ziti.netfoundry.io\"\n\ - export ZITI_R01_HOSTNAME=\"\${ZITI_NETWORK}-r01.ziti.netfoundry.io\"\n\ - export ZITI_EDGE_API_PORT=1280\n\ - export ZITI_EDGE_API_HOSTNAME=\"\${ZITI_CTRL_HOSTNAME}:\${ZITI_EDGE_API_PORT}\"\n\ - mkdir -p \$ZITI_HOME/db - mkdir -p \$ZITI_PKI - " > ${ZITI_HOME}/env - - 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 controller` 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 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 - - 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 - - ls -l $ZITI_PKI/$ZITI_CA_NAME - - Example: - - 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-&-Run-A-Ziti-Controller - -### Postgres - -A Postgres installation is required for the Edge components of the Ziti Controller to operate. If an existing Postgres -instance is available, then substitute the connection information in the controller configuration that is generated -in this section. - -It is suggested that Postgres be installed via Docker; as outlined below. - -If desired, Postgres can be installed on your host machine via your platforms package management system (if available) -or directly from https://www.postgresql.org/. The Docker approach is highly encouraged for easy tear down. - -### Configure & Start - -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. Start a Postgres environment on your local machine (either local installation or Docker container, Docker commands provided below: - - - Install & Run: `docker run --name pg -d -e POSTGRES_PASSWORD=ztpassword -p 5432:5432 postgres` - - Stop: `docker stop pg` - - Start: `docker start pg` - - Verify: `docker ps` see the `postgres` image is running under name `pg` - -1. Generate the controller Ziti Identity (server, client, and private key) - - Server - - 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 - - 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 - - $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 - - echo " - 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 - persistence: - connectionUrl: postgres://postgres:ztpassword@localhost/postgres?sslmode=disable - dbName: postgres - " > $ZITI_HOME/controller.yaml - -1. Initialize the database if this is the first time you are going to start the controller - - # 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 & Run A Ziti 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. - -To configure more routers, repeat steps 3+ from below but be sure to -- alter the `--server-name`, `--client-name`, and `--dns` parameters in all commands -- update the hosts file with any new hostnames - -1. The `ziti-fabric` command will be used to manage the fabric, a Ziti Identity must be generated to do that: - - - 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 an `identities.json` file that references the Ziti Identity: - - echo " - --- - default: - caCert: ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}.cert - cert: ${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-dotzeet.cert - key: ${ZITI_PKI}/${ZITI_CA_NAME}/keys/${ZITI_NETWORK}-dotzeet.key - endpoint: tls:127.0.0.1:10000 - " > $ZITI_HOME/identities.yml - -1. Verify the identity works: - - ziti-fabric list routers - - Note: If 127.0.0.1 was not included in the controller cert, use the `-e` flag to set the address to the controller - (`ziti-fabric -e "tls:up-and-running-ctrl.ziti.netfoundry.io:10000" list routers` ) on this an all future - `ziti-fabric` command. - -1. Generate the Ziti Router identity - - Server - - 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 - - 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: - - echo "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 - " > $ZITI_HOME/r01.yaml - -1. Enroll the Ziti Router identity with the controller - - ziti-fabric create router "${ZITI_PKI}/${ZITI_CA_NAME}/certs/${ZITI_NETWORK}-r01-client.cert" - - Verify: - - ziti-fabric list routers - - Should show 1 router named `r01`. - -1. Start the router: - - 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 & Run A Ziti 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 - - #update username / password if the default admin password has been updated - ziti edge controller login ${ZITI_EDGE_API_HOSTNAME} -u admin -p admin -c ${ZITI_CA_FILE} - -1. Create a cluster - - ziti edge controller create cluster cluster01 - -1. Create a edge router and output the JWT to a file: - - ziti edge controller create edge-router er01 cluster01 -o $ZITI_HOME/er01.jwt - -1. Create the edge router configuration file - - echo " - 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 - " > $ZITI_HOME/er01.yaml - -1. Complete the enrollment process with the controller - - ziti-router enroll $ZITI_HOME/er01.yaml --jwt $ZITI_HOME/er01.jwt - -1. Start the edge router: - - 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. - - -## Configure A Service & Ziti Tunneler - -1. Authenticate w/ the controller if not authenticated - - #update username / password if the default admin password has been updated - ziti edge controller login ${ZITI_EDGE_API_HOSTNAME} -u admin -p admin -c ${ZITI_CA_FILE} - -1. Create a service that will facilitate connecting to a local netcat server listening on port 7256 and that egresses -the Ziti Fabric on our "r01" router - - ziti edge controller create service netcat7256 localhost 7256 r01 tcp://localhost:7256 - - -1. Create a Ziti Edge Identity for the Ziti Tunneler process - - ziti edge controller create identity device identity01 -o $ZITI_HOME/identity01.jwt - -1. Create an AppWan to associate the Ziti Tunneler identity (identity01) to the service (netcat7256) - - ziti edge controller create app-wan appwan01 -s netcat7256 -i identity01 - -1. Enroll the Ziti Tunneler's identity - - ziti-enroller --jwt $ZITI_HOME/identity01.jwt -o $ZITI_HOME/identity01.json - -1. Start the Ziti Tunneler in proxy mode - - ziti-tunnel proxy netcat7256:8145 -i $ZITI_HOME/identity01.json - -1. Start the netcat server - - nc -k -n 127.0.0.1 -l 7256 - -1. Start the netcat client that will connect to the Ziti Tunnel proxy - - nc -v 127.0.0.1 8145 - - -## Configuring A Hosted Service - -Services can also be hosted by another SDK. For this to work a second Ziti Tunneler can be setup to act as the host. The -exact details of this are beyond this document but the high level steps are outlined below: - -1. Create a new Ziti Identity via `ziti edge controller identity create` to allow another Ziti Tunneler to run -1. Enroll the Ziti Identitiy via `ziti-enroller` -1. Add the new Ziti Identity to the hosts of a new service or an existing service -1. Start the new Ziti Tunneler - - - -Example Hosted Service - -```sh -ziti edge controller create service \ ---hosted ---hosted-ids ---tags tunneler.dial.addr=
-``` - -Example: -```` -ziti edge controller create service postgresql pg 5432 \- ---hosted ---hosted-ids 40c025cb-bc92-4a54-b55f-1429412f2644 --tags tunneler.dial.addr=tcp:127.0.0.1:5432 -``` -