openziti / ziti-doc Goto Github PK

Right now the information around hosted services is more sparse and more difficult to understand than "non-hosted" services. Update the doc so that it's more clear as to the differences and what each type of service is

add/incorporate any REST related docs

There are two "Notes" in the following doc page that are not rendering as graphical notes in the deployed doc.

Please deploy locally to confirm the fix is working, using a generic markdown renderer won't render them properly, they will likely appear fixed when they are not actually fixed.

Source file:
docfx_project/ziti/quickstarts/zac/installation.md

Rendered output (look for > [!Note] > followed by some text and <):
https://openziti.github.io/ziti/quickstarts/zac/installation.html#using-docker-compose

It would be useful to show people how to use the C SDK to interact with a PKCS11 implementation such as SoftHSM

Ensure the quickstart/example outlines how to do this from a tunnel as well as from the C SDK

Chrome on MacOS is a particular pain for the ZAC. Until ACME can be implemented by ZAC it'd be good to point people as to how to create legit certs using lets encrypt

Search repo for "master" reveals many articles' metadata is pointing at "master", presumably after moving to "main".

lots of times we get asked questions about service mesh and how it's the same/different than ziti. let's produce some kind of wiki, doc, article around what ideas overlap, what ideas are different and how it all pertains to ziti

Missing have in sentence on Service Configuration overview.

Different applications can their own configuration for the same service

Right now there's no text telling you how to get to the web ui. There should be some information informing the user that there's a web server running, what port it runs on (if not the default https port) and how to access the UI

The edge part of a ziti overlay network is largely glossed over - mostly for a good reason. initial learners have a lot to digest as is. However - once someone starts looking into 'terminators' the nuance begins to be more important.

update the overview with some broad words about the edge and update more details about what 'the edge' means and how it's different (but incredibly similar to) 'the fabric'. Possibly include definition of terminators in the work. here's some words that might help frame terminators.

terminators are metadata stored in the controller which are used during path selection. these terminators represent all the possible routers where traffic can leave the openziti fabric. leaving the fabric does not necessarily mean leaving the overall, overlay network. If the final destination of the traffic is an edge component, the traffic continues on the ziti edge overlay network to the actual destination of the traffic.

docfx_project/ziti/clients/linux.md

with the release of 0.25.5 the ziti edge list... commands display in a "prettified" view that resembles a table. The quickstart docs (specifically for docker-compose but likely others as well) still reference the older style output and need to be updated to the new output.

Examples should be updated for both ziti edge list edge-routers and ziti edge list identities

OLD:

ziti@724087d30014:/openziti$ ziti edge list edge-routers
id: BZ.Y7vMdAI    name: ziti-edge-router    isOnline: true    role attributes: {}
id: NELWwjMd8    name: ziti-private-blue    isOnline: true    role attributes: {}
id: l9-W7jMf8    name: ziti-fabric-router-br    isOnline: true    role attributes: {}
id: rqZW7vMdA    name: ziti-edge-router-wss    isOnline: true    role attributes: {}
id: xmiYwvMf8    name: ziti-private-red    isOnline: true    role attributes: {}

NEW (despite the image, the command ziti edge list edge-routers should remain the same in the sample output):

Disclaimer: Fair warning that the formatting might be tricky converting the console output to look the same in markdown format. I'm not positive it will be cumbersome but it's worth noting as this is tagged "good first issue"

Right now there is not a 'white paper style' doc to share for those more technically inclined people. It'd be helpful to have a white paper style doc to share which covers the values of zero trust and the awesome abilities ziti can provide by going app embedded

Should have a doc page explaining various types of routers with the following info

• What they do
• How they work
• Differences between the various types (edge, fabric, private edge, wss edge, etc.)

Should also add information detailing the configuration file and what the different sections are for and how each affects the functionality of the router.

** Added the "help wanted" tag in case anyone wants to contribute more on what they'd like to see in the router doc.

The "Create a service" section explaining how to do so in CLI uses incorrect syntax (I assume old)

Source: docfx_project/ziti/services/create-service-cli.md
Url: https://openziti.github.io/ziti/services/overview.html?tabs=create-service-cli

One example is:
ziti edge controller create service ssh

Whereas the actual syntax should be:
ziti edge create service ssh

API Docs does not list javadoc. Find out if the JRE sdk has any doc and publish it if so

in the glossary add:

some getting started ideas:

I think of a link as point to point (between routers) and a circuit as an end-to-end path across the fabric (I.e., multiple fabric links)

Make a page exclusively for the sdk's. Ideally one which highlights functionality and which sdk's support which, lineage therein etc.

