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.

  • 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 hosts 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.

  • Retrieve the Sysdig access key.

  • Collect the configuration parameters.

Configuration Options

OptionDescription
ACCESS_KEYThe agent access key. You can retrieve this from Settings > Agent Installation in either Sysdig Monitor or Sysdig Secure.
tagsThe list of tags for the host where the agent is installed. For example: role:webserver, location:europe, role:webserver
COLLECTORThe collector URL for Sysdig Monitor or Sysdig Secure. This value is region-dependent in SaaS and is auto-completed on the Get Started page in the UI. It is a custom value in on-prem installations. See SaaS Regions and IP Ranges.
collector_portThe default is 6443.
SECUREUse a secure SSL/TLS connection to send metrics to the collector. This option is enabled by default.
CHECK_CERTIFICATE(On-prem) Determines strong SSL certificate check for Sysdig Monitor on-premises installation. Set to true when using SSL/TLS to connect to the collector service to ensure that a valid SSL/TLS certificate is installed. For more information, see Set Up SSL Connectivity to the Backend.
ADDITIONAL_CONFOptional. Use this option to provide custom configuration values to the agent as environment variables. If provided, will be appended to agent configuration file. For example, For example, file log configuration.
bpfEnables eBPF probe. The path to the probe file that is either built or downloaded.

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. See Installation Options for description about agent-slim and agent-kmodule.

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

  1. Collect the configuration parameters.

  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 configuration parameters.

  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 configuration parameters:

  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 configuration parameters.

  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]]
    

    For configuration parameters, see Configuration Options.

  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.