Build Falco from source
Welcome to the guide on how to build Falco yourself! You are very brave! Since you are already doing all this, chances that you are willing to contribute are high! Please read our contributing guide.
- Install the dependencies
CentOS 7 / RHEL 7
You will also need cmake
version 3.5.1
or higher which is not included in CentOS 7. You can follow the official guide or look at how that is done in the Falco builder Dockerfile.
CentOS 8 / RHEL 8
Since Alpine ships with musl
instead of glibc
, to build on Alpine, we need to pass the -DMUSL_OPTIMIZED_BUILD=On
CMake option.
If that option is used along with the -DUSE_BUNDLED_DEPS=On
option, then the final build will be 100% statically-linked and portable across different Linux distributions.
- Build Falco
More details here.
You can skip this on Ubuntu 18.04.
If you are on Ubuntu 18.04, instead of cmake ..
do cmake -DUSE_BUNDLED_DEPS=ON ..
.
More details here.
More details here.
More details here.
- Build kernel module driver
Kernel headers are required to build the driver.
In the build directory:
NO STEP
In the build directory:
- Build eBPF driver (optional)
If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.
In the build directory:
If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.
In the build directory:
If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.
In the build directory:
NO STEP
If you do not want to use the kernel module driver you can, alternatively, build the eBPF driver as follows.
In the build directory:
Dependencies
By default Falco build bundles most of its runtime dependencies dynamically.
You can notice this observing that the option USE_BUNDLED_DEPS
is OFF
by default. Which means that, whether applicable, Falco build will try to link against libraries already existing into your machine.
Changing such option to ON
causes Falco build to bundle all the dependencies statically.
For the sake of completeness this is the complete list of Falco dependencies:
- b64
- cares
- curl
- civetweb
- grpc
- jq
- libyaml
- lpeg
- luajit
- lyaml
- ncurses
- njson
- openssl
- protobuf
- tbb
- yamlcpp
- zlib
- libscap
- libsinsp
Build Falco
There are two supported ways to build Falco
Build directly on host
To build Falco, you will need to create a build
directory.
It's common to have the build
directory in the Falco working copy itself, however it can be
anywhere in your filesystem.
There are three main steps to compile Falco.
- Create the build directory and enter in it
- Use cmake in the build directory to create the build files for Falco.
..
was used because the source directory is a parent of the current directory, you can also use the absolute path for the Falco source code instead - Build using make
Build all
You can also build only specific targets:
Build Falco only
Do the build folder and cmake setup, then:
Build the Falco engine only
Do the build folder and cmake setup, then:
Build libscap only
Do the build folder and cmake setup, then:
Build libsinsp only
Do the build folder and cmake setup, then:
Build the eBPF probe / kernel driver only
Do the build folder and cmake setup, then:
Build results
Once Falco is built, the three interesting things that you will find in your build
folder are:
userspace/falco/falco
: the actual Falco binarydriver/src/falco.ko
: the Falco kernel driverdriver/bpf/falco.o
: if you built Falco with BPF support
If you'd like to build a debug version, run cmake as cmake -DCMAKE_BUILD_TYPE=Debug ..
instead, see the CMake Options section for further customizations.
CMake Options
When doing the cmake
command, we can pass additional parameters to change the behavior of the build files.
Here'are some examples, always assuming your build
folder is inside the Falco working copy.
Generate verbose makefiles
Specify C and CXX compilers
-DCMAKE_C_COMPILER=$(which gcc) -DCMAKE_CXX_COMPILER=$(which g++)
Enforce bundled dependencies
-DUSE_BUNDLED_DEPS=True
Read more about Falco dependencies here.
Treat warnings as errors
-DBUILD_WARNINGS_AS_ERRORS=True
Specify the build type
Debug build type
-DCMAKE_BUILD_TYPE=Debug
Release build type
-DCMAKE_BUILD_TYPE=Release
Notice this variable is case-insensitive and it defaults to release.
Specify the Falco version
Optionally the user can specify the version he wants Falco to have. Eg.,
-DFALCO_VERSION=0.29.0-dirty
When not explicitly specifying it the build system will compute the FALCO_VERSION
value from the git history.
In case the current git revision has a git tag, the Falco version will be equal to it (without the leading "v" character). Otherwise the Falco version will be in the form 0.<commit hash>[.dirty]
.
Enable BPF support
-DBUILD_BPF=True
When enabling this you will be able to make the bpf
target after:
Build using falco-builder container
An alternative way to build Falco is to run the falco-builder container. It contains the reference toolchain that can be used to build packages and all the dependencies are already satisfied.
The image depends on the following parameters:
BUILD_TYPE
: debug or release (case-insensitive, defaults to release)BUILD_DRIVER
: whether or not to build the kernel module when building. This should usually be OFF, as the kernel module would be built for the files in the centos image, not the host.BUILD_BPF
: LikeBUILD_DRIVER
but for the ebpf program.BUILD_WARNINGS_AS_ERRORS
: consider all build warnings fatalMAKE_JOBS
: passed to the -j argument of make
A typical way to run this builder is the following. Assuming you have checked out Falco and Sysdig to directories below /home/user/src, and want to use a build directory of /home/user/build/falco, you would run the following:
It's also possible to explicitly provide the FALCO_VERSION
environment variable to use it as the version for any built package.
Otherwise the docker image will use the default FALCO_VERSION
.
Load latest falco kernel module
If you have a binary version of Falco installed, an older Falco kernel module may already be loaded. To ensure you are using the latest version, you should unload any existing Falco kernel module and load the locally built version.
Unload any existing kernel module via:
To load the locally built version, assuming you are in the build
dir, use:
Run falco
Once Falco is built and the kernel module is loaded, assuming you are in the build
dir, you can run falco as:
By default, falco logs events to standard error.
Run regression tests
Test directly on host
To run regression tests, after building Falco, in the Falco root directory, you need to run the test/run_regression_tests.sh
script.
Dependencies
You will need the following dependencies for the regression testing framework to work.
- Python 3
- Avocado Framework, version 69
- Avocado Yaml to Mux plugin
- JQ
- The
unzip
andxargs
commands - Docker CE
You will also need to obtain some test fixtures from the internet for the regression test suites to work.
For the python dependencies, how to setup the virtualenv, how to obtain test fixtures, read more here.
Run the tests
Change $PWD/build
with the directory you built Falco in, if different.
Test using falco-tester container
If you'd like to run the regression test suite against your build, you can use the falco-tester container. Like the builder image, it contains the necessary environment to run the regression tests, but relies on a source directory and build directory that are mounted into the image. It's a different image than falco-builder
as it doesn't need a compiler and needs a different base image to include the test runner framework avocado.
It does build a new container image falcosecurity/falco:test
(which source is into docker/local
directory into Falco GitHub repository) to test the process of buillding and running a container with the Falco packages built during the build step.
The image depends on the following parameters:
FALCO_VERSION
: The version of the Falco package to include in the test container image. It must match the version of the built packages.
A typical way to run this builder is the following. Assuming you have
checked out Falco and Sysdig to directories below /home/user/src
, and
want to use a build directory of /home/user/build/falco
, you would run
the following:
Mounting $HOME
allows the test execution framework to run. You may need to replace $(id -g)
with the right gid of the group that is allowed to access the docker socket (often the docker
group).
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.