Agent Install: Non-Orchestrated

This section describes how to install the Sysdig agent directly on a Linux host, without using an orchestrator, such as Kubernetes or Mesos.

The agent can be installed in two ways:

  • As a standard container

  • As a non-containerized service

The steps for each flavor differ slightly depending on whether you are using the SaaS or on-premises version of the Sysdig platform.

If you are installing the Sysdig agent in an environment that has Kubernetes, use the Agent Install: Kubernetes instructions instead.

Prerequisites

  • See Agent Installation Requirements for information on the following:

    • Supported Linux distributions

    • Network connection

    • Sysdig access key

    • Cloud service providers (AWS, Google, and Microsoft Azure) and any steps you may need to configure to integrate the Sysdig agent.

On kernel headers: The Sysdig agent requires kernel header files in order to install successfully on a host, and the agent is delivered with precompiled headers. If the hosts in your environment match the kernel versions included with the agent, no special action is needed.

In some cases, the host(s) in your environment may use Unix versions that do not match the provided headers, and the agent may fail to install correctly. In those cases, you must install the kernel headers manually. See About Kernel Headers and the Kernel Module for details.

  • Run any commands as root or with the sudo command.

  • Have your Sysdig access key on hand.

    If you launch an agent install from www.sysdig.com, the welcome wizard will present an access key.

Installing Agent Using Containers

The Sysdig agent can be deployed as a Docker container.

The commands below can also be copied from the Get Started page. In that case, your access key will already be included in the command automatically.

SaaS

Installing As Two Containers

The agent is installed by running sysdig/agent-kmodule, followed by running sysdig/agent-slim.

Every host restart requires subsequent running of agent-kmodule and agent-slim containers.

  1. Collect the following configuration parameters:

    • ACCESS_KEY: The agent access key. You can retrieve this from Settings > Agent Installation in either Sysdig Monitor or Sysdig Secure.
    • COLLECTOR: Use the address for your region.
    • TAGS: The list of tags for the host where the agent is installed. For example: role:webserver, location:europe, role:webserver
    • SYSDIG_BPF_PROBE: The path to the probe file that is either built or downloaded.
  2. Build and load the kernel module:

    If you are not using eBPF, use the following:

    docker run -it --privileged --rm --name sysdig-agent-kmodule \
    -v /usr:/host/usr:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules \
    quay.io/sysdig/agent-kmodule
    

    If you are using eBPF use the following:

    docker run -it --privileged --rm --name sysdig-agent-kmodule \
    -e SYSDIG_BPF_PROBE="" \
    -v /etc/os-release:/host/etc/os-release:ro \
    -v /root/.sysdig:/root/.sysdig \
    -v /usr:/host/usr:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules:ro \
    quay.io/sysdig/agent-kmodule
    
  3. Configure kernel module to load during system boot.

    If you are not using eBPF, use the following commands to configure the Linux system to automatically load the kernel module during system boot.

    $ sudo mkdir -p /etc/modules-load.d
    $ sudo bash -c "echo sysdigcloud-probe > /etc/modules-load.d/sysdigcloud-probe.conf"
    
    
  4. Run the agent module providing the access key and, optionally, user-defined tags:

    If you are not using eBPF, use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host \
    -e ACCESS_KEY=[ACCESS_KEY] \
    -e COLLECTOR=[COLLECTOR_ADDRESS] \
    [-e TAGS=[TAGS]]
    -v /var/run/docker.sock:/host/var/run/docker.sock \
    -v /dev:/host/dev \
    -v /proc:/host/proc:ro \
    -v /boot:/host/boot:ro \
    --shm-size=512m \
    quay.io/sysdig/agent-slim
    

    If you are using eBPF use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host\
    -e ACCESS_KEY=[ACCESS_KEY] \
    -e COLLECTOR=[COLLECTOR_ADDRESS] \
    [-e TAGS=[TAGS]]
    -e SYSDIG_BPF_PROBE="" \
    -v /sys/kernel/debug:/sys/kernel/debug:ro \
    -v /root/.sysdig:/root/.sysdig \
    -v /var/run/docker.sock:/host/var/run/docker.sock \
    -v /dev:/host/dev \
    -v /proc:/host/proc:ro \
    -v /boot:/host/boot:ro \
    --shm-size=512m \
    quay.io/sysdig/agent-slim
    

