Project

General

Profile

Statistics
| Branch: | Revision:

gdp-router-click / README.md @ master

History | View | Annotate | Download (7.84 KB)

1 ab0dd3c7 Eric Allman
2 d533b917 Rick Pratt
# GDP v2 Network Router
3 ab0dd3c7 Eric Allman
4 bf8eea1e Rick Pratt
## Brief Overview
5 ab0dd3c7 Eric Allman
6 d533b917 Rick Pratt
The GDP project has produced several implementations of the GDP Router
7
over many years of design evolution. The two most recent
8
implementations reside in this gdp_router_click repository, however
9 d1381a19 Eric Allman
the most recent (i.e. current) GDP v2 Network gdp-router-click binary
10 5568a011 Eric Allman
is built from just two source files (`src/gdp_v4_router.cc` and
11
`src/gdp_v4_router.hh`) which are integrated and built into the latest
12 d533b917 Rick Pratt
Click modular router automatically under the control of make.
13
14
The latest GDP Router supports standard GDP clients connecting over
15
TCP sessions, and router peering over dTLS sessions, with any network
16
topology one might wish to configure.  The network itself also
17
provides reliable PDU delivery services across the datagram-based
18
portion of any network topology.
19
20 d1381a19 Eric Allman
The gdp-router-click binary will, if launched with no configuration,
21 d533b917 Rick Pratt
peer directly with the UC Berkeley GDP v2 Network by default and use
22 d1381a19 Eric Allman
the UC Berkeley RIB service. The gdp-router-click binary may also be
23 d533b917 Rick Pratt
configured to launch in "single router" mode for isolated GDP
24
experimentation, though one must also launch a few other GDP services
25 d1381a19 Eric Allman
(currently HONGDB, logCreationService, and gdplogd) in order to make
26 d533b917 Rick Pratt
use of gdp-create, gdp-writer, or gdp-reader in an isolated
27
environment. In addition to the "single router" mode's itemization of
28
required components, a standard (not "single router" mode) GDP v2
29
Network deployment also requires a RIB service instance per GDP Trust
30
Domain. The various required services (and their documentation) are
31
made available through the gdp repository.
32
33
The easiest way to begin experimenting with a GDP router binary and
34
local GDP client applications is to let your router instance directly
35
peer with the UC Berkeley GDP v2 Network, which operates all of the
36
required services (RIB service, HONGDB, logCreationService, and
37
multiple gdplogd instances). Please contact the GDP team, if questions
38
arise.
39
40
## Router Build:
41
42 5568a011 Eric Allman
**Prerequisites:**  To build, you will need to have `git` installed.
43
If you are compiling on Ubuntu 18.04 you also need to have
44
`openssl1.0` installed (the default is `openssl1.1`, which does
45
not compile.
46
47
```
48
apt install git libssl1.0-dev
49
```
50
51
The router build will automatically `git clone` dependent repositories
52
(GDP and Click), which will be created within the build
53 d533b917 Rick Pratt
subdirectory. Therefore, a successful first build requires Internet
54
access, while rebuilds may occur offline. To launch the build of
55 d1381a19 Eric Allman
gdp-router-click:
56 ab0dd3c7 Eric Allman
57 d533b917 Rick Pratt
```
58 d1381a19 Eric Allman
$ make gdp-router-click
59 d533b917 Rick Pratt
```
60
61
A simple test can be conducted on the resulting binary by launching
62
the router in single router mode:
63
64
```
65 d1381a19 Eric Allman
$ ./gdp-router-click -e "GDPR::GDPv4Router(SINGLE_ROUTER true, DEBUG 1); GDPR;"
66 d533b917 Rick Pratt
```
67
68
Output will be similar to the following:
69
70
```
71 d1381a19 Eric Allman
    Starting gdp-router-click (v2 master 67d687d61a212ee692d6d600d81c776ff9f070bc)
72 d533b917 Rick Pratt
    	as gdpr-01.8009
73
    	aka HLwmHH7Pw9mAenUHnCI0mWlP-l5O4nqmlXpjoU3bUH0
74
    	with debug 0
75
    	listening on any udp 8009 and tcp 8009
76
    	single router mode (no directory service)
77
    (4)TL new tcp listen
78
```
79
80
Use Control-C to interrupt the above test.
81
82
## Router First-Time Installation:
83 bf8eea1e Rick Pratt
84 d533b917 Rick Pratt
[Tested on Ubuntu 16.04]
85 bf8eea1e Rick Pratt
86 d533b917 Rick Pratt
To install systemd and related operational files, along with a default
87
configuration which will run the router instalation in "single router"
88
mode, run (presuming sudo privileges are configured): 
89 bf8eea1e Rick Pratt
90 d533b917 Rick Pratt
```
91 d1381a19 Eric Allman
$ make install-gdp-router-click
92 d533b917 Rick Pratt
```
93
94
When installing routers on various hosts in a full GDP v2 Network
95
Trust Domain installation, each router instance can be installed as
96
shown above, but it will also be necessary to edit each instance's
97 d1381a19 Eric Allman
configuration (typically found in /etc/gdp/gdp-router-click.conf) and
98
then execute "systemctl restart gdp-router-click" to put the desired
99 d533b917 Rick Pratt
router configuration into effect.
100
101
## Router Rebuild Installation:
102
103
```
104 d1381a19 Eric Allman
$ [sudo] make reinstall
105 d533b917 Rick Pratt
```
106
107
## Router Operation:
108
109
Have systemd to start the router (in "single router" mode if
110
first-time install):
111
112
```
113 d1381a19 Eric Allman
$ systemctl start gdp-router-click
114 d533b917 Rick Pratt
```
115
116
Check the router status:
117
118
```
119 d1381a19 Eric Allman
$ systemctl status gdp-router-click
120 d533b917 Rick Pratt
```
121
122
To monitor the router log:
123
124
```
125 d1381a19 Eric Allman
$ tail -F /var/log/gdp/gdp-router-click.log
126 d533b917 Rick Pratt
```
127
128
To stop the router:
129
130
```
131 d1381a19 Eric Allman
$ systemctl stop gdp-router-click
132 d533b917 Rick Pratt
```
133
134
## Router Configuration:
135 bf8eea1e Rick Pratt
136 e6920c35 Rick Pratt
Click can read a file or accept configuration as an expression
137 d1381a19 Eric Allman
parameter when launched. Run "gdp-router-click --help" for further
138 d533b917 Rick Pratt
details.
139 e6920c35 Rick Pratt
140 d1381a19 Eric Allman
A valid gdp-router-click configuration requires the following
141 d533b917 Rick Pratt
structure, though any name can be used in place of both instances of
142
the "GDPR" string:
143 e6920c35 Rick Pratt
144
```
145
	GDPR::GDPv4Router(...); GDPR;
146
```
147
	
148
The ellipsis, shown above, must be replaced with a valid configuration
149
constructed from zero or more ***Named Parameters*** followed by zero
150
or more ***Routing Peers***, in comma-separated list format. An empty
151
configuration ***is*** a valid configuration; it will draw upon
152
internal defaults to implicitly connect the router to a randomly
153 a42aa527 Rick Pratt
selected GDP core router and the GDP RIB service at UC Berkeley. More
154
complex configurations are built by appending named parameters and
155
routing peers into a comma-separated list, though non-zero routing
156
peer lists must explicitly include at least one GDP core router peer.
157 e6920c35 Rick Pratt
158
### Named Parameters
159
160
```
161
	TCP_PORT <port>        Listen for clients on non-default tcp port
162
	UDP_PORT <port>        Listen for routing peers on non-default udp port
163
    IP <address>           Listen for routing peers on one address, not any/all
164
    GDPNAME <gdpname>      Override gdpname generation with explicit gdpname
165
	HOSTNAME <hostname>    Override hostname discovery in gdpname generation [1]
166 a42aa527 Rick Pratt
	SINGLE_ROUTER true     Route clients locally (no routing peers or RIB)
167 5254ed23 Rick Pratt
	RIBNAME <hostname>     Override GDP RIB service default hostname
168
	IP_RIB <address>       Override GDP RIB service address, ignores RIBNAME
169
	UDP_PORT_RIB <port>    Override GDP RIB service default port
170 3aa9a35e Rick Pratt
	ADVERT_TIMER <us>	   Override advertisement timer interval [2]
171 e6920c35 Rick Pratt
	DEBUG <level>          Not intended for normal operation, increases cpu load
172
173
[1] If GDPNAME has been configured, HOSTNAME is invalid configuration input.
174 3aa9a35e Rick Pratt
[2] The default value is 128000 microseconds, but site specific tuning needed.
175 e6920c35 Rick Pratt
```
176
177
### Routing Peers
178
179
```
180
	<peer_hostname_or_ip_address> [, <peer_non-default_port> ]
181
```
182
183
## Configuration Examples:
184
185
```
186 a42aa527 Rick Pratt
	// route clients locally only (no routing peers or GDP RIB)
187 e6920c35 Rick Pratt
	R::GDPv4Router(SINGLE_ROUTER true); R;
188
189 a42aa527 Rick Pratt
	// route clients locally only, using a local GDP RIB host (no routing peers)
190 5254ed23 Rick Pratt
	R::GDPv4Router(RIBNAME gdp-ribd.domain); R;
191 a42aa527 Rick Pratt
192
	// route clients locally only, using a local GDP RIB IP (no routing peers)
193 5254ed23 Rick Pratt
	R::GDPv4Router(IP_RIB 10.1.1.1); R;
194 a42aa527 Rick Pratt
195 e6920c35 Rick Pratt
	// connect to the GDP via defaults, implicitly connects to a GDP core router
196
	R::GDPv4Router(); R;
197
	
198
	// connect to the GDP via gdp-01, and also connect to r1 in local domain
199
	R::GDPv4Router(gdp-01.eecs.berkeley.edu, r1.domain); R;
200
201
	// connect to the GDP via gdp-01, and also connect to r1 on port 8010
202
	R::GDPv4Router(gdp-01.eecs.berkeley.edu, r1.domain, 8010); R;
203
204
	// connect to the GDP via gdp-03, and also connect to r1 on port 8010 and r2
205
	R::GDPv4Router(gdp-03.eecs.berkeley.edu, r1.domain, 8010, r2.domain); R;
206
207
	// connect to the GDP via gdp-03, and connect to r1's IP on port 8010 and r2
208
	R::GDPv4Router(gdp-03.eecs.berkeley.edu, 10.1.1.1, 8010, r2.domain); R;
209
```
210
211
## Docker Configuration Examples:
212
213
```
214
	// equivalent to first example in prior section, uses container name/bridge
215
    docker run -e CONFIG="SINGLE_ROUTER true" <docker_image>
216
217
	// equivalent to second example in prior section, uses container name/bridge
218
    docker run <docker_image>
219
220
	// equivalent to third example in prior section, uses host's name/network
221
    docker run --network='host' <docker_image>
222
223
	// equivalent to fourth example in prior section, uses host's name/network
224
    docker run --network='host' \
225
		-e CONFIG="gdp-01.eecs.berkeley.edu, r1.domain, 8010" <docker_image>
226
```
227 bf8eea1e Rick Pratt
228 d533b917 Rick Pratt
For additional information, see:
229 ab0dd3c7 Eric Allman
230 d533b917 Rick Pratt
[https://gdp.cs.berkeley.edu/redmine/projects/gdp_router_click/]()
231 ab0dd3c7 Eric Allman
232
(: vim: set ai sw=4 sts=4 ts=4 :)