update systemd docs

content/en/docs/getting-started/running/index.md

@@ -4,54 +4,63 @@ description: Operating and Managing Falco
 weight: 4
 ---
 
+## Falco packages
 
-## Run Falco as a service
+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`.
 
-If you installed Falco by using [the DEB or the RPM](/docs/getting-started/installation) package, then falco systemd service was already started and enabled for you.  
-In case you wish to stop or disable it, issue:
+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.
 
-```console
-systemctl disable falco
-```
+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](/docs/getting-started/installation/#rule-update) 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.
 
-```console
-systemctl stop falco
-```
+3. Type `falco-driver-loader bpf` to download/compile the BPF probe.
 
-Then, to enable or start it back, you would need:
+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):
 
-```console
-systemctl enable falco
-```
+    ```text
+    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
+    ```
 
-```console
-systemctl start falco
-```
+5. If you want to stop both services in one shot
 
-You can also view the Falco logs using `journalctl`.
+    ```bash
+    systemctl stop falco-bpf.service
+    ```
 
-```console
-journalctl -fu falco
-```
+### Custom run
 
-## Run Falco manually
+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!
 
-If you'd like to run Falco by hand, you can find the full usage description for Falco by typing:
+## Falco binary
 
-```console
+Here you can find some examples of how to run Falco after having [installed](/docs/getting-started/installation/#falco-binary) it using the binary package
+
+
+```bash
+# Kernel module (default driver)
+falco
+# eBPF probe
+FALCO_BPF_PROBE="" falco
+# modern eBPF probe
+falco --modern-bpf
+# For more info see all available options
 falco --help
 ```
 
-{{% pageinfo color="primary" %}}
+{{% pageinfo color="warning" %}}
 
-Are you looking for userspace instrumentation? Please see [this page](/docs/event-sources/drivers/#userspace-instrumentation).
+If you are using the eBPF probe, in order to ensure that performance is not degraded, make sure that
 
-{{% /pageinfo %}}
+* 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`
 
+{{% /pageinfo %}}
 
-## Run within Docker {#docker}
 
+## Docker {#docker}
 
 {{% pageinfo color="primary" %}}
 
@@ -63,6 +72,7 @@ You can find instructions on how to install the kernel headers for your system u
 
 Falco ships a set of official [docker images](/docs/getting-started/download#images).
 The images can be used in two ways as follows:
+
 - [Least privileged (recommended)](#docker-least-privileged)
 - [Fully privileged](#docker-privileged)
 
@@ -90,11 +100,9 @@ Once the kernel module has been installed directly on the host system, it can be
         falcosecurity/falco-driver-loader:latest
     ```
 
-
 The `falcosecurity/falco-driver-loader` image just wraps the `falco-driver-loader` script.
 You can find more about its usage [here](/docs/getting-started/installation#install-driver)
 
-
 2. Run Falco in a container using Docker with the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege):
 
     ```shell
@@ -106,7 +114,6 @@ You can find more about its usage [here](/docs/getting-started/installation#inst
         falcosecurity/falco-no-driver:latest
     ```
 
-
 {{% pageinfo color="warning" %}}
 If you are running Falco on a system with the AppArmor LSM enabled (e.g Ubuntu), you will also need to pass `--security-opt apparmor:unconfined` to
 the `docker run` command above.
@@ -119,18 +126,19 @@ docker info | grep -i apparmor
 
 {{% /pageinfo %}}
 
-
 {{% pageinfo color="primary" %}}
 
 Note that `ls /dev/falco* | xargs -I {} echo --device {}` outputs a `--device /dev/falcoX` option per CPU (ie. just the devices created by the Falco's kernel module). Also, `-e HOST_ROOT=/` is necessary since with `--device` there is no way to remap devices to `/host/dev/`.
 
 {{% /pageinfo %}}
 
-To run Falco in least privileged mode with the eBPF driver, we list all the required capabilities: 
+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
+
     ```shell
     docker pull falcosecurity/falco-driver-loader:latest
     docker run --rm -i -t \
@@ -143,7 +151,9 @@ To run Falco in least privileged mode with the eBPF driver, we list all the requ
         -v /etc:/host/etc:ro \
         falcosecurity/falco-driver-loader:latest bpf
     ```
+
 2. Then, run Falco
+
     ```shell
     docker pull falcosecurity/falco-no-driver:latest
     docker run --rm -i -t \
@@ -161,9 +171,10 @@ To run Falco in least privileged mode with the eBPF driver, we list all the requ
 
 {{% pageinfo color="warning" %}}
 
-Again, you will need to add `--security-opt apparmor:unconfined` to the last command if your system has the AppArmor LSM enabled. 
+Again, you will need to add `--security-opt apparmor:unconfined` to the last command if your system has the AppArmor LSM enabled.
 
 {{% /pageinfo %}}
+
 ### Fully privileged {#docker-privileged}
 
 To run Falco in a container using Docker with full privileges use the following commands.
@@ -230,6 +241,7 @@ docker run --rm -i -t \
 ```
 
 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:
+
 ```shell
     -e FALCO_BPF_PROBE="" -v /root/.falco:/root/.falco \
 ```
@@ -240,6 +252,7 @@ Other configurable options:
 - `SKIP_DRIVER_LOADER` - Set this environment variable to avoid running `falco-driver-loader` 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.
 
 ```bash

content/en/docs/getting-started/upgrade.md

@@ -4,21 +4,26 @@ description: Upgrading Falco on a Linux system
 weight: 3
 ---
 
-This section provides upgrading paths for Falco if previously installed following the [Install](../installation/) section. 
+This section provides upgrading paths for Falco if previously installed following the [Install](../installation/) section.
 
-## Upgrading
-
-According to the installation method you chose, you first have to remove the active kernel module before upgrading Falco to the latest version:
+{{% pageinfo color="warning" %}}
+If you are using the kernel module, please remove it before upgrading Falco to avoid issues during the upgrade.
 
-```shell
+```bash
 rmmod falco
 ```
 
+{{% /pageinfo %}}
+
+## Falco packages
+
+Here there are no specific steps to follow, you just need to type the specific commands for your distro. Please remember to specify the `FALCO_FRONTEND=noninteractive` env variable if you don't want to use the `dialog` during the upgrade
+
 ### Debian/Ubuntu {#debian}
 
 {{% pageinfo color="warning" %}}
-If you configured the `apt` repository by having followed the instructions for Falco 0.27.0 or older, 
-you may need to update the repository URL:
+
+If you configured the `apt` repository by having followed the instructions for Falco 0.27.0 or older, you may need to update the repository URL, otherwise, **fell free to ignore this message**
 
 ```shell
 sed -i 's,https://dl.bintray.com/falcosecurity/deb,https://download.falco.org/packages/deb,' /etc/apt/sources.list.d/falcosecurity.list
@@ -30,7 +35,7 @@ Check in the `apt-get update` log that `https://download.falco.org/packages/deb`
 
 {{% /pageinfo %}}
 
-If you installed Falco by following the [provided instructions](../installation/#debian):
+If you installed Falco by following the [provided instructions](../installation/#installation-details):
 
 ```shell
 apt-get --only-upgrade install falco
@@ -39,8 +44,7 @@ apt-get --only-upgrade install falco
 ### CentOS/RHEL/Fedora/Amazon Linux {#centos-rhel}
 
 {{% pageinfo color="warning" %}}
-If you configured the `yum` repository by having followed the instructions for Falco 0.27.0 or older, 
-you may need to update the repository URL:
+If you configured the `yum` repository by having followed the instructions for Falco 0.27.0 or older, you may need to update the repository URL, otherwise, **fell free to ignore this message**
 
 ```shell
 sed -i 's,https://dl.bintray.com/falcosecurity/rpm,https://download.falco.org/packages/rpm,' /etc/yum.repos.d/falcosecurity.repo
@@ -52,25 +56,27 @@ Then check that the `falcosecurity-rpm` repository is pointing to `https://downl
 ```shell
 yum repolist -v falcosecurity-rpm
 ```
+
 {{% /pageinfo %}}
 
 If you installed Falco by following the [provided instructions](../installation/#centos-rhel):
 
 1. Check for updates:
+
     ```shell
     yum check-update
     ```
 
 2. If a newer Falco version is available:
+
     ```shell
     yum update falco
     ```
 
 ### openSUSE {#suse}
 
 {{% pageinfo color="warning" %}}
-If you configured the `zypper` repository by having followed the instructions for Falco 0.27.0 or older,
-you may need to update the repository URL:
+If you configured the `zypper` repository by having followed the instructions for Falco 0.27.0 or older, you may need to update the repository URL, otherwise, **fell free to ignore this message**
 
 ```shell
 sed -i 's,https://dl.bintray.com/falcosecurity/rpm,https://download.falco.org/packages/rpm,' /etc/zypp/repos.d/falcosecurity.repo
@@ -82,10 +88,15 @@ Then check that the `falcosecurity-rpm` repository is pointing to `https://downl
 ```shell
 zypper lr falcosecurity-rpm
 ```
+
 {{% /pageinfo %}}
 
 If you installed Falco by following the [provided instructions](../installation/#suse):
 
 ```shell
 zypper update falco
 ```
+
+## Falco binary
+
+For the Falco binary we don't provide specific update paths, you just have to remove files installed by the old `tar.gz` and download the new version of Falco as described [here](../installation/#falco-binary)