Installing As Single Container (Legacy)

  1. Collect the following configuration parameters:

    • ACCESS_KEY: The agent access key. You can retrieve this from Settings > Agent Installation in either Sysdig Monitor or Sysdig Secure.
    • COLLECTOR: Use the address for your region.
    • TAGS: The list of tags for the host where the agent is installed. For example: role:webserver, location:europe, role:webserver
    • SYSDIG_BPF_PROBE: The path to the probe file that was either built or downloaded.
  2. Run the agent container providing the access key and, optionally, user-defined tags:

    If you are not using eBPF, use the following:

    If you are not using eBPF, use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host\
     -e ACCESS_KEY=[ACCESS_KEY] \
     -e COLLECTOR=[COLLECTOR_ADDRESS] \
    -e TAGS=[TAGS] \
    -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 \
    quay.io/sysdig/agent
    

    If you are using eBPF use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host\
     -e ACCESS_KEY=[ACCESS_KEY] \
     -e COLLECTOR=[COLLECTOR_ADDRESS] \
    -e TAGS=[TAGS] \
    -e SYSDIG_BPF_PROBE="" \
    -v /sys/kernel/debug:/sys/kernel/debug:ro \
    -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 \
    quay.io/sysdig/agent
    

On-Premises

Installing As Two Containers

  1. Collect the following configuration parameters:

    • ACCESS_KEY: The agent access key. You can retrieve this from Settings > Agent Installation in either Sysdig Monitor or Sysdig Secure.
    • COLLECTOR: Use the URL of your environment.
    • TAGS: The list of tags for the host where the agent is installed. For example: role:webserver, location:europe, role:webserver
    • SYSDIG_BPF_PROBE: The path to the probe file that was either built or downloaded.
    • CHECK_CERTIFICATE: Set to false if a self-signed certificate or private CA-signed certificate is used. For more information, see Set Up SSL Connectivity to the Backend.
  2. Build and load the kernel module:

    If you are not using eBPF, use the following:

    docker run -it --privileged --rm --name sysdig-agent-kmodule \
    -v /usr:/host/usr:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules \
    quay.io/sysdig/agent-kmodule
    

    If you are using eBPF use the following:

    docker run -it --privileged --rm --name sysdig-agent-kmodule \
    -e SYSDIG_BPF_PROBE="" \
    -v /etc/os-release:/host/etc/os-release:ro \
    -v /root/.sysdig:/root/.sysdig \
    -v /usr:/host/usr:ro \
    -v /boot:/host/boot:ro \
    -v /lib/modules:/host/lib/modules:ro \
    quay.io/sysdig/agent-kmodule
    
  3. Configure kernel module to load during system boot.

    If you are not using eBPF, use the following commands to configure the Linux system to automatically load the kernel module during system boot.

    $ sudo mkdir -p /etc/modules-load.d
    $ sudo bash -c "echo sysdigcloud-probe > /etc/modules-load.d/sysdigcloud-probe.conf"
    
    
  4. Run the agent module providing the access key and, optionally, user-defined tags:

    If you are not using eBPF, use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host \
    -e ACCESS_KEY=[ACCESS_KEY] \
    -e COLLECTOR=[COLLECTOR_ADDRESS] \
    -e SECURE=true \
    -e CHECK_CERTIFICATE=true \
    [-e TAGS=[TAGS]]
    -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 \
    quay.io/sysdig/agent-slim
    

    If you are using eBPF use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host \
    -e ACCESS_KEY=[ACCESS_KEY] \
    -e COLLECTOR=[COLLECTOR_ADDRESS] \
    -e SECURE=true \
    -e CHECK_CERTIFICATE=true \
    [-e TAGS=[TAGS]]
    -e SYSDIG_BPF_PROBE="" \
    -v /sys/kernel/debug:/sys/kernel/debug:ro \
    -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 \
    quay.io/sysdig/agent-slim
    

