-
Notifications
You must be signed in to change notification settings - Fork 0
Code and Binaries
Pre-built .deb packages can be found here. For Ubuntu 20, 22 and 24 there are e2sar_<version>_amd64.deb containing E2SAR include files, library, python bindings and binaries. In addition to assist with developing E2SAR, .deb packages are provided containing just the dependencies for E2SAR called e2sar-deps_<version>_amd64.deb (these generally contain gRPC and Boost libraries of appropriate versions). All installs go under /usr/local/.
Once the debian packages are installed, the library can be liked using PkgConfig. The install path of the pkgconfig is /usr/local/lib/x86_64-linux-gnu/pkgconfig/e2sar.pc. PkgConfig should be able to resolve this by itself otherwise you can set the PKG_CONFIG_PATH as an environment variable or pass it to your build system. You would also need to link with Boost, Protobuf, Threads and GRPC. An example cmake config to link with E2SAR is given below.
project(E2SAR_ERSAP_SEGMENTOR CXX)
set(CMAKE_CXX_STANDARD 17)
find_package(Boost COMPONENTS system url thread chrono random program_options REQUIRED )
find_package(PkgConfig REQUIRED)
find_package(Threads REQUIRED)
find_program(PKG_CONFIG_EXECUTABLE pkg-config)
pkg_check_modules(E2SAR REQUIRED e2sar)
pkg_check_modules(GRPC REQUIRED grpc++)
add_library(e2sarSegmentor SHARED src/cpp/segmentor_actor.cpp )
target_link_libraries(e2sarSegmentor ${E2SAR_LIBRARIES}
${Boost_LIBRARIES} ${GRPC_LIBRARIES} ${Protobuf_LIBRARIES} Threads::Threads)
install(TARGETS ersapSegmentor DESTINATION "dest")
Be sure to set your PATH to include /usr/local/bin and LD_LIBRARY_PATH to include /usr/local/lib. Similarly /usr/local/include should be on your include path when compiling:
$ export PATH=/usr/local/bin:$PATH
$ export LD_LIBRARY_PATH=/usr/local/lib
- Installation of Python3.10 is required:
$ sudo apt-get -yq update
$ sudo apt-get install -yq software-properties-common
$ sudo add-apt-repository -y ppa:deadsnakes/ppa
$ sudo apt-get -yq update
$ sudo apt-get -yq install python3.10
$ sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.8 1
$ sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 2
A command-line utility for issuing control plane gRPC commands.
$ ./build/bin/lbadm -h [21:51:06]
E2SAR Version: 0.1.2
Command-line options:
-h [ --help ] show this help message
-l [ --lbname ] arg specify name of the load balancer
-i [ --lbid ] arg override/provide id of the loadbalancer
-a [ --address ] arg node IPv4/IPv6 address, can be used
multiple times for 'reserve' call
-d [ --duration ] arg (=02:00:00) specify duration as '[hh[:mm[:ss]]]'
-u [ --uri ] arg specify EJFAT_URI on the command-line
instead of the environment variable
-n [ --name ] arg specify node name for registration
-p [ --port ] arg node starting listening port number
-w [ --weight ] arg (=1) node weight
-c [ --count ] arg (=1) node source count
-s [ --session ] arg override/provide session id
-q [ --queue ] arg (=0) queue fill
-t [ --ctrl ] arg (=0) control signal value
-r [ --ready ] arg (=1) worker ready state (1 or 0)
-o [ --root ] arg root cert for SSL communications
-v [ --novalidate ] don't validate server certificate
(conflicts with 'root')
--minfactor arg (=0.5) node min factor, multiplied with the number
of slots that would be assigned evenly to
determine min number of slots for example,
4 nodes with a minFactor of 0.5 = (512
slots / 4) * 0.5 = min 64 slots
--maxfactor arg (=2) multiplied with the number of slots that
would be assigned evenly to determine max
number of slots for example, 4 nodes with a
maxFactor of 2 = (512 slots / 4) * 2 = max
256 slots set to 0 to specify no maximum
-6 [ --ipv6 ] force using IPv6 control plane address if
URI specifies hostname (disables cert
validation)
-4 [ --ipv4 ] force using IPv4 control plane address if
URI specifies hostname (disables cert
validation)
-e [ --export ] suppresses other messages and prints out
'export EJFAT_URI=<the new uri>' returned
by the LB
--reserve reserve a load balancer (-l, -a, -d
required). Uses admin token.
--free free a load balancer. Uses instance or
admin token.
--version report the version of the LB. Uses admin or
instance token.
--register register a worker (-n, -a, -p, -w, -c
required), note you must use 'state' within
10 seconds or worker is deregistered. Uses
instance or admin token.
--deregister deregister worker. Uses instance or session
token.
--status get and print LB status. Uses admin or
instance token.
--state send worker state update (must be done
within 10 sec of registration) (-q, -c, -r
required). Uses session token.
--overview return metadata and status information on
all registered load balancers. Uses admin
token.
--addsenders add 'safe' sender IP addresses to CP (one
or more -a required). Uses instance token.
--removesenders remove 'safe' sender IP addresses from CP
(one or more -a required). Uses instance
token.
A command-line utility to monitor a particular instance of load balancer.
$ ./build/bin/lbmon -h [21:55:15]
E2SAR Version: 0.1.2
Command-line options:
-h [ --help ] EJFAT LB MonitorThis tool can be used to either check
the status of a reserved LB with an instance tokenor to
check the overview of the LB with an admin tokenIf lbid
is specified in EJFAT_URI/argument, it will default to
status of LBEJFAT_URI must be specified in this format
ejfat[s]://<token>@<cp name or ip>:<cp port>/lb/<lbid>
-i [ --lbid ] arg specify id of the loadbalancer as issued by reserve
call instead of using what is in EJFAT_URI
-o [ --root ] arg root cert for SSL communications
-v [ --novalidate ] don't validate server certificate (conflicts with
'root')
-6 [ --ipv6 ] prefer IPv6 control plane address if URI specifies
hostname (disables cert validation)
-4 [ --ipv4 ] prefer IPv4 control plane address if URI specifies
hostname (disables cert validation)
-u [ --uri ] arg specify EJFAT_URI on the command-line instead of the
environment variable
-t [ --time ] arg specify refresh time in ms (default is 5000ms)
A command-line performance testing utility, somehwat similar to iperf, but specific to E2SAR
$ ./build/bin/e2sar_perf -h [21:56:03]
E2SAR Version: 0.1.2
Command-line options:
-h [ --help ] show this help message
-s [ --send ] send traffic
-r [ --recv ] receive traffic
-l [ --length ] arg (=1048576) event buffer length (defaults to 1024^2) [s]
-u [ --uri ] arg specify EJFAT_URI on the command-line instead
of the environment variable
-n [ --num ] arg (=10) number of event buffers to send (defaults to
10) [s]
-e [ --enum ] arg (=0) starting event number (defaults to 0) [s]
-m [ --mtu ] arg (=1500) MTU (default 1500) [s]
--src arg (=1234) Event source (default 1234) [s]
--dataid arg (=4321) Data id (default 4321) [s]
--threads arg (=1) number of receive threads (defaults to 1) [r]
--sockets arg (=4) number of send sockets (defaults to 4) [r]
--rate arg (=1) send rate in Gbps (defaults to 1.0)
-p [ --period ] arg (=1000) receive side reporting thread sleep period in
ms (defaults to 1000) [r]
-b [ --bufsize ] arg (=3145728) send or receive socket buffer size (default
to 3MB)
-d [ --duration ] arg (=0) duration for receiver to run for (defaults to
0 - until Ctrl-C is pressed)
-c [ --withcp ] enable control plane interactions
-i [ --ini ] arg INI file to initialize SegmenterFlags [s]] or
ReassemblerFlags [r]. Values found in the
file override --withcp, --mtu and --bufsize
--ip arg (=127.0.0.1) IP address (IPv4 or IPv6) from which sender
sends from or on which receiver listens.
Defaults to 127.0.0.1. [s,r]
--port arg (=10000) Starting UDP port number on which receiver
listens. Defaults to 10000. [r]
-6 [ --ipv6 ] force using IPv6 control plane address if URI
specifies hostname (disables cert validation)
[s,r]
-4 [ --ipv4 ] force using IPv4 control plane address if URI
specifies hostname (disables cert validation)
[s,r]
-v [ --novalidate ] don't validate server certificate
A scapy script that can generate and listen for dataplane and sync control plane UDP messages. It can listen/generate sync UDP packets, data plane UDP packets with LB+RE headers and dataplane with only RE headers and arbitrary payloads:
$ ./snifgen.py -h
usage: snifgen.py [-h] (-l | -g | -a) [-p PORT] [-y SYNCPORT] [-n NPORTS] [-c COUNT] [--ip IP] [--show] [--entropy ENTROPY] [--event EVENT] [--rate RATE] [--dataid DATAID] [--srcid SRCID] [--mtu MTU] [--pld PLD]
[--iface IFACE] [-f FILE] (--sync | --lbre | --re | --lbresync)
options:
-h, --help show this help message and exit
-l, --listen listen for incoming packets and try to parse and validate them
-g, --generate generate new packets of specific types
-a, --parse parse a pcap file. The recommended way to capture is something like this 'sudo tcpdump -s 200 -tttt -i enp7s0 udp \( dst port 19522 or dst port 19523 \) -w e2sar.pcap'
-p PORT, --port PORT UDP data port (only port for --lbre, starting port for --re)
-y SYNCPORT, --syncport SYNCPORT
UDP sync port
-n NPORTS, --nports NPORTS
number of ports starting with -p to listen on for --re
-c COUNT, --count COUNT
number of events (if pld larger than mtu, otherwise packets) to generate or expect or parse
--ip IP IP address to which to send the packet(s) or listen from
--show only show the packet without sending it (with -g)
--entropy ENTROPY entropy value for LB+RE packet
--event EVENT event number for sync, LB+RE and RE packet
--rate RATE event rate in Hz for Sync packet
--dataid DATAID data id for RE packet
--srcid SRCID source id for Sync packet
--mtu MTU set the MTU length, so LB+RE and RE packets can be fragmented.
--pld PLD payload for LB+RE or RE packets. May be broken up if MTU size insufficient
--iface IFACE which interface should we listen on (defaults to all)
-f FILE, --file FILE pcap file name to parse
--sync listen for, parse or generate Sync packets
--lbre listen for, parse or generate packets with LB+RE header
--re listen for, parse or generate packets with just the RE header
--lbresync listen for or parse LB+RE and Sync packetsTypical uses may include (note the scripts have sane defaults for everything, but can be overridden with command line):
Generate a LB+RE header packet with a specific payload. Only show it without sending (doesn't need root privilege)
$ ./snifgen.py -g --lbre --pld "this is payload" --show -c 1 Generate and send a LB+RE header packet to 192.168.100.10 with a specific payload. Use default MTU of 1500.
$ ./snifgen.py -g --lbre --pld "this is payload" --ip "192.168.100.10" -c 1 Generate and send a RE header packet to 192.168.100.10 with a specific payload. Use MTU of 50.
$ ./snifgen.py -g --re --pld "this is payload" --ip "192.168.100.10" --mtu 50 -c 1 Listen for 10 Sync packets sent to port 18347 then exit.
$ ./snifgen -l -p 18347 -c 10 --syncListen for 10 Sync packets sent to 192.168.100.10 port 18347 then exit.
$ ./snifgen -l -p 18347 -c 10 --ip "192.168.100.10" --syncParse PCAP file of the sender including both LBRE and Sync packets (LB packets sent to port 19522, Sync packets sent to port 19522, parse all available events -c 0):
$ ./snifgen.py --parse --lbresync --file e2sar-sender-with-sync.pcap --port 19522 --syncport 19010 -c 0 > e2sar-sender-parsed-v2.txtParse PCAP file for RE packets, produced on a worker listening on 4 ports starting from 10000:
$ ./snifgen.py --parse --re --file e2sar-worker3.pcap --port 10000 --nports 4 -c 0 > e2sar-worker3-parsed.txtThe binaries are offered as part of a docker image available through DockerHub. To run e.g. lbadm from inside the container you can do something like this (in this example issuing a version() command):
$ docker run --rm ibaldin/e2sar:latest lbadm --version -u "ejfats://[email protected]:18347/" -v