ziti-enroller is on its way out. ziti-tunnel now has the enroll capability. find any enrollment locations and make the doc better wrt how enrolling works on the many os's, refer to ziti-tunnel if one wants to enroll it manually etc

had a user mention skupper.io. consider doing a "how ziti is different" for skupper.io

There is a typo with the word "located", it's showing "locoated" in the Dark Services and Routers section

https://openziti.github.io/ziti/overview.html#dark-services-and-routers

The PKI troubleshooting only was edge focused at first when we only had ZEDE. with the open core coming out - add troubleshooting for routers/ziti-fabric

There is a section that explains you may run into an issue if you run quickstart more than one. It directs the user to unset Ziti variables and run it again. However, this should be updated as a feature was added to prompt the user for input and then continue as directed rather than requiring them to manually unset the variables.

The warning appears with this text
"If you run this command twice in the same shell you'll see a message warning you that you've already run the command. It will look like this:"

After ZAC is installed, during the login steps, the first step mentions "At this point you should be able to navigate to both" but since it's one big paragraph of text it's not clear what is meant by "both" so maybe make these sub-bullets as I believe it's referring to both the external URL and the url of the docker hostname.

It also appears there is a "NOTE" that should be showing differently in HTML based on docfx documentation but is just showing some brackets and a bunch of greater-than symbols. (this "> [!NOTE] >" plus all subsequent ">" symbols)

At this point you should be able to navigate to both: https://${ZITI_EDGE_CONTROLLER_HOSTNAME}:8443and see the ZAC login screen. (The TLS warnings your browser will show you are normal - it's because these steps use a self-signed certificate generated in the install process) > [!NOTE] > If you are using docker-compose to start your network, when you access ZAC for the first time you will need to > specify the url of the controller. Since everything is running in docker compose this url is relative to the > internal docker compose network that is declared in the compose file. You would enter > https://ziti-edge-controller:1280 as the controller's URL

I'm not sure if this is a Mac specific thing but when I had first run the command to start up the ZAC server, I was presented with a failure that explained the express package was required.

After a simple npm install express and retrying to start ZAC everything worked.

We should verify if this is a widespread issue or just a local issue in this one case. If it's a widespread issue then update the doc to explain that this package is needed. Or maybe just add a blurb that it's needed and might not be installed and show how to install it.

Right now after running the expressInstall, when you are done you're given a startZitiController and other helpful functions but if you make a new shell, the functions aren't sourced. Discuss this in the doc.

Consider moving these sorts of functions to the env file that gets sourced/generated

https://openziti.github.io/ziti/quickstarts/network/common-quickstart.html?q=password#tabpanel_Jgj2pEEE-E_change-pwd-cli
should show you how to change the password via cli - but it's not rendering properly

ziti edge update authenticator updb -s
Enter your current password:
Enter your new password:

I am looking for help configuring ziti-router i.e. example directives for config.yml. Specifically, I'm trying to find out whether a property needs to be set in config.yml to enabled the router's built-in tunneler features for hosting a Ziti service.

I found a v2 example in https://openziti.github.io/ziti/manage/edge-router.html#configuration, but it doesn't have a comment or placeholder for any tunneler-related properties. Does that mean the built-in tunneler stuff is only managed through the controller's management API, and no config properties are needed?

The "Local - No Docker" quickstart explains how there are two commands for starting up your controller startZitiController and router startExpressEdgeRouter but doesn't mention that there are also simple commands already sourced that will stop the processes. Those would be stopZitiController and stopAllEdgeRouters

It would be nice to add a section explaining that these commands are already provided by the express install, no need to find and kill the processes manually.

Steps:

Follow quickstart guide: https://openziti.github.io/ziti/quickstarts/network/local-with-docker.html
On the step of running the docker run command it attempts to write a file, then read a second file. Neither files exist despite logged as created.

jq is required for expressInstall and the install does check for this but it would be nice to enhance the part of the "Local - No Docker" install where it says jq is required so the user can install jq before watching quickstart fail because the prereq is not met.