Installing As Single Container (Legacy)

  1. Collect the following configuration parameters:

    • ACCESS_KEY: The agent access key. You can retrieve this from Settings > Agent Installation in either Sysdig Monitor or Sysdig Secure.
    • COLLECTOR: Use the URL of your environment.
    • TAGS: The list of tags for the host where the agent is installed. For example: role:webserver, location:europe, role:webserver
    • SYSDIG_BPF_PROBE: The path to the probe file that was either built or downloaded.
    • CHECK_CERTIFICATE: Set to false if a self-signed certificate or private CA-signed certificate is used. For more information, see Set Up SSL Connectivity to the Backend.
  2. Run the agent module providing the access key and, optionally, user-defined tags:

    If you are not using eBPF, use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host \
    -e ACCESS_KEY=[ACCESS_KEY] \
    -e COLLECTOR=[COLLECTOR_ADDRESS] \
    -e SECURE=true \
    -e CHECK_CERTIFICATE=true \
    [-e TAGS=[TAGS]]
    -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 \
    quay.io/sysdig/agent
    

    If you are using eBPF use the following:

    docker run -d --name sysdig-agent \
    --restart always \
    --privileged \
    --net host \
    --pid host \
    -e ACCESS_KEY=[ACCESS_KEY] \
    -e COLLECTOR=[COLLECTOR_ADDRESS] \
    -e SECURE=true \
    -e CHECK_CERTIFICATE=true \
    [-e TAGS=[TAGS]]
    -e SYSDIG_BPF_PROBE="" \
    -v /sys/kernel/debug:/sys/kernel/debug:ro \
    -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 \
    quay.io/sysdig/agent
    

Installing Agent as a Service on Linux Host

Use these instructions to install the agent on the host itself, not in a container. Install on each host in the environment.

The command lines below can also be copy/pasted from the Welcome wizard or the Settings>Agent Installation page in the Sysdig Monitor interface.

In that case, your access key will already be included in the command automatically.

The Sysdig agent depends on several python modules, some of which might not be installed on the hosts where the agent is running as a service. When the required dependencies are not available, the sdchecks component in the agent will report errors in the log files, such as:

 >> Error, sdchecks[0] ModuleNotFoundError: No module named 'posix_ipc'

To address these errors, install the missing modules using the pip install command.

SaaS

  1. Run the following command:

    curl -s https://download.sysdig.com/stable/install-agent | sudo bash -s -- --access_key [ACCESS_KEY] --collector [COLLECTOR_ADDRESS] [--tags [TAGS]]
    

    Where [ACCESS_KEY] is your unique agent access key string. For example, 1234-your-key-here-1234. TAGS is an optional list of user-defined agent tags. For example, role:webserver,location:europe.

    See SaaS Regions and IP Ranges to find the collector endpoint for your region.

  2. Restart the agent and start the service:

    sudo systemctl enable dragent
    

On-Premises

  1. Run the following command:

    curl -s https://download.sysdig.com/stable/install-agent | sudo bash -s -- --access_key [ACCESS_KEY] --collector [COLLECTOR_ADDRESS] --secure true --check_certificate true [--tags [TAGS]]
    

    Where [ACCESS_KEY] is your unique agent access key string. For example, 1234-your-key-here-1234. TAGS is an optional list of user-defined agent tags. For example, role:webserver,location:europe. check_certificate: Set it to false if a self-signed certificate, a private, or a CA-signed certificate is used. See Set Up SSL Connectivity to the Backend for more information.

  2. Restart the agent and start the service:

    sudo systemctl enable dragent
    

Connect to the Sysdig Backend via Static IPs (SaaS only)

Sysdig provides a list of static IP addresses that can be whitelisted in a Sysdig environment, allowing users to establish a network connection to the Sysdig backend without opening complete network connectivity. This is done by setting the Collector IP to collector-static.sysdigcloud.com:

user@host:~$ docker run --name sysdig-agent \
--privileged \
--net host \
--pid host \
-e ACCESS_KEY=[ACCESS_KEY] \
-e TAGS=[TAGS] \
-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 \
-e COLLECTOR=collector-static.sysdigcloud.com \
-e COLLECTOR_PORT=6443 \
-e SECURE=true \
-e CHECK_CERTIFICATE=true \
--shm-size=512m \
quay.io/sysdig/agent-slim

Guidelines for Manual Agent Installation

In the following cases, we recommend that you manually install the agent.

  • Full control over the deployment process

  • Integration with configuration management tools

  • Custom kernel

  • Unsupported distribution

See Agent Install: Manual Linux Installation for more information.



Last modified June 23, 2022