Airgapped Agent Installation

Airgapped environments are those that do not have network access to the public internet.

At startup, the agent will try to compile its own version of the probes, provided kernel header packages are installed on the host. Failing that, the agent will try to download pre-compiled probes, sysdigcloud-probe-<suffix>.ko or sysdigcloud-probe-bpf-<suffix>.o, from the Sysdig download site over the internet.

In an airgapped environemnt, you cannot download these artifacts. Therefore, before installing the agent, you will have to compile sysdigcloud-probe-<suffix> for each kernel version in your environment, and make it available to the installed agents through an internally accessible URL.

Prerequisites

  • A machine with internet access where you can download the required artifacts
  • A machine in your airgapped environment where you can build your probes
  • Tool to transfer artifacts to the machine in your airgapped environment
  • Docker installed

Overview

Sysdig provides a tool, named the probe builder, to help you build the probes for different kernels and for a specific agent version. After downloading the required artifacts on a machine connected to the internet, you can copy them to an airgapped host, build your own probes, and make them available to your agent installations.

On a Machine with Internet Connectivity

Prepare the Sysdig Probe Builder Images

On a machine with internet connectivity, build the Sysdig probe builder container images and create a tar file of the images.

  1. Get the probe builder source code from the repository:

    $ git clone https://github.com/draios/probe-builder
    
  2. Build the container image for the probe builder:

    $ docker build -t airgap/sysdig-probe-builder probe-builder/
    
  3. Build the images for each supported distribution-compiler combination:

    $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock airgap/sysdig-probe-builder:latest -P -b airgap/
    

    Running this command will create a different image tag for each supported combination of distribution-compiler, with the distro-compiler information suffixed to the image name, airgap/sysdig-probe-builder. For example, airgap/sysdig-probe-builder:centos-gcc4.8.

  4. Save all the above images to a tar archive:

    $ docker save airgap/sysdig-probe-builder | gzip > builders.tar.gz
    
  5. (optional) If you are building probes for the Ubuntu kernels, you will also need an ubuntu:latest image on your airgapped host. You can build it as follows:

    $ docker pull ubuntu
    $ docker save ubuntu | gzip > ubuntu.tar.gz
    

Download the Kernel Packages

Download your kernel packages. For more information, see Download Kernel Packages.

Download Probe Source Code

You need to download the probe source code for a specific agent version you want to build your probes for.

For example, for agent version 12.0.0 you would use:

$ git clone https://github.com/draios/agent-libs
$ cd agent-libs
$ git archive agent/12.0.0 --prefix sysdig/ | gzip > sysdig.tar.gz

Transfer the Downloaded Files

Copy the artifacts you have built to the airgapped host machine:

  • builders.tar.gz
  • ubuntu.tar.gz (if needed, see above)
  • sysdig.tar.gz
  • Kernel packages

On the Airgapped Host

Load the Builder Images

$ zcat builders.tar.gz | docker load

Unpack the Sysdig Source

$ tar xzf sysdig.tar.gz

Running this command will create the sysdig/ directory in the current directory.

Move the Kernel Packages to a Dedicated Location

Make sure you have all the downloaded kernel package artifacts in a single directory, /directory-containing-kernel-packages/, for each distribution you want to support.

Run the Probe Builder

Now that you have all your requirements in place, you can run the main probe builder:

$ docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /a-directory-with-some-free-space/:/workspace \
  -v /wherever-you-unpacked/sysdig/:/sysdig \
  -v /directory-containing-kernel-packages/:/kernels \
  airgap/sysdig-probe-builder:latest -B -b airgap/ -- \
  -p sysdigcloud-probe -v 12.0.0 -k CustomCentOS

The probes will appear in /a-directory-with-some-free-space/output. That directory can be served over HTTP and the URL to the server used as SYSDIG_PROBE_URL when loading the module (e.g. agent-kmodule container). As an example, the following sections describe how you can deploy your own nginx server within your cluster and upload your probes there.

Serve Your Pre-Compiled Probes

Set up a local repository to host the pre-compiled kernel module. Here is an example with nginx:

$ docker run --rm -v /a-directory-with-some-free-space/output:/usr/share/nginx/html/stable/sysdig-probe-binaries -p 80:80 nginx

Note down the URL and use it as the SYSDIG_PROBE_URL while installing the agent.

​ See Run the Probe Builder.

Run the Probe Builder

$ docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /sysdigcloud-probe/:/workspace \
  -v /wherever-you-unpacked/sysdig/:/sysdig \
  -v /directory-containing-kernel-packages/:/kernels \
  airgap/sysdig-probe-builder:latest -B -b airgap/ -- \
  -p sysdigcloud-probe -v 12.0.0 -k CustomCentOS

The probes will appear in /sysdigcloud-probe/output. This directory can be served over HTTP and the URL to the server used as SYSDIG_PROBE_URL when loading the module. For example, agent-kmodule container.

Install Agent in a Docker Environment

  1. Install Sysdig agent by pointing SYSDIG_PROBE_URL to the local repository:

    For docker-based installations:

    $ docker run -d --name sysdig-agent --restart always --privileged --net host --pid host -e ACCESS_KEY=WWWWW-YYYY-XXXX-ZZZZ-123456789 -e SECURE=true -e SYSDIG_PROBE_URL=http://www.mywebserver.net:80/ -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 --shm-size=512m sysdig/agent
    

    Where -e SYSDIG_PROBE_URL=http://www.mywebserver:80/ is the local nginx web server with the loaded module.

    Note: To use HTTPS communication with a self-signed or untrusted certificate, use the -e SYSDIG_PROBE_INSECURE_DOWNLOAD=true environment variable in the above command.

  2. Check the agent log. If the installation is successful, you will see a message as follows:

    Evaluating override of environment variables
    
    Trying to download precompiled module from http://mywebserver:80/stable/sysdig-probe-binaries/sysdigcloud-probe-<version>
    
    Download succeeded
    
  3. Continue with the instructions in Agent Install: Non-Orchestrated.

Install Agent in a Kubernetes Environment

  1. Open your agent daemonset and update the SYSDIG_PROBE_URL to point to the local repository:

    - name: SYSDIG_PROBE_URL
      value: http://www.mywebserver:80/
    

    If you would like to use secure communication with a self-signed or untrusted certificate, apply the SYSDIG_PROBE_INSECURE_DOWNLOAD environment variable.

    - name: SYSDIG_PROBE_INSECURE_DOWNLOAD
      value: true
    
  2. Continue with the instructions in Agent Install: Kubernetes.