From aacd796a494a74c23fecd598dc7df88ea64b871b Mon Sep 17 00:00:00 2001 From: dovholuknf <46322585+dovholuknf@users.noreply.github.com> Date: Tue, 22 Oct 2024 15:57:27 -0400 Subject: [PATCH 1/3] update the zping readme --- example/zping/README.md | 193 +++++++++++++++++++++------------------- 1 file changed, 99 insertions(+), 94 deletions(-) diff --git a/example/zping/README.md b/example/zping/README.md index a8580e25..d5697c4b 100644 --- a/example/zping/README.md +++ b/example/zping/README.md @@ -1,123 +1,128 @@ -# Intro: +# zping -What is zping? zping replaces the function of icmp ping tool in a ziti network. +`zping` provides equivalent functionality for an OpenZiti overlay network as the similarly named underlay function +`ping`. Being a zero trust overlay network, classic underlay tooling like `ping` won't function properly. -It provides an end to end latency measurement between any two ziti identities in a ziti network and like icmp ping will provide the following metrics upon completion of the ping session: +`zping` provides end to end latency measurements between any two identities in an OpenZiti network. Like `icmp`, `zping` +will provide the following metrics upon completion of the ping session: -min, max and mean latency and standard deviation. +* min +* max +* mean latency +* standard deviation. -zping uses the addressable terminator function of ziti to direct ping requests to specific identities. +`zping` uses addressable terminators to direct ping requests to specific identities. -# Get the code : +## Build the Example +Refer to the [example README](../README.md) to build the SDK examples -Compile from source: +## Setup and Configure the Example -Install golang for your platform follow instructions at https://golang.org -and ensure you set you gopath properly for your platform. i.e -Ubuntu linux: - -``` -export GOPATH=$HOME/go -``` -``` -export PATH=$PATH:$GOROOT/bin:$GOPATH/bin -``` - -Linux: - - Create a dir -``` - mkdir zitiapps -``` -``` - $ cd zitiapps -``` -``` - $ git clone https://github.com/openziti/sdk-golang.git -``` -``` - $ cd sdk-golang/example/zping -``` -``` - $ go install zping -``` - -# Setup the Network and the Ziti Service : +This README will use the `ziti edge quickstart` command for its example. You'll need the `ziti` CLI on your path to run +the commands shown. If you have an OpenZiti overlay network already, some commands will not be necessary. The +commands all use bash and expect you're running on a version of *nix as `/tmp` is referenced. Adapt accordingly if +you're using Windows. The example expects the binary to be put into the build directory as specified by the "Build +the Example" section above. ![Diagram](network.png) -1. Create or use an existing ziti network with at least one edge router. - -2. Create at least two ziti identities and give them a common identity role i.e. #ping - - e.g. zitiendpoint1, zitiendpoint2 - -3. Create a simple sdk service named “ziti-ping” this is the default service zping looks for but can be +1. Create or use an existing ziti network with at least one edge router. This can be accomplished easily by running - overridden with the -s command line flag. + ziti edge quickstart -4. Create a bind policy with identityRoles set to [#ping] and serviceroles set to [@ziti-ping]. + after the quickstart runs, you'll have an ephemeral network usable for testing. -5. Create a dial service policy with identityRoles set to [#ping] and serviceroles set to [@ziti-ping]. +1. Create at least two ziti identities and give them a common identity role i.e. #zping -6. Ensure that you have created appropriate edge-router and service-edge-router policies allowing the identities access - edge-router(s) and the edge-routers access to the service. + ziti edge create identity client -o client.jwt -a "zping" + ziti edge create identity server -o server.jwt -a "zping" + ziti edge enroll client.jwt + ziti edge enroll server.jwt -7. Create an AppWAN and enter @ziti-ping in the service attributes and #ping in the “Endpoint Attributes” +1. Create a simple sdk service named "ziti-ping". This is the default service name `zping` looks for. You can + override the service by using the `-s` flag. -8. Download the zpingendpoint1.jwt, zpingendpoint2.jwt + ziti edge create service ziti-ping -9. Distribute the zping binary to the endpoint(s) you wish to run on +1. Create a bind policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping]. -10. Enroll the endpoints with the zping binary i.e. -``` - $ zping enroll -j zitiendpoint1.jwt - - INFO[0000] generating 4096 bit RSA key + ziti edge create service-policy zping.bind Bind --identity-roles "#zping" --service-roles "@ziti-ping" - INFO[0002] enrolled successfully. identity file written to: zpingendpoint1.json -``` -``` - $ zping enroll -j zpingendpoint2.jwt +1. Create a dial service policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping]. + + ziti edge create service-policy zping.dial Dial --identity-roles "#zping" --service-roles "@ziti-ping" - INFO[0000] generating 4096 bit RSA key +1. Ensure that you have created appropriate edge-router and service-edge-router policies allowing the identities access + edge-router(s) and the edge-routers access to the service. Verify by running policy-advisor. Both identities + should be able to dial **and** bind zping: - INFO[0002] enrolled successfully. identity file written to: zpingendpoint2.json -``` -11. On each machine in run either in background or a separate window in server mode -``` - $ zping server -c zpingendpoint1.json & - [1] 4123 - INFO[0000] binding service ziti-ping + $ ziti edge policy-advisor identities -q + ERROR: Default Admin + - Identity does not have access to any services. Adjust service policies. + + OKAY : client (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N - zpingendpoint1 now serving + OKAY : server (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N - INFO[0000] connection to edge router using token 1de2f02e-62fe-44fb-bebb-e2d21a82d13f + ERROR: quickstart-router + - Identity does not have access to any services. Adjust service policies. + +1. In one window run the server ``` + build/zping server -c server.json ``` - $ zping server -c zpingendpoint2.json & - [1] 5176 - INFO[0000] binding service ziti-ping - - zpingendpoint2 now serving + example: + ``` + $ build/zping server -c server.json + INFO[0000] binding service ziti-ping + + 0xc00040d660 now serving + + INFO[0000] new service session session token=52e059d2-f166-4561-b5a4-b42056bcd787 + INFO[0041] new connection + ``` - INFO[0000] connection to edge router using token d472f74c-97af-426a-a07f-7ecd907a2013 +1. In another window run the client ``` -12. Send 5 zpings from zpingclient2 to zpingclient1 + build/zping client -c client.json -i server ``` - $ zping client -c zitiendpoint2.json -i zitiendpoint1 -n 5 - INFO[0000] connection to edge router using token b78cab88-fa22-4d49-906f-ddf101b63b88 - INFO[0566] new connection - - Sending 100 byte pings to zpingendpoint1: - - 100 bytes from zpingendpoint1: ziti_seq=1 time=76.558ms - 100 bytes from zpingendpoint1: ziti_seq=2 time=75.597ms - 100 bytes from zpingendpoint1: ziti_seq=3 time=76.209ms - 100 bytes from zpingendpoint1: ziti_seq=4 time=76.332ms - 100 bytes from zpingendpoint1: ziti_seq=5 time=76.849ms - - --- zpingendpoint1 ping statistics --- - 5 packets transmitted and 5 packets received, 0.00% packet loss - round-trip min/max/avg/stddev 75.597/76.849/76.309/0.417 ms + + ``` + $ build/zping client -c client.json -i server + + Sending 100 byte pings to server: + + 100 bytes from server: ziti_seq=1 time=0.609ms + 100 bytes from server: ziti_seq=2 time=0.670ms + 100 bytes from server: ziti_seq=3 time=0.381ms + 100 bytes from server: ziti_seq=4 time=0.387ms + 100 bytes from server: ziti_seq=5 time=0.564ms + 100 bytes from server: ziti_seq=6 time=0.455ms + 100 bytes from server: ziti_seq=7 time=0.446ms + 100 bytes from server: ziti_seq=8 time=0.377ms + 100 bytes from server: ziti_seq=9 time=0.455ms + 100 bytes from server: ziti_seq=10 time=0.502ms + 100 bytes from server: ziti_seq=11 time=0.977ms + 100 bytes from server: ziti_seq=12 time=0.487ms + ^C + --- server ping statistics --- + 12 packets transmitted and 12 packets received, 0.00% packet loss + round-trip min/max/avg/stddev 0.377/0.977/0.526/0.162 ms + ``` + +1. Send 5 zpings from the client to the server using `-n 5` +``` +$ build/zping client -c client.json -i server -n 5 + +Sending 100 byte pings to server: + +100 bytes from server: ziti_seq=1 time=0.349ms +100 bytes from server: ziti_seq=2 time=0.690ms +100 bytes from server: ziti_seq=3 time=0.590ms +100 bytes from server: ziti_seq=4 time=0.429ms +100 bytes from server: ziti_seq=5 time=0.480ms + +--- server ping statistics --- +5 packets transmitted and 5 packets received, 0.00% packet loss +round-trip min/max/avg/stddev 0.349/0.690/0.508/0.120 ms ``` From 13386bf0ad60f05f2002105e505a20905ecef1ee Mon Sep 17 00:00:00 2001 From: dovholuknf <46322585+dovholuknf@users.noreply.github.com> Date: Tue, 22 Oct 2024 16:00:27 -0400 Subject: [PATCH 2/3] update the zping readme --- example/zping/README.md | 125 +++++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 59 deletions(-) diff --git a/example/zping/README.md b/example/zping/README.md index d5697c4b..71ea35d7 100644 --- a/example/zping/README.md +++ b/example/zping/README.md @@ -27,88 +27,95 @@ the Example" section above. ![Diagram](network.png) 1. Create or use an existing ziti network with at least one edge router. This can be accomplished easily by running - - ziti edge quickstart +``` +ziti edge quickstart +``` after the quickstart runs, you'll have an ephemeral network usable for testing. 1. Create at least two ziti identities and give them a common identity role i.e. #zping - - ziti edge create identity client -o client.jwt -a "zping" - ziti edge create identity server -o server.jwt -a "zping" - ziti edge enroll client.jwt - ziti edge enroll server.jwt +``` +ziti edge create identity client -o client.jwt -a "zping" +ziti edge create identity server -o server.jwt -a "zping" +ziti edge enroll client.jwt +ziti edge enroll server.jwt +``` 1. Create a simple sdk service named "ziti-ping". This is the default service name `zping` looks for. You can override the service by using the `-s` flag. - - ziti edge create service ziti-ping +``` +ziti edge create service ziti-ping +``` 1. Create a bind policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping]. - - ziti edge create service-policy zping.bind Bind --identity-roles "#zping" --service-roles "@ziti-ping" +``` +ziti edge create service-policy zping.bind Bind --identity-roles "#zping" --service-roles "@ziti-ping" +``` 1. Create a dial service policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping]. - - ziti edge create service-policy zping.dial Dial --identity-roles "#zping" --service-roles "@ziti-ping" +``` +ziti edge create service-policy zping.dial Dial --identity-roles "#zping" --service-roles "@ziti-ping" +``` 1. Ensure that you have created appropriate edge-router and service-edge-router policies allowing the identities access edge-router(s) and the edge-routers access to the service. Verify by running policy-advisor. Both identities should be able to dial **and** bind zping: - $ ziti edge policy-advisor identities -q - ERROR: Default Admin - - Identity does not have access to any services. Adjust service policies. - - OKAY : client (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N - - OKAY : server (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N - - ERROR: quickstart-router - - Identity does not have access to any services. Adjust service policies. +``` +$ ziti edge policy-advisor identities -q +ERROR: Default Admin + - Identity does not have access to any services. Adjust service policies. + +OKAY : client (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N + +OKAY : server (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N + +ERROR: quickstart-router + - Identity does not have access to any services. Adjust service policies. +``` 1. In one window run the server ``` - build/zping server -c server.json +build/zping server -c server.json +``` + +example: +``` +$ build/zping server -c server.json +INFO[0000] binding service ziti-ping + +0xc00040d660 now serving + +INFO[0000] new service session session token=52e059d2-f166-4561-b5a4-b42056bcd787 +INFO[0041] new connection ``` - example: - ``` - $ build/zping server -c server.json - INFO[0000] binding service ziti-ping - - 0xc00040d660 now serving - - INFO[0000] new service session session token=52e059d2-f166-4561-b5a4-b42056bcd787 - INFO[0041] new connection - ``` 1. In another window run the client ``` - build/zping client -c client.json -i server -``` - - ``` - $ build/zping client -c client.json -i server - - Sending 100 byte pings to server: - - 100 bytes from server: ziti_seq=1 time=0.609ms - 100 bytes from server: ziti_seq=2 time=0.670ms - 100 bytes from server: ziti_seq=3 time=0.381ms - 100 bytes from server: ziti_seq=4 time=0.387ms - 100 bytes from server: ziti_seq=5 time=0.564ms - 100 bytes from server: ziti_seq=6 time=0.455ms - 100 bytes from server: ziti_seq=7 time=0.446ms - 100 bytes from server: ziti_seq=8 time=0.377ms - 100 bytes from server: ziti_seq=9 time=0.455ms - 100 bytes from server: ziti_seq=10 time=0.502ms - 100 bytes from server: ziti_seq=11 time=0.977ms - 100 bytes from server: ziti_seq=12 time=0.487ms - ^C - --- server ping statistics --- - 12 packets transmitted and 12 packets received, 0.00% packet loss - round-trip min/max/avg/stddev 0.377/0.977/0.526/0.162 ms - ``` +build/zping client -c client.json -i server +``` +``` +$ build/zping client -c client.json -i server + +Sending 100 byte pings to server: + +100 bytes from server: ziti_seq=1 time=0.609ms +100 bytes from server: ziti_seq=2 time=0.670ms +100 bytes from server: ziti_seq=3 time=0.381ms +100 bytes from server: ziti_seq=4 time=0.387ms +100 bytes from server: ziti_seq=5 time=0.564ms +100 bytes from server: ziti_seq=6 time=0.455ms +100 bytes from server: ziti_seq=7 time=0.446ms +100 bytes from server: ziti_seq=8 time=0.377ms +100 bytes from server: ziti_seq=9 time=0.455ms +100 bytes from server: ziti_seq=10 time=0.502ms +100 bytes from server: ziti_seq=11 time=0.977ms +100 bytes from server: ziti_seq=12 time=0.487ms +^C +--- server ping statistics --- +12 packets transmitted and 12 packets received, 0.00% packet loss +round-trip min/max/avg/stddev 0.377/0.977/0.526/0.162 ms +``` 1. Send 5 zpings from the client to the server using `-n 5` ``` From 80fc872ba68715da479bbfb2f03c632987272c85 Mon Sep 17 00:00:00 2001 From: dovholuknf <46322585+dovholuknf@users.noreply.github.com> Date: Tue, 22 Oct 2024 16:03:20 -0400 Subject: [PATCH 3/3] update the zping readme --- example/zping/README.md | 170 ++++++++++++++++++++-------------------- 1 file changed, 86 insertions(+), 84 deletions(-) diff --git a/example/zping/README.md b/example/zping/README.md index 71ea35d7..5387fe9c 100644 --- a/example/zping/README.md +++ b/example/zping/README.md @@ -27,109 +27,111 @@ the Example" section above. ![Diagram](network.png) 1. Create or use an existing ziti network with at least one edge router. This can be accomplished easily by running -``` -ziti edge quickstart -``` + ``` + ziti edge quickstart + ``` after the quickstart runs, you'll have an ephemeral network usable for testing. 1. Create at least two ziti identities and give them a common identity role i.e. #zping -``` -ziti edge create identity client -o client.jwt -a "zping" -ziti edge create identity server -o server.jwt -a "zping" -ziti edge enroll client.jwt -ziti edge enroll server.jwt -``` + ``` + ziti edge create identity client -o client.jwt -a "zping" + ziti edge create identity server -o server.jwt -a "zping" + ziti edge enroll client.jwt + ziti edge enroll server.jwt + ``` 1. Create a simple sdk service named "ziti-ping". This is the default service name `zping` looks for. You can override the service by using the `-s` flag. -``` -ziti edge create service ziti-ping -``` + ``` + ziti edge create service ziti-ping + ``` 1. Create a bind policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping]. -``` -ziti edge create service-policy zping.bind Bind --identity-roles "#zping" --service-roles "@ziti-ping" -``` + ``` + ziti edge create service-policy zping.bind Bind --identity-roles "#zping" --service-roles "@ziti-ping" + ``` 1. Create a dial service policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping]. -``` -ziti edge create service-policy zping.dial Dial --identity-roles "#zping" --service-roles "@ziti-ping" -``` + ``` + ziti edge create service-policy zping.dial Dial --identity-roles "#zping" --service-roles "@ziti-ping" + ``` 1. Ensure that you have created appropriate edge-router and service-edge-router policies allowing the identities access edge-router(s) and the edge-routers access to the service. Verify by running policy-advisor. Both identities should be able to dial **and** bind zping: -``` -$ ziti edge policy-advisor identities -q -ERROR: Default Admin - - Identity does not have access to any services. Adjust service policies. - -OKAY : client (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N - -OKAY : server (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N - -ERROR: quickstart-router - - Identity does not have access to any services. Adjust service policies. -``` + ``` + $ ziti edge policy-advisor identities -q + ERROR: Default Admin + - Identity does not have access to any services. Adjust service policies. + + OKAY : client (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N + + OKAY : server (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N + + ERROR: quickstart-router + - Identity does not have access to any services. Adjust service policies. + ``` 1. In one window run the server -``` -build/zping server -c server.json -``` - -example: -``` -$ build/zping server -c server.json -INFO[0000] binding service ziti-ping - -0xc00040d660 now serving - -INFO[0000] new service session session token=52e059d2-f166-4561-b5a4-b42056bcd787 -INFO[0041] new connection -``` + ``` + build/zping server -c server.json + ``` + + example: + ``` + $ build/zping server -c server.json + INFO[0000] binding service ziti-ping + + 0xc00040d660 now serving + + INFO[0000] new service session session token=52e059d2-f166-4561-b5a4-b42056bcd787 + INFO[0041] new connection + ``` 1. In another window run the client -``` -build/zping client -c client.json -i server -``` -``` -$ build/zping client -c client.json -i server - -Sending 100 byte pings to server: - -100 bytes from server: ziti_seq=1 time=0.609ms -100 bytes from server: ziti_seq=2 time=0.670ms -100 bytes from server: ziti_seq=3 time=0.381ms -100 bytes from server: ziti_seq=4 time=0.387ms -100 bytes from server: ziti_seq=5 time=0.564ms -100 bytes from server: ziti_seq=6 time=0.455ms -100 bytes from server: ziti_seq=7 time=0.446ms -100 bytes from server: ziti_seq=8 time=0.377ms -100 bytes from server: ziti_seq=9 time=0.455ms -100 bytes from server: ziti_seq=10 time=0.502ms -100 bytes from server: ziti_seq=11 time=0.977ms -100 bytes from server: ziti_seq=12 time=0.487ms -^C ---- server ping statistics --- -12 packets transmitted and 12 packets received, 0.00% packet loss -round-trip min/max/avg/stddev 0.377/0.977/0.526/0.162 ms -``` + ``` + build/zping client -c client.json -i server + ``` + + example: + ``` + $ build/zping client -c client.json -i server + + Sending 100 byte pings to server: + + 100 bytes from server: ziti_seq=1 time=0.609ms + 100 bytes from server: ziti_seq=2 time=0.670ms + 100 bytes from server: ziti_seq=3 time=0.381ms + 100 bytes from server: ziti_seq=4 time=0.387ms + 100 bytes from server: ziti_seq=5 time=0.564ms + 100 bytes from server: ziti_seq=6 time=0.455ms + 100 bytes from server: ziti_seq=7 time=0.446ms + 100 bytes from server: ziti_seq=8 time=0.377ms + 100 bytes from server: ziti_seq=9 time=0.455ms + 100 bytes from server: ziti_seq=10 time=0.502ms + 100 bytes from server: ziti_seq=11 time=0.977ms + 100 bytes from server: ziti_seq=12 time=0.487ms + ^C + --- server ping statistics --- + 12 packets transmitted and 12 packets received, 0.00% packet loss + round-trip min/max/avg/stddev 0.377/0.977/0.526/0.162 ms + ``` 1. Send 5 zpings from the client to the server using `-n 5` -``` -$ build/zping client -c client.json -i server -n 5 - -Sending 100 byte pings to server: - -100 bytes from server: ziti_seq=1 time=0.349ms -100 bytes from server: ziti_seq=2 time=0.690ms -100 bytes from server: ziti_seq=3 time=0.590ms -100 bytes from server: ziti_seq=4 time=0.429ms -100 bytes from server: ziti_seq=5 time=0.480ms - ---- server ping statistics --- -5 packets transmitted and 5 packets received, 0.00% packet loss -round-trip min/max/avg/stddev 0.349/0.690/0.508/0.120 ms -``` + ``` + $ build/zping client -c client.json -i server -n 5 + + Sending 100 byte pings to server: + + 100 bytes from server: ziti_seq=1 time=0.349ms + 100 bytes from server: ziti_seq=2 time=0.690ms + 100 bytes from server: ziti_seq=3 time=0.590ms + 100 bytes from server: ziti_seq=4 time=0.429ms + 100 bytes from server: ziti_seq=5 time=0.480ms + + --- server ping statistics --- + 5 packets transmitted and 5 packets received, 0.00% packet loss + round-trip min/max/avg/stddev 0.349/0.690/0.508/0.120 ms + ```