Skip to content

Commit aacd796

Browse files
dovholuknfdovholuknf
committed
update the zping readme
1 parent 07f25b8 commit aacd796

File tree

1 file changed

+99
-94
lines changed

1 file changed

+99
-94
lines changed

‎example/zping/README.md‎

Lines changed: 99 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,128 @@
1-
# Intro:
1+
# zping
22

3-
What is zping? zping replaces the function of icmp ping tool in a ziti network.
3+
`zping` provides equivalent functionality for an OpenZiti overlay network as the similarly named underlay function
4+
`ping`. Being a zero trust overlay network, classic underlay tooling like `ping` won't function properly.
45

5-
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:
6+
`zping` provides end to end latency measurements between any two identities in an OpenZiti network. Like `icmp`, `zping`
7+
will provide the following metrics upon completion of the ping session:
68

7-
min, max and mean latency and standard deviation.
9+
* min
10+
* max
11+
* mean latency
12+
* standard deviation.
813

9-
zping uses the addressable terminator function of ziti to direct ping requests to specific identities.
14+
`zping` uses addressable terminators to direct ping requests to specific identities.
1015

11-
# Get the code :
16+
## Build the Example
17+
Refer to the [example README](../README.md) to build the SDK examples
1218

13-
Compile from source:
19+
## Setup and Configure the Example
1420

15-
Install golang for your platform follow instructions at https://golang.org
16-
and ensure you set you gopath properly for your platform. i.e
17-
Ubuntu linux:
18-
19-
```
20-
export GOPATH=$HOME/go
21-
```
22-
```
23-
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
24-
```
25-
26-
Linux:
27-
28-
Create a dir
29-
```
30-
mkdir zitiapps
31-
```
32-
```
33-
$ cd zitiapps
34-
```
35-
```
36-
$ git clone https://github.com/openziti/sdk-golang.git
37-
```
38-
```
39-
$ cd sdk-golang/example/zping
40-
```
41-
```
42-
$ go install zping
43-
```
44-
45-
# Setup the Network and the Ziti Service :
21+
This README will use the `ziti edge quickstart` command for its example. You'll need the `ziti` CLI on your path to run
22+
the commands shown. If you have an OpenZiti overlay network already, some commands will not be necessary. The
23+
commands all use bash and expect you're running on a version of *nix as `/tmp` is referenced. Adapt accordingly if
24+
you're using Windows. The example expects the binary to be put into the build directory as specified by the "Build
25+
the Example" section above.
4626

4727
![Diagram](network.png)
4828

49-
1. Create or use an existing ziti network with at least one edge router.
50-
51-
2. Create at least two ziti identities and give them a common identity role i.e. #ping
52-
53-
e.g. zitiendpoint1, zitiendpoint2
54-
55-
3. Create a simple sdk service named “ziti-ping” this is the default service zping looks for but can be
29+
1. Create or use an existing ziti network with at least one edge router. This can be accomplished easily by running
5630

57-
overridden with the -s command line flag.
31+
ziti edge quickstart
5832

