Project

General

Profile

Statistics
| Branch: | Revision:

gdp-router-click / README.md @ master

History | View | Annotate | Download (7.84 KB)

GDP v2 Network Router

Brief Overview

The GDP project has produced several implementations of the GDP Router over many years of design evolution. The two most recent implementations reside in this gdprouterclick repository, however the most recent (i.e. current) GDP v2 Network gdp-router-click binary is built from just two source files (src/gdp_v4_router.cc and src/gdp_v4_router.hh) which are integrated and built into the latest Click modular router automatically under the control of make.

The latest GDP Router supports standard GDP clients connecting over TCP sessions, and router peering over dTLS sessions, with any network topology one might wish to configure. The network itself also provides reliable PDU delivery services across the datagram-based portion of any network topology.

The gdp-router-click binary will, if launched with no configuration, peer directly with the UC Berkeley GDP v2 Network by default and use the UC Berkeley RIB service. The gdp-router-click binary may also be configured to launch in "single router" mode for isolated GDP experimentation, though one must also launch a few other GDP services (currently HONGDB, logCreationService, and gdplogd) in order to make use of gdp-create, gdp-writer, or gdp-reader in an isolated environment. In addition to the "single router" mode's itemization of required components, a standard (not "single router" mode) GDP v2 Network deployment also requires a RIB service instance per GDP Trust Domain. The various required services (and their documentation) are made available through the gdp repository.

The easiest way to begin experimenting with a GDP router binary and local GDP client applications is to let your router instance directly peer with the UC Berkeley GDP v2 Network, which operates all of the required services (RIB service, HONGDB, logCreationService, and multiple gdplogd instances). Please contact the GDP team, if questions arise.

Router Build:

Prerequisites: To build, you will need to have git installed. If you are compiling on Ubuntu 18.04 you also need to have openssl1.0 installed (the default is openssl1.1, which does not compile.

apt install git libssl1.0-dev

The router build will automatically git clone dependent repositories (GDP and Click), which will be created within the build subdirectory. Therefore, a successful first build requires Internet access, while rebuilds may occur offline. To launch the build of gdp-router-click:

$ make gdp-router-click

A simple test can be conducted on the resulting binary by launching the router in single router mode:

$ ./gdp-router-click -e "GDPR::GDPv4Router(SINGLE_ROUTER true, DEBUG 1); GDPR;"

Output will be similar to the following:

    Starting gdp-router-click (v2 master 67d687d61a212ee692d6d600d81c776ff9f070bc)
        as gdpr-01.8009
        aka HLwmHH7Pw9mAenUHnCI0mWlP-l5O4nqmlXpjoU3bUH0
        with debug 0
        listening on any udp 8009 and tcp 8009
        single router mode (no directory service)
    (4)TL new tcp listen

Use Control-C to interrupt the above test.

Router First-Time Installation:

[Tested on Ubuntu 16.04]

To install systemd and related operational files, along with a default configuration which will run the router instalation in "single router" mode, run (presuming sudo privileges are configured):

$ make install-gdp-router-click

When installing routers on various hosts in a full GDP v2 Network Trust Domain installation, each router instance can be installed as shown above, but it will also be necessary to edit each instance's configuration (typically found in /etc/gdp/gdp-router-click.conf) and then execute "systemctl restart gdp-router-click" to put the desired router configuration into effect.

Router Rebuild Installation:

$ [sudo] make reinstall

Router Operation:

Have systemd to start the router (in "single router" mode if first-time install):

$ systemctl start gdp-router-click

Check the router status:

$ systemctl status gdp-router-click

To monitor the router log:

$ tail -F /var/log/gdp/gdp-router-click.log

To stop the router:

$ systemctl stop gdp-router-click

Router Configuration:

Click can read a file or accept configuration as an expression parameter when launched. Run "gdp-router-click --help" for further details.

A valid gdp-router-click configuration requires the following structure, though any name can be used in place of both instances of the "GDPR" string:

    GDPR::GDPv4Router(...); GDPR;

The ellipsis, shown above, must be replaced with a valid configuration constructed from zero or more Named Parameters followed by zero or more Routing Peers, in comma-separated list format. An empty configuration is a valid configuration; it will draw upon internal defaults to implicitly connect the router to a randomly selected GDP core router and the GDP RIB service at UC Berkeley. More complex configurations are built by appending named parameters and routing peers into a comma-separated list, though non-zero routing peer lists must explicitly include at least one GDP core router peer.

Named Parameters

    TCP_PORT <port>        Listen for clients on non-default tcp port
    UDP_PORT <port>        Listen for routing peers on non-default udp port
    IP <address>           Listen for routing peers on one address, not any/all
    GDPNAME <gdpname>      Override gdpname generation with explicit gdpname
    HOSTNAME <hostname>    Override hostname discovery in gdpname generation [1]
    SINGLE_ROUTER true     Route clients locally (no routing peers or RIB)
    RIBNAME <hostname>     Override GDP RIB service default hostname
    IP_RIB <address>       Override GDP RIB service address, ignores RIBNAME
    UDP_PORT_RIB <port>    Override GDP RIB service default port
    ADVERT_TIMER <us>      Override advertisement timer interval [2]
    DEBUG <level>          Not intended for normal operation, increases cpu load

[1] If GDPNAME has been configured, HOSTNAME is invalid configuration input.
[2] The default value is 128000 microseconds, but site specific tuning needed.

Routing Peers

    <peer_hostname_or_ip_address> [, <peer_non-default_port> ]

Configuration Examples:

    // route clients locally only (no routing peers or GDP RIB)
    R::GDPv4Router(SINGLE_ROUTER true); R;

    // route clients locally only, using a local GDP RIB host (no routing peers)
    R::GDPv4Router(RIBNAME gdp-ribd.domain); R;

    // route clients locally only, using a local GDP RIB IP (no routing peers)
    R::GDPv4Router(IP_RIB 10.1.1.1); R;

    // connect to the GDP via defaults, implicitly connects to a GDP core router
    R::GDPv4Router(); R;

    // connect to the GDP via gdp-01, and also connect to r1 in local domain
    R::GDPv4Router(gdp-01.eecs.berkeley.edu, r1.domain); R;

    // connect to the GDP via gdp-01, and also connect to r1 on port 8010
    R::GDPv4Router(gdp-01.eecs.berkeley.edu, r1.domain, 8010); R;

    // connect to the GDP via gdp-03, and also connect to r1 on port 8010 and r2
    R::GDPv4Router(gdp-03.eecs.berkeley.edu, r1.domain, 8010, r2.domain); R;

    // connect to the GDP via gdp-03, and connect to r1's IP on port 8010 and r2
    R::GDPv4Router(gdp-03.eecs.berkeley.edu, 10.1.1.1, 8010, r2.domain); R;

Docker Configuration Examples:

    // equivalent to first example in prior section, uses container name/bridge
    docker run -e CONFIG="SINGLE_ROUTER true" <docker_image>

    // equivalent to second example in prior section, uses container name/bridge
    docker run <docker_image>

    // equivalent to third example in prior section, uses host's name/network
    docker run --network='host' <docker_image>

    // equivalent to fourth example in prior section, uses host's name/network
    docker run --network='host' \
        -e CONFIG="gdp-01.eecs.berkeley.edu, r1.domain, 8010" <docker_image>

For additional information, see:

https://gdp.cs.berkeley.edu/redmine/projects/gdprouterclick/

(: vim: set ai sw=4 sts=4 ts=4 :)