gsadmin/ziti
1
0
Fork 0
mirror of https://github.com/openziti/ziti.git synced 2026-10-14 08:10:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

netfoundry/ziti-cmd#15 moves some doc to ziti-cmd

Browse Source
This commit is contained in:
Andrew Martinez
2019-12-18 16:17:51 -05:00
parent f3ec635198
commit 0969b5fc72
3 changed files with 0 additions and 814 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/001-overview.md
-84
View File
@@ -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.
doc/002-local-dev.md
-194
View File
@@ -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": "<cluster id>"
}
```
...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/<id>
```
...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 <path to enrollment.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.
doc/003-local-deploy.md
-536
View File
@@ -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 <service name> <dns host> <dns port> \
--hosted
--hosted-ids <someIdentityId>
--tags tunneler.dial.addr=<address for tunneler to dial>
```
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
```