Install on a host (DEB, RPM)

There are two main methods to install Falco on your host using the released Falco packages:

1. RPM or DEB package (includes Systemd setup): This method is detailed on this page.
2. Tarball archive: For instructions, refer to the Install on a host (tarball) page.

Install

This installation method is for Linux distributions with a package manager that supports DEB (Debian, Ubuntu) or RPM (CentOS, RHEL, Fedora, Amazon Linux) packages.

In interactive installations, the Falco installation package uses the dialog binary for configuration prompts. The dialog allows the user to complete the Systemd setup which includes:

• The driver selection (kmod, ebpf, modern_ebpf) or automatic selection
• The Falcoctl service setup

In non-interactive installations (e.g., dialog is not available, or if the user disables it by setting FALCO_FRONTEND=noninteractive when installing Falco using the package manager), the automatic driver selection is enabled by default and for other options, the user needs to manually configure the Systemd services.

Env variables

The following environment variables can be used to customize the installation process:

• FALCO_FRONTEND: Set to noninteractive to disable the dialog prompts. The default is dialog.
• FALCO_DRIVER_CHOICE: Set to kmod, ebpf, or modern_ebpf to choose a driver; set to none to disable service installation. If one of the previous option is selected, the dialog will be skipped too. The default (empty) is automatic selection.
• FALCOCTL_ENABLED: Set to no to disable the automatic rules update provided by falcoctl. The default (empty) or any value other than no will keep the option enabled.

These environment variables can be used in conjunction with the package manager (as described in the following sections) to customize the installation process as needed.

Examples:

• No dialog, no driver, no automatic rules update:

  FALCO_DRIVER_CHOICE=none apt-get install -y falco
  

  Copy

• Install with kmod driver and automatic rules update:

  FALCO_DRIVER_CHOICE=kmod apt-get install -y falco
  

  Copy

• No dialog, automatic selection and automatic rules update:

  FALCO_FRONTEND=noninteractive apt-get install -y falco
  

  Copy

• No dialog, automatic selection and no automatic rules update:

  FALCO_FRONTEND=noninteractive FALCOCTL_ENABLED=no apt-get install -y falco
  

  Copy

apt (Debian/Ubuntu)

The following steps are for Debian and Debian-based distributions, such as Ubuntu, which use the apt package manager.

1. Trust the falcosecurity GPG key

   curl -fsSL https://falco.org/repo/falcosecurity-packages.asc | \
   sudo gpg --dearmor -o /usr/share/keyrings/falco-archive-keyring.gpg
   

   Copy

2. Configure the apt repository

   echo "deb [signed-by=/usr/share/keyrings/falco-archive-keyring.gpg] https://download.falco.org/packages/deb stable main" | \
   sudo tee -a /etc/apt/sources.list.d/falcosecurity.list
   

   Copy

sudo apt-get install apt-transport-https

3. Update the package list

   sudo apt-get update -y
   

   Copy

4. Install some required dependencies that are needed to build the Kernel Module and the eBPF probe

   Note: You don't need to install these dependencies if you want to use the Modern eBPF.

   sudo apt install -y dkms make linux-headers-$(uname -r)
   # If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
   sudo apt install -y clang llvm
   # You can install also the dialog package if you want it
   sudo apt install -y dialog
   

   Copy

5. Install the Falco package

   sudo apt-get install -y falco
   

   Copy

yum (CentOS/RHEL/Fedora/Amazon Linux)

1. Trust the falcosecurity GPG key

   rpm --import https://falco.org/repo/falcosecurity-packages.asc
   

   Copy

2. Configure the yum repository

   curl -s -o /etc/yum.repos.d/falcosecurity.repo https://falco.org/repo/falcosecurity-rpm.repo
   

   Copy

3. Update the package list

   yum update -y
   

   Copy

4. Install some required dependencies that are needed to build the Kernel Module and the eBPF probe

   Note: You don't need to install these dependencies if you want to use the Modern eBPF.

   # If necessary install it using: `yum install epel-release` (or `amazon-linux-extras install epel` in case of amzn2), then `yum install make dkms`.
   yum install -y dkms make
   # If the package was not found by the below command, you might need to run `yum distro-sync` in order to fix it. Rebooting the system may be required.
   yum install -y kernel-devel-$(uname -r)
   # If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
   yum install -y clang llvm
   # You can install also the dialog package if you want it
   yum install -y dialog
   

   Copy

5. Install the Falco package

   yum install -y falco
   

   Copy

zypper (openSUSE)

1. Trust the falcosecurity GPG key

   rpm --import https://falco.org/repo/falcosecurity-packages.asc
   

   Copy

2. Configure the zypper repository

   curl -s -o /etc/zypp/repos.d/falcosecurity.repo https://falco.org/repo/falcosecurity-rpm.repo
   

   Copy

3. Update the package list

   zypper -n update
   

   Copy

