README.md

edgesec

edgesec defines a new architecture and toolset for edge based routers addressing fundamental security weaknesses that impact current IP and IoT router implementations.

For more information, please see the edgesec website: https://edgesec.info

Dependencies

On Debian/Ubuntu, build dependencies are listed in the debian/control file.

You can use mk-build-deps to automatically install these build-dependencies.

sudo apt install devscripts equivs # install mk-build-depends
sudo mk-build-deps --install debian/control

On other OSes, you can try to find dependencies yourself, or you can run the instructions in a new Ubuntu Docker or Podman container:

# in root of git repo (where the `CMakePresets.json` file is)
docker run --rm -it --volume "$PWD":/opt/EDGESec --workdir /opt/EDGESec ubuntu:jammy bash
# then run the Debian/Ubuntu dependencies setup instructions

Compile & Build

Compiling edgesec is done with CMake.

If you have CMake v3.22+, you can use the following cmake-presets to compile edgesec:

cmake --list-presets # list all available presets
cmake --preset linux # configure edgesec for Linux
cmake --build --preset linux -j4 # build edgesec for Linux using 4 threads
ctest --preset linux # test edgesec for Linux

A useful one-liner (i.e. for git rebase) is the following, which given a preset, automatically configures, compiles (using all cores, but nice -n19 for lower CPU priority), tests (if a test config exists), then installs into the ./tmp folder.

export PRESET=linux && cmake --preset "$PRESET" && nice -n19 cmake --build --preset "$PRESET" -j=$(nproc) && { if ctest --list-presets | grep "\"$PRESET\""; then ctest --preset "$PRESET" --output-on-failure -j=$(nproc); fi } && cmake --install "./build/$PRESET" --prefix "./tmp/$PRESET"

For older versions of CMake, or for manual configuration, please see the next headings for more details.

Configure

Configure cmake in the build/ directory by running the following:

# or for old versions of cmake, do: mkdir build/ && cd build/ && cmake ..
cmake -S . -B build

The configure stage will download some of the edgesec dependencies, so this may take a while.

Configure for cross-compiling

To cross-compile edgesec, pass CMake a cmake-toolchain file.

For example:

cmake -S . -B build --toolchain ./CMakeModules/CMakeToolchains/openwrt-ath79-generic.cmake

In ./CMakeModules/CMakeToolchains, we have some example toolchains that automatically download the OpenWRT SDK to cross-compile for specific OpenWRT SDK versions.

You can also make a new preset in the CMakePresets.json file that points to this toolchain.

Configure for OpenWRT

For production uses of edgesec, we recommend using the edgesec OpenWRT package feed at https://github.com/nqminds/manysecured-openwrt-packages

It comes with an /etc/init.d/edgesec script that can be used to automatically run edgesec on startup.

Additionally, this package allows easy installation/uninstallation of edgesec.

Building

To build, you can then run:

# or for old versions of cmake, do: cd build/ && make
cmake --build build/

or to built on multiple core run:

cmake --build build/ -j4

-j4 means 4 jobs/threads, replace 4 with the amount of cores you want to use, equivalent to make -j4.

After succesful compilation the binary will be located in ./build/src folder.

Running

To run edgesec tool with the configuration file dev-config.ini located in ./build folder use:

./build/src/edgesec -c ./build/dev-config.ini

To enable verbose debug mode use:

./build/src/edgesec -c ./build/dev-config.ini -ddddd

Testing

To compile the tests use:

cmake -B build/ -S . # configure CMAKE
cmake --build build/ -j4 # or make -j4
cmake --build build/ --target test -j4 # or 'make test'

To run each test individually, the test binaries can be located in ./build/tests folder.

Developer Documentation

To compile the docs from ./build folder:

make doxydocs

See ./docs for how to build the developer doxygen documentation website.