diff --git a/content/docs/source.md b/content/docs/source.md index 2d1b12d1f..743d7b618 100644 --- a/content/docs/source.md +++ b/content/docs/source.md @@ -1,13 +1,261 @@ --- -title: Installing Falco from Source +title: Build Falco from source weight: 6 --- -Building falco requires having `cmake` and `g++` installed. +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](https://github.com/falcosecurity/falco/blob/dev/CONTRIBUTING.md). + +## System requirements + +In order compile Falco, you will need the following tools and installed on your machine. + +- wget +- pkg-config +- make +- cmake +- gcc +- g++ +- kernel headers +- libelf-dev + +Following, you can find how to meet the minimum requirements in the most common Linux distros. + +### CentOS/RHEL + +```bash +yum install gcc gcc-c++ cmake make pkgconfig autoconf wget automake patch elfutils-libelf libtool kernel-devel kernel-headers +``` + +### Fedora + +```bash +dnf install gcc gcc-c++ cmake make pkgconfig autoconf wget automake patch elfutils-libelf libtool kernel-devel kernel-headers +``` + +### Ubuntu + +``` +apt install build-essential cmake autoconf wget automake patch elfutils libelf-dev pkg-config libtool linux-headers-$(uname -r) +``` + +### Debian + +``` +apt install build-essential cmake autoconf wget automake patch elfutils libelf-dev pkg-config libtool linux-headers-$(uname -r) +``` + +### Arch Linux + +``` +pacman -S gcc cmake make pkgconfig autoconf automake patch elfutils libelf libtool linux-headers +``` + +## Runtime dependencies + +By default Falco build bundles its runtime dependencies statically. + +You can notice this observing that the option [`USE_BUNDLED_DEPS`](https://github.com/falcosecurity/falco/blob/75b816d806d29bd47ace6b14a311c18dfc610d19/CMakeLists.txt#L86) is `ON` by default. Which in turn causes all of the dependencies options (eg., [`USE_BUNDLED_ZLIB`](https://github.com/falcosecurity/falco/blob/75b816d806d29bd47ace6b14a311c18dfc610d19/CMakeLists.txt#L91), [`USE_BUNDLED_JQ`](https://github.com/falcosecurity/falco/blob/75b816d806d29bd47ace6b14a311c18dfc610d19/CMakeLists.txt#L120), ...) to inherit this setting. + +In case you prefer to have all of them dynamically linked, you can change the value of this option. + +But it's also possible to selectively declare which dependency have to be linked dynamically through the `USE_BUNDLED_*` environment variables to disable the default behavior. + +For example, suppose you do not want to use the bundled `jq` dependency but you prefer to link the `jq` dalready present in your system. +To achieve this goal you need to configure the build process passing the `USE_BUNDLED_JQ=False` as shown in more detail [here](#disable-a-bundled-dependency). + +These are all the dependencies for which you can disable the bundling mechanism. + +Each of these respects an option `USE_BUNDLED_` you can set to `False`. + +- b64 +- cares +- curl +- civetweb +- grpc +- jq +- libyaml +- lpeg +- luajit +- lyaml +- ncurses +- njson +- openssl +- protobuf +- tbb +- yamlcpp +- zlib + +Furthermore Falco also depends on the following libraries coming from the Sysdig repository: + +- libscap +- libsinsp + +## Obtain the source code + +First, make sure you have a working copy of the Falco source code along with a working copy of Sysdig to compile `libscap` and `libsinsp`. + +**Clone Falco** + +```bash +git clone https://github.com/falcosecurity/falco.git +``` + +**Clone Sysdig** + +```bash +git clone https://github.com/draios/sysdig.git +``` + +# Build Falco + +There are two supported ways to build Falco + +- [Build directly on host](#build-directly-on-host) +- [Build using a container](#build-using-falco-builder-container) + +## 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. + +1. Create the build directory and enter in it +2. 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 +3. Build using make + + +### Build all + +```bash +mkdir build +cd build +cmake -DSYSDIG_DIR=/path/to/sysdig .. # make sure to change the path to the directory where you cloned sysdig +make +``` + +You can also build only specific targets: + +### Build Falco only + +Do the build folder and cmake setup, then: + +```bash +make falco +``` + +### Build the Falco engine only + +Do the build folder and cmake setup, then: + +```bash +make falco_engine +``` + +### Build libscap only + +Do the build folder and cmake setup, then: + +```bash +make scap +``` + +### Build libsinsp only + +Do the build folder and cmake setup, then: + +```bash +make sinsp +``` + +### Build the kernel driver only + +Do the build folder and cmake setup, then: + +```bash +make driver +``` + +### 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 binary +- `driver/src/falco-probe.ko`: the Falco kernel driver +- `driver/bpf/probe.o`: if you built Falco with [BPF support](#enable-bpf-support) + +If you'd like to build a debug version, run cmake as `cmake -DCMAKE_BUILD_TYPE=Debug ..` instead, see the [CMake Options](#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 + +```bash +-DCMAKE_VERBOSE_MAKEFILE=On +``` + +#### Specify C and CXX compilers + +``` +-DCMAKE_C_COMPILER=$(which gcc) -DCMAKE_CXX_COMPILER=$(which g++) +``` + +#### Disable a bundled dependency + +``` +-DUSE_BUNDLED_JQ=False +``` + +Read more about Falco dependencies [here](#runtime-dependencies). + + +#### 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 +``` + +#### Specify the Falco version + +``` + -DFALCO_VERSION=0.15.0-dirty +``` + +#### Enable BPF support + +``` +-DBUILD_BPF=True +``` + +When enabling this you will be able to make the `bpf` target after: + +```bash +make bpf +``` ## Build using falco-builder container -One easy way to build falco is to run the [falco-builder](https://hub.docker.com/r/falcosecurity/falco-builder) container. It contains the reference toolchain we use to build packages. +An alternative way to build Falco is to run the [falco-builder](https://hub.docker.com/r/falcosecurity/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: @@ -30,85 +278,95 @@ FALCO_VERSION=0.1.2-test docker run --user $(id -u):$(id -g) -v /etc/passwd:/etc FALCO_VERSION=0.1.2-test docker run --user $(id -u):$(id -g) -v /etc/passwd:/etc/passwd:ro -e MAKE_JOBS=4 -e FALCO_VERSION=${FALCO_VERSION} -it -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-builder package ``` -The default value for FALCO_VERSION is `0.1.1dev`, so you can skip specifying FALCO_VERSION if you want. +The default value for `FALCO_VERSION` is `0.1.1dev`, so you can skip specifying `FALCO_VERSION` if you want. -### Test using falco-tester container -If you'd like to run the regression test suite against your build, you can use the [falco-tester](https://hub.docker.com/r/falcosecurity/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](http://avocado-framework.github.io/). +## Load latest falco-probe kernel module -It does build a new container image `falcosecurity/falco:test` to test the process of buillding and running a container with the falco packages built during the build step. +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. -The image depends on the following parameters: +Unload any existing kernel module via: -* `FALCO_VERSION`: The version of the falco package to include in the test container image. +```bash +rmmod falco_probe +``` -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: +To load the locally built version, assuming you are in the `build` dir, use: ```bash -docker run --user $(id -u):$(id -g) -v $HOME:$HOME:ro -v /boot:/boot:ro -v /var/run/docker.sock:/var/run/docker.sock -v /etc/passwd:/etc/passwd:ro -e FALCO_VERSION=${FALCO_VERSION} -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-tester +insmod driver/falco-probe.ko ``` -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). +```bash +rmmod falco_probe +``` -The default value for FALCO_VERSION is `0.1.1dev`, so you can skip specifying FALCO_VERSION if you want. +To load the locally built version, assuming you are in the `build` dir, use: -## Build directly on host +```bash +insmod driver/falco-probe.ko +``` -If you'd rather build directly on the host, you can use your local toolchain and cmake binaries. +# Run falco -Clone this repo in a directory that also contains the sysdig source repo. The result should be something like: +Once Falco is built and the kernel module is loaded, assuming you are in the `build` dir, you can run falco as: -``` -22:50 vagrant@vagrant-ubuntu-trusty-64:/sysdig -$ pwd -/sysdig -22:50 vagrant@vagrant-ubuntu-trusty-64:/sysdig -$ ls -l -total 20 -drwxr-xr-x 1 vagrant vagrant 238 Feb 21 21:44 falco -drwxr-xr-x 1 vagrant vagrant 646 Feb 21 17:41 sysdig +```bash +sudo ./userspace/falco/falco -c ../falco.yaml -r ../rules/falco_rules.yaml ``` -To build from the head of falco's dev branch, make sure you're also using the head of the sysdig dev branch. If you're building from a specific version of falco (say x.y.z), there will be a corresponding tag `falco/x.y.z` on the sysdig repository that you should use. +By default, falco logs events to standard error. -create a build dir, then setup cmake and run make from that dir: -```bash -mkdir build -cd build -cmake .. -make -``` +# Run regression tests -Afterward, you should have a falco executable in `build/userspace/falco/falco`. +## Test directly on host -If you'd like to build a debug version, run cmake as `cmake -DCMAKE_BUILD_TYPE=Debug ..` instead. +To run regression tests, after building Falco, in the Falco root directory, you need to run the `test/run_regression_tests.sh` script. -## Load latest falco-probe kernel module +### Dependencies -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. +You will need the following dependencies for the regression testing framework to work. -Unload any existing kernel module via: +- [Avocado Framework](https://github.com/avocado-framework/avocado) +- [Avocado Yaml to Mux plugin](https://avocado-framework.readthedocs.io/en/66.0/optional_plugins/varianter_yaml_to_mux.html) +- [JQ](https://github.com/stedolan/jq) +- The unzip command +- [Docker CE](https://docs.docker.com/install/) + +To install Avocado and its plugins, you can use pip: -```bash -rmmod falco_probe +``` +pip install avocado-framework avocado-framework-plugin-varianter-yaml-to-mux ``` -To load the locally built version, assuming you are in the `build` dir, use: +### Run the tests + +Change `$PWD/build` with the directory you built Falco in, if different. ```bash -insmod driver/falco-probe.ko +./test/run_regression_tests.sh $PWD/build ``` -## Running falco +## Test using falco-tester container + +If you'd like to run the regression test suite against your build, you can use the [falco-tester](https://hub.docker.com/r/falcosecurity/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](http://avocado-framework.github.io/). + +It does build a new container image `falcosecurity/falco:test` 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. -Assuming you are in the `build` dir, you can run falco as: +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: ```bash -sudo ./userspace/falco/falco -c ../falco.yaml -r ../rules/falco_rules.yaml +docker run --user $(id -u):$(id -g) -v $HOME:$HOME:ro -v /boot:/boot:ro -v /var/run/docker.sock:/var/run/docker.sock -v /etc/passwd:/etc/passwd:ro -e FALCO_VERSION=${FALCO_VERSION} -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-tester ``` -By default, falco logs events to standard error. +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). + +The default value for FALCO_VERSION is `0.1.1dev`, so you can skip specifying `FALCO_VERSION` if you want.