Running

Falco packages

If you installed the Falco packages using the dialog all your services should be already up and running, while if you chose the Manual configuration or if you used the FALCO_FRONTEND=noninteractive env variable you have to configure services by your hand. Here we show a simple example with the eBPF probe.

Let's imagine we want to start the falco-bpf.service.

1. Type systemctl list-units | grep falco to check that no unit is running.

2. Now you have to decide whether you want the Falcoctl service running together with the Falco one. If yes you don't have to do anything, else you will need to mask the Falcoctl service with systemctl mask falcoctl-artifact-follow.service. As pointed out in this section the Falcoctl service is strictly related to the Falco one so if you don't mask it, it will be started together with the Falco service.

3. Type falcoctl driver config --type ebpf to configure Falco to use eBPF driver, then falcoctl driver install to download/compile the eBPF probe.

4. Now running systemctl start falco-bpf.service and typing systemctl list-units | grep falco you should see something like that (supposing you didn't mask the Falcoctl service):

   falco-bpf.service                                 loaded active running   Falco: Container Native Runtime Security with ebpf
   falcoctl-artifact-follow.service                  loaded active running   Falcoctl Artifact Follow: automatic artifacts update service
   

5. If you want to stop both services in one shot

   systemctl stop falco-bpf.service
   

Automatic driver selection

Please note that since Falco 0.38.0, its packages will leverage a falcoctl driver-loader feature to autodetect the best driver to be used by the system. The algorithm will try to use the modern_ebpf driver wherever it is supported, falling back at other drivers where needed features are not available.

Custom run

You may have noticed a Falco unit called falco-custom.service. You should use it when you want to run Falco with a custom configuration like a plugin or Gvisor. Please note that in this case you have to modify this template according to how you want to run Falco, the unit should not be used as is!

Falco binary

Since Falco 0.38.0, the default configured driver is modern_ebpf; if you are willing to change it, here you can find some examples of how to run Falco after having installed it using the binary package

# Default driver as set in the Falco config file
falco
# Force eBPF probe
falco -o engine.kind=ebpf
# Force kernel module
falco -o engine.kind=kmod
# For more info see all available options
falco --help

Docker

To learn how to run Falco from a container in a Kubernetes setting, checkout the Deployment guide next.

Falco ships a set of official docker images. The images can be used in two ways as follows:

• Least privileged (recommended)
• Fully privileged

Least privileged (recommended)

This is how the Falco userspace process can be ran in a container.

Modern eBPF

The following capabilities should be enough to run Falco with the Modern eBPF probe:

• CAP_SYS_PTRACE
• CAP_SYS_RESOURCE
• CAP_BPF
• CAP_PERFMON

Here we have the docker command to run with the modern probe.

docker run --rm -i -t \
           --cap-drop all \
           --cap-add sys_admin \
           --cap-add sys_resource \
           --cap-add sys_ptrace \
           -v /var/run/docker.sock:/host/var/run/docker.sock \
           -v /proc:/host/proc:ro \
           -v /etc:/host/etc:ro \
           falcosecurity/falco-no-driver:latest

Note: in the command we use CAP_SYS_ADMIN because docker doesn't support CAP_BPF and CAP_PERFMON yet

Kernel module

Once the kernel module has been installed directly on the host system, it can be used from within a container.

1. Install the kernel module:

   • You can use an official installation method directly on the host
   • Alternatively, you can temporarily use a privileged container to install the driver on the host:

   docker pull falcosecurity/falco-driver-loader:latest
   docker run --rm -i -t \
       --privileged \
       -v /root/.falco:/root/.falco \
       -v /proc:/host/proc:ro \
       -v /boot:/host/boot:ro \
       -v /lib/modules:/host/lib/modules \
       -v /usr:/host/usr:ro \
       -v /etc:/host/etc:ro \
       falcosecurity/falco-driver-loader:latest kmod
   

The falcosecurity/falco-driver-loader image just wraps the falcoctl driver-loader tool. You can find more about its usage here

2. Run Falco in a container using Docker with the principle of least privilege:

   docker pull falcosecurity/falco-no-driver:latest
   docker run --rm -i -t \
       -e HOST_ROOT=/ \
       --cap-add SYS_PTRACE --pid=host $(ls /dev/falco* | xargs -I {} echo --device {}) \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v /etc:/host/etc:ro \
       falcosecurity/falco-no-driver:latest falco -o engine.kind=kmod
   

docker info | grep -i apparmor

eBPF

To run Falco in least privileged mode with the eBPF driver, we list all the required capabilities:

• on kernels <5.8, Falco requires CAP_SYS_ADMIN, CAP_SYS_RESOURCE and CAP_SYS_PTRACE
• on kernels >=5.8, CAP_BPF and CAP_PERFMON were separated out of CAP_SYS_ADMIN, so the required capabilities are CAP_BPF, CAP_PERFMON, CAP_SYS_RESOURCE, CAP_SYS_PTRACE. Unfortunately, Docker does not yet support adding the two newly introduced capabilities with the --cap-add option. For this reason, we continue using CAP_SYS_ADMIN, given that it still allows performing the same operations granted by CAP_BPF and CAP_PERFMON. In the near future, Docker will support adding these two capabilities and we will be able to replace CAP_SYS_ADMIN.

1. Install the eBPF probe

   docker pull falcosecurity/falco-driver-loader:latest
   docker run --rm -i -t \
       --privileged \
       -v /root/.falco:/root/.falco \
       -v /proc:/host/proc:ro \
       -v /boot:/host/boot:ro \
       -v /lib/modules:/host/lib/modules:ro \
       -v /usr:/host/usr:ro \
       -v /etc:/host/etc:ro \
       falcosecurity/falco-driver-loader:latest ebpf
   

2. Then, run Falco

   docker pull falcosecurity/falco-no-driver:latest
   docker run --rm -i -t \
       --cap-drop all \
       --cap-add sys_admin \
       --cap-add sys_resource \
       --cap-add sys_ptrace \
       -v /var/run/docker.sock:/host/var/run/docker.sock \
       -v /root/.falco:/root/.falco \
       -v /etc:/host/etc \
       -v /proc:/host/proc:ro \
       falcosecurity/falco-no-driver:latest falco -o engine.kind=ebpf
   
   # Please remember to add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above docker command
   # if you are running a kernel version < 4.14
   

Fully privileged

To run Falco in a container using Docker with full privileges use the following commands.

Modern eBPF

The modern eBPF is bundled into Falco therefore the falco-no-driver image is enough. This allows you to run Falco without dependencies, just the following command:

docker run --rm -i -t \
           --privileged \
           -v /var/run/docker.sock:/host/var/run/docker.sock \
           -v /proc:/host/proc:ro \
           -v /etc:/host/etc:ro \
           falcosecurity/falco-no-driver:latest

Kernel module

If you want to use Falco with the Kernel module driver:

docker pull falcosecurity/falco:latest
docker run --rm -i -t \
    --privileged \
    -v /var/run/docker.sock:/host/var/run/docker.sock \
    -v /dev:/host/dev \
    -v /proc:/host/proc:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules:ro \
    -v /usr:/host/usr:ro \
    -v /etc:/host/etc:ro \
    falcosecurity/falco:latest falco -o engine.kind=kmod

eBPF

Alternatively, you can use the eBPF probe driver:

docker pull falcosecurity/falco:latest
docker run --rm -i -t \
    --privileged \
    -e FALCO_DRIVER_LOADER_OPTIONS="ebpf" \
    -v /var/run/docker.sock:/host/var/run/docker.sock \
    -v /proc:/host/proc:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules:ro \
    -v /usr:/host/usr:ro \
    -v /etc:/host/etc:ro \
    falcosecurity/falco:latest falco -o engine.kind=ebpf

# Please remember to add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above docker command
# if you are running a kernel version < 4.14

It is also possible to use falco-no-driver and falco-driver-loader images in fully privileged mode. This may be desirable in environments which do not allow the full Falco image due to space, resource, security or policy constraints. You can load the eBPF probe or kernel module in its own temporary container as below:

docker pull falcosecurity/falco-driver-loader:latest
docker run --rm -i -t \
    --privileged \
    -v /dev:/host/dev \
    -v /proc:/host/proc:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules:ro \
    -v /usr:/host/usr:ro \
    -v /etc:/host/etc:ro \
    falcosecurity/falco-driver-loader:latest kmod

Once this has been done, or if you have installed the driver on the host permanently via the falcoctl driver tool instead of the Docker image, then you can simply load up the falco-no-driver image in privileged mode:

docker pull falcosecurity/falco-no-driver:latest
docker run --rm -i -t \
    --privileged \
    -v /var/run/docker.sock:/host/var/run/docker.sock \
    -v /dev:/host/dev \
    -v /proc:/host/proc:ro \
    -v /etc:/host/etc:ro \
    falcosecurity/falco-no-driver:latest falco -o engine.kind=kmod

To use falco-no-driver and falco-driver-loader with the eBPF probe you have to remove the -v /dev:/host/dev (which is only required by the Kernel Module) and add:

    -v /root/.falco:/root/.falco \

Plus, using -o engine.kind=ebpf Falco command line option.

Other configurable options:

• FALCOCTL_DRIVER_REPOS - See the Installing the driver section.
• SKIP_DRIVER_LOADER - Set this environment variable to avoid running falcoctl driver tool when the falcosecurity/falco image starts. Useful when the driver has been already installed on the host by other means.

Rules validation

It's possible to validate Falco rules without installation by using the Docker image.

export RULES_PATH=<PATH_TO_YOUR_RULES_HERE>
docker run --rm \
    -v ${RULES_PATH}:/etc/falco/my-rules \
    falcosecurity/falco:latest /usr/bin/falco \
    -r /etc/falco/falco_rules.yaml \
    -r /etc/falco/my-rules \
    -L

Hot Reload

This will reload the Falco configuration and restart the engine without killing the pid. This is useful to propagate new config changes without killing the daemon.

kill -1 $(cat /var/run/falco.pid)

Moreover, since Falco 0.32.0, watch_config_files config option drives the automatic reload of Falco when either the config or the ruleset change.