openziti · qrkourier · Sep 30, 2023 · Sep 6, 2023
@@ -1,13 +1,13 @@
 <br/>
 
-The `ziti` CLI will help you get a session from the controller's management API. You will be prompted to trust any new server certificates. Your session cache and trust store are managed by the CLI in your home directory.
+The `ziti` CLI will help you get an API Session from the controller's management API. You will be prompted to trust any new server certificates. Your login token cache and trust store are managed by the CLI in your home directory.
 
-```bash
+```text
 # implies https://localhost:1280
 ziti edge login -u admin -p admin
 ```
 
-```bash
+```text
 # implies https://
 ziti edge login ziti.example.com:8441 -u admin -p admin
 ```
@@ -1,11 +1,8 @@
 ---
 title: Data Flow Explainer
-sidebar_label: Data Flow Explainer
 sidebar_position: 30
 ---
 
-# Data Flow Explainer
-
 This explainer walks through how data flow is established in an OpenZiti network.
 
 ## Baseline
@@ -19,9 +16,9 @@ It has the following components:
 * An OpenZiti controller
 * Two OpenZiti routers that are available via the public internet
 * Two private networks, each containing a router and an application server
-    * The application servers are serving up the same application. There are multiple servers, so
-      that load can be spread across them. They are in separate regions to ensure that the
-      application can still be accessed, even if a datacenter becomes unavailable.
+  * The application servers are serving up the same application. There are multiple servers, so
+    that load can be spread across them. They are in separate regions to ensure that the
+    application can still be accessed, even if a datacenter becomes unavailable.
 * An SDK application which wants to access the application hosted by the application servers
 
 ## Control Channels
@@ -82,7 +79,7 @@ When an SDK wants to connect to an OpenZiti hosted service, it will initiate the
 of events:
 
 1. Authenticate to the controller
-2. Create a Service Session for the desired service
+2. Create a Session for the desired service
 3. Connect to one or more edge routers
 4. Send a Dial request to the selected edge router
 5. The edge router will send a create circuit request to the controller
@@ -105,18 +102,18 @@ An API Session can be extended, so a single API Session can generally be used fo
 the application. A new API Session may be required if the application is unable to reach the
 controller for an extended period of time.
 
-### Create Service Session
+### Create Session
 
-The SDK must now create a Service Session. When creating a Service Session, the controller will
+The SDK must now create a Session. When creating a Session, the controller will
 verify that the identity used by the SDK has permission to access the service. The controller will
 also see which edge routers can be used to access the session. The set of edge routers will be
-returned along with the Service Session token.
+returned along with the Session token.
 
 ![image](/img/data-flow/client-session.png)
 
 ### Connect to Edge Routers
 
-The returned Service Session contains the edge routers that can be used for this service along with
+The returned Session contains the edge routers that can be used for this service along with
 the address or addresses that each router is listening on for SDK connections. The SDK will connect
 to the edge routers and use whichever one connects the fastest. The edge router connections are not
 per-service, but will be shared by all services. If the connections are already made, the SDK will
@@ -131,7 +128,7 @@ routers will be notified and connections associated with that API Session will b
 ### Dial the Service
 
 The SDK will pick an edge router and send it a Dial request for desired service along with the
-Service Session token. The edge router selected is known as the initiating router. The edge router
+Session token. The edge router selected is known as the initiating router. The edge router
 will translate this into a 'create circuit' request to the controller. The controller will select a
 path and will message the routers in the path, so they can update their routing tables and/or make
 connections to application servers as necessary.
@@ -159,4 +156,3 @@ controller notifies the initiating router and data can now flow between the SDK
 server.
 
 ![image](/img/data-flow/circuit.png)
-
@@ -19,7 +19,7 @@ Application Client ->Ziti SDK : TCP Connection (3 way handshake)
 note over Ziti SDK : Edge Router Selection
 Ziti SDK ->Controller : Dial Request
 
-Ziti SDK -> Controller :Initiating Edge Router\nEdge Session Token\nService ID\nDial Options
+Ziti SDK -> Controller :Initiating Edge Router's\nSession Token\nService ID\nDial Options
 
 
 

@@ -5,7 +5,7 @@ Metrics are reported to the log files, locale in /var/log/ziti by default.  Ther
 | Metric | Type | Source | Description|
 |------------------------|-----------|------------|-----------------------------------------------------------------------------------------------------|
 |api-session.create | Histogram | controller | Time to create api sessions|
