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

md eol fix

Browse Source
This commit is contained in:
Andrew Martinez
2020-01-15 11:16:04 -05:00
parent 0cecc8b28f
commit 0129b80b84
2 changed files with 230 additions and 230 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/001-overview.md
+82 -82
View File
@@ -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.
doc/002-local-dev.md
+148 -148
View File
@@ -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/<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> 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/<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> 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.