openziti / ziti-doc Goto Github PK
View Code? Open in Web Editor NEWDocumentation describing the usage of the Ziti platform.
Home Page: https://openziti.io
License: Apache License 2.0
Documentation describing the usage of the Ziti platform.
Home Page: https://openziti.io
License: Apache License 2.0
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.
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
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.
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)
The Azure quickstart for ZEDE is mostly place holders. Flesh it out and finish it off
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
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
add/incorporate any REST related docs
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:
had a user mention submariner.io. consider reviewing the solution and producing a comparison guide
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
should cover things like e2ee, fabric, router selections etc etc
Search repo for "master" reveals many articles' metadata is pointing at "master", presumably after moving to "main".
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"
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.
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
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
had a user mention skupper.io. consider doing a "how ziti is different" for skupper.io
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
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.
Not the SaaS platform, but the open-source Teleport tunneler CLI and service/daemon.
API Docs does not list javadoc. Find out if the JRE sdk has any doc and publish it if so
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
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
Just a note that I have created a PR for some documentation updates
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:"
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
Some notes that we could fold-in to https://openziti.github.io/ziti/clients/tunneler.html#linux
ziti-edge-tunnel
ziti-tunnel
but has a superior approach to built-in DNSziti-tunnel
run
mode uses tun
device IP routes to intercept service traffic and answer DNS via resolvectl
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
proxy
and host
in addition to tproxy
(IPtables intercepts)netfoundry/ziti-tunnel
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
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?
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
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:
Missing have
in sentence on Service Configuration overview.
Different applications can their own configuration for the same service
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.
Should have a doc page explaining various types of routers with the following info
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.
revisit the samples and ensure they are complete and up to date with the latest ziti releases
docfx_project/ziti/clients/linux.md
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
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.
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
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.
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.