Summary

Even though the goal is to get the EPS network clients to run as a mesh, a single EPS server is still required to co-ordinate between the clients. Each EPS network must have exactly 1 server. Preferably, you'll have 3 computers to use when testing EPS for the first time: 2 clients and 1 server.

Note: For advanced users, note that a computer can simultaneously run both the EPS client and the EPS server.

The EPS server must be reachable by all EPS clients that want to participate in the EPS network. If the server is on a private network or behind a firewall, then a TCP port will need to be forwarded or a hole created in the appropriate firewall. Since version 0.0.2-628, EPS server uses UPnP (when available) to automatically setup the necessary port forwarding.

The EPS client runs on every computer that wants to establish a "EPS conduit". The client computers connect to the EPS server, from which they'll receive their initial configuration and periodic updates. Clients then bring up the requested network, sets up a default route, and both forwards and receives packets for the new network.

Run as root

Running EPS networks requires bringing up TAP interfaces, setting and removing network routes, and using some configuration files from /etc/ which are owned by root. This is why both the EPS clients and server requires root access to work correctly. Remember to use sudo or whatever other means necessary for the EPS software to have the necessary permissions.

Log files

The EPS client log files are named /var/log/eps_client.log.
The EPS server log files are named /var/log/eps_server.log.
All EPS log files are automatically rolled and deleted as necessary.

Command-line parameters

Note: The instructions on this page are still valid, but since EPS Conduits version 0.0.1-593, a new shell script called /usr/bin/eps-configure.sh was added to the product. This script should make configuration much easier. Instead of manually editing /etc/eps.conf or having to specify command-line parameters, you may want to try and run "sudo eps-configure.sh" after the .deb or .rpm package has been installed.

The EPS client accepts these parameters:

sudo eps-client --help
Common options:
  --conf arg (=/etc/eps.conf)
                        filename from which additional %EPS configuration will be read
  --help                show this help message
  --version             show version information
Logging and statistics:
  --log arg (=/var/log/eps_client.log)
                        file to which logging messages will be written (file is auto-rotated)
  --stats               log statistics every 60 seconds
  --scorecard [=arg(=/var/log/eps_client.stats)]
                        file where statistics scorecard is written every 60 seconds
Client options:
  --port arg (=43439)   TCP/UDP port of the server
  --server arg          IP address (or hostname) of the server

The EPS server accepts similar parameters:

sudo src-server/eps-server --help
Common options:
  --conf arg (=/etc/eps.conf)
                        filename from which additional %EPS configuration will be read
  --help                show this help message
  --version             show version information
Logging and statistics:
  --log arg (=/var/log/eps_server.log)
                        file to which logging messages will be written (file is auto-rotated)
  --stats               log statistics every 60 seconds
  --scorecard [=arg(=/var/log/eps_server.stats)]
                        file where statistics scorecard is written every 60 seconds
Server options:
  --graphviz [=arg(=/var/log/eps.gv)]
                        file to which a Graphviz-format network diagram is written every 5 minutes
  --network arg (=192.168.43.0/24)
                        network (with mask) to create
  --port arg (=43439)   TCP/UDP listening port to bind
  --sequential          new clients will be assign IP addresses sequentially (.1, .2, .3, etc) instead of from within the pool
  --upnptimeout arg (=1000)
                        UPnP timeout in milliseconds (set to zero to disable UPnP support)

--conf

The EPS clients and server normally read extra configuration settings from /etc/eps.conf. This command-line option can be used to specify a different file.

--conf /home/foobar/eps/eps.config

See also: EPS::Hull::conf_filename

Note: All of the command-line parameters can also be specified in the eps.conf configuration file.

--graphviz

The EPS server can write out a Graphviz-format network diagram every 5 minutes. This includes transfer and bandwidth statistics on all clients on the EPS network. This command-line option can be used to specify a different file to which the Graphviz file will be written.

--graphviz /tmp/eps_network.gv

The resulting .gv files can be rendered using any of the usual Graphviz tools. For example:

circo -Tpng /var/log/eps_network.gv > output.png

--log

The EPS clients and server logs messages to a log file. This is usually /var/log/eps* but this command-line option can be used to specify a different file.

--log /tmp/eps.log

--network

The EPS server selects a class 'C' network for the EPS network, and then assigns addresses from within this network to each EPS member that wants to join the network. By default, the network selected is 192.168.43.0/24. If this network is already in use on any of your clients, you must select a different network when starting up the EPS server. Several different examples:

--network 192.168.99.0/24
--network 10.0.8.0/24
--network 172.20.18.0/24

Note: The EPS networks are currently limited to 24-bit (class 'C') networks. This limitation will be removed in the future.; The –network command-line parameter only applies to the EPS server.

See also: EPS::Hull::network_str

--port

By default, the server listens for EPS clients on TCP/UDP port 43439. This parameter can be used to specify a different port. For example:

--port 12345

See also: --server; EPS::Hull::port

--scorecard

Statistics are compiled every minute by EPS. These statistics can also be written out to a scorecard and easily processed by any 3rd-party software. The –scorecard parameter names the file to use as a scorecard. For example:

--scorecard /var/log/eps.stats

See also: --stats; EPS::Hull::scorecard

--sequential

The EPS server normally assigns IP addresses to the EPS clients in a random manner. By specifying –sequential the IP addresses will be assigned sequentially (192.168.43.1, 192.168.43.2, 192.168.43.3, etc) starting with the lowest available address first.

See also: EPS::Hull::sequential

--server

The EPS clients need to know where the EPS server can be reached. This can be specified using either a resolvable hostname or an IP address. Multiple names or IP addresses can be listed. Several examples:

--server 192.168.1.42
--server eps.example.com
--server "192.168.1.42 eps.example.com test.example.com"

Note: The –server command-line parameter only applies to the EPS client.

See also: --port; EPS::Hull::addr

--stats

Statistics are compiled every minute by EPS. Since logging these statistics every minute can quickly overwhelm the log files /var/log/eps_*.log these statistics are usually not logged. To enable togging the statistics to /var/log/eps_*.log you must specify the –stats command-line option.

When specified, you'll see statistics such as these every 60 seconds:

cat /var/log/eps_server_0.log
...
2014-06-23 20:31:59.634678 [00000x3f32:0x00007fe87f970780]    info  - in: 3.81 MBps (30.50 Mbps), out: 0.00 Bps (0.00 bps), fwd: 3.81 MBps (30.50 Mbps)
2014-06-23 20:31:59.635310 [00000x3f32:0x00007fe87f970780]    info  - EPS statistics:
60-second stats:
269119 packets forwarded
228757979 bytes forwarded (228.76 MBytes)
269119 packets received
228757979 bytes received (228.76 MBytes)
total stats:
1690156 packets forwarded
1436434521 bytes forwarded (1.44 GBytes)
1690102 packets received
1436426256 bytes received (1.44 GBytes)
12 packets sent
615 bytes sent (0.62 KBytes)
3 connections established

See also: --scorecard

--upnptimeout

The EPS server uses UPnP when available on the network to automatically setup TCP and UDP port forwarding. This parameter can be used to specify the length of time (in milliseconds) the EPS server initially waits for a UPnP-capable router or NAT device. If set to zero, this will disable UPnP in EPS server, in which case manually configuring port forwarding will be required if the server is behind a firewall or NAT device.

--upnptimeout 1000

Examples

sudo eps-server --stats --scorecard /var/log/eps_server.stats --port 12545 --network 192.168.99.0/24

sudo eps-client --stats --scorecard /var/log/eps_client.stats --port 12345 --server 10.0.1.1