-|api.session.enforcer.run | Timer | controller | How long it takes the api session policy enforcer to run|
+|api.session.enforcer.run | Timer | controller | How long it takes the API Session policy enforcer to run|
 |bolt.open_read_txs | Gauge | controller | Current number of open bbolt read transactions|
 |ctrl.latency | Histogram | controller | Per control channel latency|
 |ctrl.queue_time | Histogram | controller | Per control channel queue time (between send and write to wire)|
@@ -15,8 +15,8 @@ Metrics are reported to the log files, locale in /var/log/ziti by default.  Ther
 |ctrl.tx.bytesrate | Meter | controller | Per control channel send data rate|
 |ctrl.tx.msgrate | Meter | controller | Per control channel send message rate|
 |ctrl.tx.msgsize | Histogram | controller | Per control channel send messsage size distribution|
-|edge.invalid_api_tokens | Meter | router | Number of invalid api session token encountered|
-|edge.invalid_api_tokens_during_sync | Meter | router | Number of invalid api session token encountered while a sync is in progress|
+|edge.invalid_api_tokens | Meter | router | Number of invalid API Session token encountered|
+|edge.invalid_api_tokens_during_sync | Meter | router | Number of invalid API Session token encountered while a sync is in progress|
 |egress.rx.bytesrate | Meter | router | Data rate of data received via xgress, originating from terminators. Per router.|
 |egress.rx.msgrate | Meter | router | Message rate of data received via xgress, originating from terminators. Per router.|
 |egress.rx.msgsize | Histogram | router | Message size distribution of data received via xgress, originating from terminators. Per router.|
@@ -49,7 +49,7 @@ Metrics are reported to the log files, locale in /var/log/ziti by default.  Ther
 |service.policy.enforcer.run | Timer | controller | How long it takes the service policy enforcer to run|
 |service.policy.enforcer.run.deletes | Meter | controller | How many sessions are deleted by the service policy enforcer|
 |services.list | Histogram | controller | Time to list services|
-|session.create | Histogram | controller | Time to create a session|
+|session.create | Histogram | controller | Time to create an API Session|
 |xgress.ack_duplicates | Meter | router | Number of duplicate acks received. Indicates over-eager retransmission|
 |xgress.ack_failures | Meter | router | Number of failures sending acks|
 |xgress.acks.queue_size | Gauge | router | Number of acks queued to send|

