diff --git a/doc/001-overview.md b/doc/001-overview.md index e32e7d2d4..c24a3af61 100644 --- a/doc/001-overview.md +++ b/doc/001-overview.md @@ -1,83 +1,83 @@ -# 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 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-tunnel | Provides the ability to intercept traffic to route traffic across Ziti| - - +# 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 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-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 index 8ed589ccc..bf0a43c3d 100644 --- a/doc/002-local-dev.md +++ b/doc/002-local-dev.md @@ -1,149 +1,149 @@ -# 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+ - - -# Debugging - -This guide can be used to run all of the Ziti applications via command line or in the debugger of an IDE. - - -# Get Started - -### Checkout & Build - -1. Checkout the `ziti-cmd` repository from `github.com/netfoundry/ziti-cmd` - - `git clone https://github.com/netfoundry/ziti-cmd.git` -2. Change into the `ziti-cmd` dirrectory - - `cd ziti-cmd` -3. Build - - `go build ./ziti-controller` - - `go build ./ziti-router` - - `go build ./ziti/cmd/ziti` - - -### Starting the Controller - -If you wish to start the controller with the Ziti Fabric and Ziti Edge enabled: - -``` -ziti-controller run etc/ctrl.with.edge.yml -``` - - -If you wish to start the Ziti Fabric standalone: - -``` -ziti-controller run 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. - - -# 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 `etc/` named `001.yml` to `004.yml`. - -Each configuration file refers to certificate and private keys kept in `etc/ca/intermediate/certs` and -`etc/ca/intermediate/private/`. The steps for starting the router is to first register the router then -start it. - -Register: - -``` -ziti-fabric create router etc/ca/intermediate/certs/XXX-client.cert.pem -``` - -Where `XXX` is replaced with `001` through `004`. - -Run: - -``` -ziti-router run 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: -`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 - -Please note that this is not a complete API reference and all of these request have analogous commands in the Ziti CLI via the `ziti` binary. - -``` -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 An Edge Router -``` -POST /edge-routers -{ - "name": "My Edge Router", -} -``` - - -### 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 etc/edge.router.yml -``` - -...where `path to enrollment.jwt` is the enrollment JWT for the edge router. - -### Start Ziti Edge Router - -``` -ziti-router run 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 `github.com/netfoundry/ziti-edge/controller/postman` and the Ziti SDK can be found in -`netfoundry/ziti-sdk-golang`. +# 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+ + + +# Debugging + +This guide can be used to run all of the Ziti applications via command line or in the debugger of an IDE. + + +# Get Started + +### Checkout & Build + +1. Checkout the `ziti-cmd` repository from `github.com/netfoundry/ziti-cmd` + - `git clone https://github.com/netfoundry/ziti-cmd.git` +2. Change into the `ziti-cmd` dirrectory + - `cd ziti-cmd` +3. Build + - `go build ./ziti-controller` + - `go build ./ziti-router` + - `go build ./ziti/cmd/ziti` + + +### Starting the Controller + +If you wish to start the controller with the Ziti Fabric and Ziti Edge enabled: + +``` +ziti-controller run etc/ctrl.with.edge.yml +``` + + +If you wish to start the Ziti Fabric standalone: + +``` +ziti-controller run 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. + + +# 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 `etc/` named `001.yml` to `004.yml`. + +Each configuration file refers to certificate and private keys kept in `etc/ca/intermediate/certs` and +`etc/ca/intermediate/private/`. The steps for starting the router is to first register the router then +start it. + +Register: + +``` +ziti-fabric create router etc/ca/intermediate/certs/XXX-client.cert.pem +``` + +Where `XXX` is replaced with `001` through `004`. + +Run: + +``` +ziti-router run 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: +`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 + +Please note that this is not a complete API reference and all of these request have analogous commands in the Ziti CLI via the `ziti` binary. + +``` +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 An Edge Router +``` +POST /edge-routers +{ + "name": "My Edge Router", +} +``` + + +### 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 etc/edge.router.yml +``` + +...where `path to enrollment.jwt` is the enrollment JWT for the edge router. + +### Start Ziti Edge Router + +``` +ziti-router run 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 `github.com/netfoundry/ziti-edge/controller/postman` and the Ziti SDK can be found in +`netfoundry/ziti-sdk-golang`. Additionally the `ziti-enroller` and `ziti-tunnel` command in this repository contain reference implementations. \ No newline at end of file