59-
4. Create a bind policy with identityRoles set to [#ping] and serviceroles set to [@ziti-ping].
33+
after the quickstart runs, you'll have an ephemeral network usable for testing.
6034

61-
5. Create a dial service policy with identityRoles set to [#ping] and serviceroles set to [@ziti-ping].
35+
1. Create at least two ziti identities and give them a common identity role i.e. #zping
6236

63-
6. Ensure that you have created appropriate edge-router and service-edge-router policies allowing the identities access
64-
edge-router(s) and the edge-routers access to the service.
37+
ziti edge create identity client -o client.jwt -a "zping"
38+
ziti edge create identity server -o server.jwt -a "zping"
39+
ziti edge enroll client.jwt
40+
ziti edge enroll server.jwt
6541

66-
7. Create an AppWAN and enter @ziti-ping in the service attributes and #ping in the “Endpoint Attributes”
42+
1. Create a simple sdk service named "ziti-ping". This is the default service name `zping` looks for. You can
43+
override the service by using the `-s` flag.
6744

68-
8. Download the zpingendpoint1.jwt, zpingendpoint2.jwt
45+
ziti edge create service ziti-ping
6946

70-
9. Distribute the zping binary to the endpoint(s) you wish to run on
47+
1. Create a bind policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping].
7148

72-
10. Enroll the endpoints with the zping binary i.e.
73-
```
74-
$ zping enroll -j zitiendpoint1.jwt
75-
76-
INFO[0000] generating 4096 bit RSA key
49+
ziti edge create service-policy zping.bind Bind --identity-roles "#zping" --service-roles "@ziti-ping"
7750

78-
INFO[0002] enrolled successfully. identity file written to: zpingendpoint1.json
79-
```
80-
```
81-
$ zping enroll -j zpingendpoint2.jwt
51+
1. Create a dial service policy with identityRoles set to [#zping] and serviceroles set to [@ziti-ping].
52+
53+
ziti edge create service-policy zping.dial Dial --identity-roles "#zping" --service-roles "@ziti-ping"
8254

83-
INFO[0000] generating 4096 bit RSA key
55+
1. Ensure that you have created appropriate edge-router and service-edge-router policies allowing the identities access
56+
edge-router(s) and the edge-routers access to the service. Verify by running policy-advisor. Both identities
57+
should be able to dial **and** bind zping:
8458

85-
INFO[0002] enrolled successfully. identity file written to: zpingendpoint2.json
86-
```
87-
11. On each machine in run either in background or a separate window in server mode
88-
```
89-
$ zping server -c zpingendpoint1.json &
90-
[1] 4123
91-
INFO[0000] binding service ziti-ping
59+
$ ziti edge policy-advisor identities -q
60+
ERROR: Default Admin
61+
- Identity does not have access to any services. Adjust service policies.
62+
63+
OKAY : client (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N
9264

93-
zpingendpoint1 now serving
65+
OKAY : server (1) -> ziti-ping (1) Common Routers: (1/1) Dial: Y Bind: N
9466

95-
INFO[0000] connection to edge router using token 1de2f02e-62fe-44fb-bebb-e2d21a82d13f
67+
ERROR: quickstart-router
68+
- Identity does not have access to any services. Adjust service policies.
69+
70+
1. In one window run the server
9671
```
72+
build/zping server -c server.json
9773
```
98-
$ zping server -c zpingendpoint2.json &
99-
[1] 5176
100-
INFO[0000] binding service ziti-ping
101-
102-
zpingendpoint2 now serving
74+
example:
75+
```
76+
$ build/zping server -c server.json
77+
INFO[0000] binding service ziti-ping
78+
79+
0xc00040d660 now serving
80+
81+
INFO[0000] new service session session token=52e059d2-f166-4561-b5a4-b42056bcd787
82+
INFO[0041] new connection
83+
```
10384

104-
INFO[0000] connection to edge router using token d472f74c-97af-426a-a07f-7ecd907a2013
85+
1. In another window run the client
10586
```
106-
12. Send 5 zpings from zpingclient2 to zpingclient1
87+
build/zping client -c client.json -i server
10788
```
108-
$ zping client -c zitiendpoint2.json -i zitiendpoint1 -n 5
109-
INFO[0000] connection to edge router using token b78cab88-fa22-4d49-906f-ddf101b63b88
110-
INFO[0566] new connection
111-
112-
Sending 100 byte pings to zpingendpoint1:
113-
114-
100 bytes from zpingendpoint1: ziti_seq=1 time=76.558ms
115-
100 bytes from zpingendpoint1: ziti_seq=2 time=75.597ms
116-
100 bytes from zpingendpoint1: ziti_seq=3 time=76.209ms
117-
100 bytes from zpingendpoint1: ziti_seq=4 time=76.332ms
118-
100 bytes from zpingendpoint1: ziti_seq=5 time=76.849ms
119-
120-
--- zpingendpoint1 ping statistics ---
121-
5 packets transmitted and 5 packets received, 0.00% packet loss
122-
round-trip min/max/avg/stddev 75.597/76.849/76.309/0.417 ms
89+
90+
```
91+
$ build/zping client -c client.json -i server
92+
93+
Sending 100 byte pings to server:
94+
95+
100 bytes from server: ziti_seq=1 time=0.609ms
96+
100 bytes from server: ziti_seq=2 time=0.670ms
97+
100 bytes from server: ziti_seq=3 time=0.381ms
98+
100 bytes from server: ziti_seq=4 time=0.387ms
99+
100 bytes from server: ziti_seq=5 time=0.564ms
100+
100 bytes from server: ziti_seq=6 time=0.455ms
101+
100 bytes from server: ziti_seq=7 time=0.446ms
102+
100 bytes from server: ziti_seq=8 time=0.377ms
103+
100 bytes from server: ziti_seq=9 time=0.455ms
104+
100 bytes from server: ziti_seq=10 time=0.502ms
105+
100 bytes from server: ziti_seq=11 time=0.977ms
106+
100 bytes from server: ziti_seq=12 time=0.487ms
107+
^C
108+
--- server ping statistics ---
109+
12 packets transmitted and 12 packets received, 0.00% packet loss
110+
round-trip min/max/avg/stddev 0.377/0.977/0.526/0.162 ms
111+
```
112+
113+
1. Send 5 zpings from the client to the server using `-n 5`
114+
```
115+
$ build/zping client -c client.json -i server -n 5
116+
117+
Sending 100 byte pings to server:
118+
119+
100 bytes from server: ziti_seq=1 time=0.349ms
120+
100 bytes from server: ziti_seq=2 time=0.690ms
121+
100 bytes from server: ziti_seq=3 time=0.590ms
122+
100 bytes from server: ziti_seq=4 time=0.429ms
123+
100 bytes from server: ziti_seq=5 time=0.480ms
124+
125+
--- server ping statistics ---
126+
5 packets transmitted and 5 packets received, 0.00% packet loss
127+
round-trip min/max/avg/stddev 0.349/0.690/0.508/0.120 ms
123128
```

0 commit comments

Comments
 (0)