Possibly explain how to check if it is (maybe a which jq orjq --version. Then also have a link to the jq install page in case it isn't installed.

There are certain steps one must go through when making an sdk. let's produce some guidance on what the best way is to adopt open ziti for times where there is no SDK for ${my.favorite.language}

Things to consider:

• how to use ziti
• main features
• how do i maintain feature parity
• how do i contribute the sdk back (and will you adopt it, maintain it etc)
• other considerations?

Just a note that I have created a PR for some documentation updates

There is an extra character in a sample command that will cause the command to not work if it is copied along with the command.

In Quickstart Local there is a command referenced as follows
`"${ZITI_BIN_DIR-}/ziti" edge list edge-routers

Just need that extra accent removed from the beginning of the command. I know, it probably took longer to create this issue but it's a good way for someone to get their name in on a code fix on an open source project.

• illustrate how to setup the service or refer to doc for creating the service
• include screen shots of the output

https://openziti.github.io/ziti/identities/overview.html?tabs=tabid-new-ca-ui%2Ctabid-new-identity-ui

states: One time tokens are delivered from the Ziti Controller as a jwt and the token expires 24 hours after the identity is created.

This is not correct. At this time it's set to 5 minutes and changing to 3 hours soon. It should have words to the effect that it's configurable by the controller.

Right now when people show up to openziti.github.io - there's a nice landing page but not a lot of info about what a zero trust overlay network really is. maybe put a link on it and let people learn about it

The Azure quickstart for ZEDE is mostly place holders. Flesh it out and finish it off

Not the SaaS platform, but the open-source Teleport tunneler CLI and service/daemon.

https://openziti.github.io/ziti/clients/linux.html hasn't been updated for a long time. re-read it and fix anything missing. SPECIFICALLY rework the page (if nothing else) to use/mention ziti-edge-tunnel vs ziti-tunnel

had a user mention submariner.io. consider reviewing the solution and producing a comparison guide

revisit the samples and ensure they are complete and up to date with the latest ziti releases

should cover things like e2ee, fabric, router selections etc etc

Some notes that we could fold-in to https://openziti.github.io/ziti/clients/tunneler.html#linux

ziti-edge-tunnel

• C-SDK tunneler aka "tunneler SDK"
• a bit more advanced and less user-friendly than ziti-tunnel but has a superior approach to built-in DNS
• is more performant than ziti-tunnel
• run mode uses tun device IP routes to intercept service traffic and answer DNS via resolvectl
• Future development will probably land first in the tunneler SDK
• Experimental Docker container exists: netfoundry/ziti-edge-tunnel
• systemd install

# transparent install procedure for ziti-edge-tunnel

# where to install the executable binary
❯ ZITI_EDGE_TUNNEL_BIN_DIR=/usr/local/bin

# where to look at startup for enrolled identity JSON config files
❯ ZITI_EDGE_TUNNEL_ID_DIR=~/.ziti-edge-tunnel

# create the identity directory
❯ mkdir -pvm0700 $ZITI_EDGE_TUNNEL_ID_DIR

# create a systemd service
❯ cat <<ZITI_SERVICE | sudo tee /usr/lib/systemd/system/ziti-edge-tunnel.service                
[Unit]
Description=Ziti Edge Tunnel
After=network.target
ConditionDirectoryNotEmpty=$ZITI_EDGE_TUNNEL_ID_DIR

[Service]
User=root
ExecStart=${ZITI_EDGE_TUNNEL_BIN_DIR}/ziti-edge-tunnel run --verbose 4 --identity-dir $ZITI_EDGE_TUNNEL_ID_DIR
Restart=always
RestartSec=2
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
ZITI_SERVICE

# load the new systemd config
❯ sudo systemctl daemon-reload

# download some version of ziti-edge-tunnel
❯ curl -sSLf https://raw.githubusercontent.com/openziti/ziti-tunnel-sdk-c/main/docker/fetch-github-releases.sh | ZITI_VERSION=0.17.7 bash -x /dev/stdin ziti-edge-tunnel

# install in a directory that is in the executable search PATH
❯ sudo mv -v ./ziti-edge-tunnel ${ZITI_EDGE_TUNNEL_BIN_DIR}/

# verify the installed version
❯ sudo ziti-edge-tunnel version

# use a downloaded enrollment token to generate an identity
❯ sudo ziti-edge-tunnel enroll --jwt ~/Downloads/linuxTunneler1.jwt --identity ${ZITI_EDGE_TUNNEL_ID_DIR}/linuxTunneler1.json

# start the daemon
❯ sudo systemctl start ziti-edge-tunnel.service

# view the logs
❯ sudo journalctl -lfu ziti-edge-tunnel.service

ziti-tunnel

• the first Linux tunneler
• Go-SDK tunneler
• has useful modes proxy and host in addition to tproxy (IPtables intercepts)
• works fairly well today in Docker: netfoundry/ziti-tunnel

The first sentence in the page describing services seems to be messed up in a few ways.

The primaryategy assumes that one ter function of Ziti is providing access to "services". A service encapsulates the definition of any resource that could be accessed by a client on a traditional network.