@@ -11,7 +11,7 @@ Grafana has a marvelous datasource type called [Infinity](https://grafana.com/gr
 ### Configure the datasource
 The configuration of the datasource is simple, but a little nonintuitive.
 
-We set the name of the server, in this case our OpenZiti Network Controller, but no authentication.  This seems odd for a secure network, but the datasource does not provide (at this level) the tools we need to interact with the authentication endpoint to receive an API session token.  
+We set the name of the server, in this case our OpenZiti Network Controller, but no authentication.  This seems odd for a secure network, but the datasource does not provide (at this level) the tools we need to interact with the authentication endpoint to receive an API Session token.  
 
 ![Infinity datasource authentication configuration](/img/Infinity_noAuth.png)
 
@@ -33,7 +33,7 @@ In the network section, we can provide the CA certificate for the controller, or
 
  ![Variable query URL Options configuration](/img/bearer_token_variable_url_options.png) 
 
-- In the Parsing options and Result fields, enter the below.  The Infinity datasource provides JSONPath functionality, which is used here to extract the API session token for use in the panel queries.
+- In the Parsing options and Result fields, enter the below.  The Infinity datasource provides JSONPath functionality, which is used here to extract the API Session token for use in the panel queries.
 
    ![Variable parsing options configuration](/img/bearer_token_variable_parsing.png)
 

@@ -31,11 +31,11 @@ end
 par Edge Control Plane
 	SDK 1 ->> Network Controller: 
 and 
-	SDK 2 ->>Network Controller: Edge Session (per service)
+	SDK 2 ->>Network Controller: Session (per service)
 and 
-	Edge Router 1 ->> Network Controller: Edge Session (per service)
+	Edge Router 1 ->> Network Controller: Session (per service)
 and 
-	Edge Router 2 ->> Network Controller: Edge Session (per service)
+	Edge Router 2 ->> Network Controller: Session (per service)
 end
 
 par Data Plane (TCP)
@@ -56,7 +56,7 @@ Edge Router 1 ->> Edge Router 2: Circuit
 ## Control Plane
 
 1. The API Session is the first and primary session between and endpoint and the OpenZiti network instance.  This session is created during attachment, after validating the certificates in both directions, and the endpoint name.  This makes the endpoint present on the network, and all endpoints and routers have API sessions to the Controller(s)
-2. The Edge Session is created with the API session authorization, and is specific to each service configured for the endpoint.  The edge session object holds information such as the service policies, parent API session, service ID, and other information the endpoint and network require to properly service each given service.
+2. The Session is created with the API Session authorization, and is specific to each service configured for the endpoint.  The Session object holds information such as the service policies, parent API Session, service ID, and other information the endpoint and network require to properly service each given service.
 3. Channels are formed between the endpoint and each Edge Router available and within the policies.  These channels are monitored for latency to select best path, and are the control connections for incoming connections for hosted services.
 4. Links connect Edge Routers logically.  Edge Routers can advertise a listener socket, which is distributed during client initialization to other Edge Routers.  All Edge Routers will attach to all others in a mesh, provided the policy dictates/allows it.  Each pair of routers will have one link per link type (TLS, WSS, etc.)  Links are a split connection, having both control plane and data plane messaging.
 

@@ -175,4 +175,4 @@ It does not remove entities are that re-usable between Identities:
 - [Edge Router Policies](/learn/core-concepts/security/authorization/policies/overview.mdx)
 
 Deleting an Identity immediately removes it and all current and future access it would have to a Ziti Network and its
-Services.
+Services.
@@ -101,8 +101,8 @@ in the policy. All Ziti policies work the same way.
  and service must have at least one on-line edge router in common in 
  order for a connection to be made. 
 
-When an identity is trying to establish a session to use or host a service the Ziti
-controller will verify that they access via service policy. Once the session is 
+When an identity is trying to establish an API Session to use or host a service, the Ziti
+controller will verify that they access via service policy. Once the API Session is 
 established, the controller will return a list of edge routers that the identity 
 can use to connect to that service. The list will be all edge routers which **both**
 the identity and service have access to. It is possible that an identity may have

@@ -36,7 +36,7 @@ the mesh.
 
 Controller APIs provide ways for clients (SDKs or otherwise) to interact with a network. The [Edge Management API](/reference/developer/api/02-edge-management-reference.mdx)
 is used for configuration and maintenance. The [Edge Client API](/reference/developer/api/01-edge-client-reference.mdx)
-is used to allow clients to authenticate, discover services, request service [Sessions](sessions.md#session),
+is used to allow clients to authenticate, discover services, request [Sessions](sessions.md#session),
 discover Edge Routers, and to perform basic self-maintenance.
 
 Access to the APIs requires [authentication](authentication/auth.md) which results in an [API Session](authentication/auth.md#api-sessions)
@@ -67,9 +67,9 @@ establish a `service` connection of either type the following is required:
 - a [Session](sessions.md#session) for the target service and intent (dial/bind)
 
 [Sessions](sessions.md#session) are issued by the controller's Edge Client API. A valid [Sessions](sessions.md#session) token 
-must be included with dial and bind requests. Edge Routers validate Session tokens continuously. If valid, the Edge 
+must be included with dial and bind requests. Edge Routers validate API Session tokens continuously. If valid, the Edge 
 Router will facilitate the connecting the client to a service or registering the client as a host.
 
 Should a [Session](sessions.md#session) become invalid at any point, any existing `service` connection that 
-was established using the invalidated session will be terminated. Attempts to re-establish connection with the 
-invalidated [Session](sessions.md#session) will be refused.
+was established using the invalidated Session will be terminated. Attempts to re-establish connection with the 
+invalidated [Session](sessions.md#session) will be refused.
@@ -1,5 +1,7 @@
 # Session Types
 
+Ziti has API Session and Session types.
+
 ## API Session
 
 API Sessions represent a client that is either partially or fully authenticated as a specific Ziti Identity.
@@ -193,11 +195,11 @@ A client may terminate its own API Session at any time by calling: `DELETE /edge
 
 ## Session
 
-Session represent access to a specific service for dialing or binding. They are scoped to the
+A Session represents access to a specific service for dialing or binding. They are scoped to the
 [API Session](#api-session) that was used to create them. They are requested from the
 controller by a client through the Edge Client API. The result of that request is a security token representing
 the Session and a list of Edge Routers that the client may use to dial or bind the target service through.
 
 Sessions are removed when the parent [API Session](authentication/auth.md#api-sessions) is removed,
-[policies](authorization/policies/overview.mdx) are changed to deny access, or when [Posture Checks](authorization/posture-checks.md) enter an
-invalid state for the target service.
+[policies](authorization/policies/overview.mdx) are changed to deny access, or when [Posture
+Checks](authorization/posture-checks.md) enter an invalid state for the target service.