4. Install some required dependencies that are needed to build the Kernel Module and the eBPF probe

   Note: You don't need to install these dependencies if you want to use the Modern eBPF.

   zypper -n install dkms make
   # If the package was not found by the below command, you might need to run `zypper -n dist-upgrade` in order to fix it. Rebooting the system may be required.
   zypper -n install kernel-default-devel-$(uname -r | sed s/\-default//g)
   # If you use falcoctl driver loader to build the eBPF probe locally you need also clang toolchain
   zypper -n install clang llvm
   # You can install also the dialog package if you want it
   zypper -n install dialog
   

   Copy

5. Install Falco:

   zypper -n install falco
   

   Copy

6. Uninstall Falco:

   zypper rm falco
   

   Copy

Systemd setup

Setup with dialog

By default, if you have the dialog binary installed on your system, you will be prompted with this:

From here you can choose one of our 3 drivers Kmod, eBPF, Modern eBPF, a Manual configuration or the Automatic selection (recommended) to trigger the automatic logic to select the best driver for you. When you choose a driver from the dialog, the systemd service is always enabled by default so it will start at every system reboot. If you want to disable this behavior type systemctl disable falco-kmod.service (if you are using the kernel module like in this example).

After the first dialog, you should see a second one:

If you choose Yes, falcoctl will periodically check for ruleset updates and, if a new update is available, will pull and install it.

Manual configuration

If you chose Manual configuration from the dialog, you need to complete the setup configuration.

First, let's verify the available services:

$ sudo systemctl list-unit-files "falco*"

UNIT FILE                        STATE    PRESET 
falco-bpf.service                disabled enabled
falco-custom.service             disabled enabled
falco-kmod-inject.service        static   enabled
falco-kmod.service               disabled enabled
falco-modern-bpf.service         disabled enabled
falcoctl-artifact-follow.service disabled enabled

Using the systemctl command, you can now enable the desired unit to start at boot time.

Let's say you want to enable the modern eBPF probe:

$ sudo systemctl enable falco-modern-bpf.service
Created symlink /etc/systemd/system/falco.service → /usr/lib/systemd/system/falco-modern-bpf.service.
Created symlink /etc/systemd/system/multi-user.target.wants/falco-modern-bpf.service → /usr/lib/systemd/system/falco-modern-bpf.service.

$ sudo systemctl list-unit-files "falco*"

UNIT FILE                        STATE    PRESET 
falco-bpf.service                disabled enabled
falco-custom.service             disabled enabled
falco-kmod-inject.service        static   -      
falco-kmod.service               disabled enabled
falco-modern-bpf.service         enabled  enabled
falco.service                    alias    -      
falcoctl-artifact-follow.service disabled enabled

Or you'd like to switch to using the kernel module:

$ sudo systemctl disable falco-modern-bpf.service
Removed "/etc/systemd/system/multi-user.target.wants/falco-modern-bpf.service".
Removed "/etc/systemd/system/falco.service".

$ sudo systemctl enable falco-kmod.service
Created symlink /etc/systemd/system/falco.service → /usr/lib/systemd/system/falco-kmod.service.
Created symlink /etc/systemd/system/multi-user.target.wants/falco-kmod.service → /usr/lib/systemd/system/falco-kmod.service.

$ sudo systemctl list-unit-files "falco*"

UNIT FILE                        STATE    PRESET 
falco-bpf.service                disabled enabled
falco-custom.service             disabled enabled
falco-kmod-inject.service        static   -      
falco-kmod.service               enabled  enabled
falco-modern-bpf.service         disabled enabled
falco.service                    alias    -      
falcoctl-artifact-follow.service disabled enabled

7 unit files listed.

As you can see, enabling the falco-kmod.service, falco-modern-bpf.service or falco-custom.service also creates a new alias/service called falco.service that can be used in place of the aliased ones.

As a side note, if you prefer not to use the falcoctl tool to automatically update your rules, you can mask it as follows. Otherwise, as explained here, Falco will enable it too.

$ sudo systemctl mask falcoctl-artifact-follow.service
Created symlink /etc/systemd/system/falcoctl-artifact-follow.service → /dev/null.

Configuring services

If you installed the Falco packages using the dialog option, all your services should already be up and running. However, if you chose the Manual configuration option, you need to configure the services manually.

If you need to switch from one service to another, ensure that the current service is properly stopped before starting the new one. This can be done by using the appropriate service management commands for your system (e.g., systemctl stop <service_name> and systemctl start <new_service_name>).

For example, if you want to use the service for the eBPF probe:

1. Type systemctl list-units | grep falco to check that no unit is running. Stop the current services, if any.

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. 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 probe, 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
   

   Copy

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

   systemctl stop falco-bpf.service
   

   Copy

Falcoctl service (automatic rules update)

If this service is enabled (as default), typing systemctl list-units | grep falco you should see something similar to this:

falco-kmod-inject.service                         loaded active exited    Falco: Container Native Runtime Security with kmod, inject.
falco-kmod.service                                loaded active running   Falco: Container Native Runtime Security with kmod
falcoctl-artifact-follow.service                  loaded active running   Falcoctl Artifact Follow: automatic artifacts update service

• falco-kmod-inject.service injects the kernel module and exits. This unit remains after exit to detach the kernel module when the falco-kmod.service will be stopped.
• falco-kmod.service instance of Falco running the kernel module.
• falcoctl-artifact-follow.service instance of Falcoctl that searches for new rulesets. This unit will be stopped when falco-kmod.service terminates.

The Falcoctl service is strictly related to the Falco one:

• when the Falco service starts it searches for a unit called falcoctl-artifact-follow.service and if present it starts it. Please note that following this pattern, if you enable the Falco service and you reboot your system, Falcoctl will start again with Falco even if you don't enable it through systemd enable! You can disable this behavior by stopping the Falcoctl service and masking it systemctl mask falcoctl-artifact-follow.service.
• when the Falco service stops also the Falcoctl service is stopped.

In case the Falcoctl service is not enabled, the Falco package will only start the falco-kmod.service. Typing systemctl list-units | grep falco you should see something similar to this:

falco-kmod-inject.service                         loaded active exited    Falco: Container Native Runtime Security with kmod, inject.
falco-kmod.service                                loaded active running   Falco: Container Native Runtime Security with kmod

In this mode, the Falcoctl service is masked by default so if you want to enable it in a second step you need to type systemctl unmask falcoctl-artifact-follow.service.

Custom service

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!

Configuration

The Falco configuration file is located at /etc/falco/falco.yaml. You can edit it to customize Falco's behavior.

Since Falco 0.38.0, a new config key, config_files, allows the user to load additional configuration files to override main config entries. This allows user to keep local customization between Falco upgrades. Its default value points to a new folder, /etc/falco/config.d/ that gets installed by Falco and will be processed to look for local configuration files.

Hot Reload

By default, with the watch_config_files configuration option enabled, Falco automatically monitors changes to configuration and rule files. When these files are modified, Falco will automatically reload the updated configuration without requiring a restart.

If this option is disabled, you can manually restart the Falco systemd service to apply the changes:

systemctl restart falco

Upgrade

apt (Debian/Ubuntu)

sed -i 's,https://dl.bintray.com/falcosecurity/deb,https://download.falco.org/packages/deb,' /etc/apt/sources.list.d/falcosecurity.list
apt-get clean
apt-get -y update

If you installed Falco by following the provided instructions:

apt-get --only-upgrade install falco

yum (CentOS/RHEL/Fedora/Amazon Linux)

sed -i 's,https://dl.bintray.com/falcosecurity/rpm,https://download.falco.org/packages/rpm,' /etc/yum.repos.d/falcosecurity.repo
yum clean all

yum repolist -v falcosecurity-rpm

If you installed Falco by following the provided instructions:

1. Check for updates:

   yum check-update
   

   Copy

2. If a newer Falco version is available:

   yum update falco
   

   Copy

zypper (openSUSE)

sed -i 's,https://dl.bintray.com/falcosecurity/rpm,https://download.falco.org/packages/rpm,' /etc/zypp/repos.d/falcosecurity.repo
zypper refresh

zypper lr falcosecurity-rpm

If you installed Falco by following the provided instructions:

zypper update falco

Kernel Upgrades

When performing kernel upgrades on your host, a reboot is required. When using a eBPF probe or a Kernel Module driver, the Falco driver loader (i.e., falcoctl driver) should be able to automatically find a pre-built driver (or build it on the fly) corresponding to the updated kernel release (uname -r), making it easy to handle kernel upgrades. The Falco Project features a kernel crawler and automated CI, ensuring you can always obtain the necessary pre-built driver artifact, even for the latest kernel releases we support.

Uninstall

apt (Debian/Ubuntu)

apt-get --purge autoremove falco

yum (CentOS/RHEL/Fedora/Amazon Linux)

yum autoremove falco

zypper (openSUSE)

zypper remove falco

Package signing

Most Falco packages available at download.falco.org are provided with a detached signature that can be used to verify that the package information downloaded from the remote repository can be trusted.

The latest trusted public GPG key used for packages signing can be downloaded from falco.org/repo/falcosecurity-packages.asc. The following table lists all the keys employed by the organization currently and in the past, including the revoked ones. We recommend updating the revoked keys to download their revocation certificate, and eventually removing them from your package verification system due to the signature made with them not being trustable anymore.

Troubleshooting

This section aims to offer further guidance when something doesn't go as expected in the installation of Falco.

Unable to find a prebuilt driver

• ERROR failed: unable to find a prebuilt driver

This error message appears when the falcoctl driver loader tool, which looks for the Falco driver and loads it in memory, is not able to find a pre-built driver, neither as an eBPF probe nor as a kernel module, at the [Falco driver repository] (https://download.falco.org).

This means that there's no prebuilt driver available for the kernel running on the machine where Falco is going to be installed.

However, you can add your kernel release version to the build grid the pipeline refers to building the drivers. Follow this tutorial to contribute the required configuration.

Enable the BPF JIT Compiler

If you are using the eBPF probe, in order to ensure that performance is not degraded, make sure that:

• Your kernel has CONFIG_BPF_JIT enabled
• net.core.bpf_jit_enable is set to 1 (enable the BPF JIT Compiler)

This can be verified via sysctl -n net.core.bpf_jit_enable.