How to Install Sysdig on Debian Linux

Sysdig captures and analyzes system calls, network activity, and process behavior in real-time, making it invaluable for debugging performance issues, investigating security incidents, and monitoring container environments. Unlike traditional monitoring tools that sample data periodically, Sysdig intercepts every system call at the kernel level, providing complete visibility into what applications are doing. This guide covers installing Sysdig on Debian through the official Sysdig repository, which provides the latest version with full kernel module support. After completing these steps, you will be able to monitor specific processes, filter events by container or application, and use the csysdig terminal interface for interactive analysis.

Update Debian Before Installation

Before installing Sysdig, first update your package lists and upgrade installed packages to ensure dependency compatibility:

sudo apt update && sudo apt upgrade

Install Sysdig from Official Repository

The official Sysdig repository provides the latest version with full kernel module support. While Debian 12 includes an older Sysdig version in its default repositories, the official repository offers newer releases with additional features and bug fixes. Importantly, this method works on Debian 11, 12, and 13. To begin, install the required prerequisites:

sudo apt install curl ca-certificates gnupg ncurses-term dkms -y

These packages serve specific purposes: curl downloads the GPG key, gnupg converts the key to binary format for APT, ca-certificates validates HTTPS connections, ncurses-term provides terminal capabilities for the csysdig interface, and dkms (Dynamic Kernel Module Support) automatically rebuilds the sysdig-probe module when your kernel updates.

Import the Sysdig GPG Key

Next, download and convert the Sysdig GPG key to binary format for APT signature verification:

curl -fsSL https://download.sysdig.com/DRAIOS-GPG-KEY.public | gpg --dearmor | sudo tee /usr/share/keyrings/sysdig.gpg > /dev/null

Add the Sysdig APT Repository

After importing the GPG key, create a DEB822-format repository file that points to the Sysdig stable repository:

echo "Types: deb
URIs: https://download.sysdig.com/stable/deb
Suites: stable-$(dpkg --print-architecture)/
Signed-By: /usr/share/keyrings/sysdig.gpg" | sudo tee /etc/apt/sources.list.d/sysdig.sources

This guide uses the modern DEB822 .sources format. The Suites: line ends with a trailing slash because Sysdig uses a flat repository structure without separate components.

Refresh APT Package Index

Now update your package lists to include the newly added Sysdig repository:

sudo apt update

Verify Repository Configuration

Before proceeding with installation, confirm that APT recognizes the Sysdig repository:

apt-cache policy sysdig

Expected output showing the Sysdig repository as source:

sysdig:
  Installed: (none)
  Candidate: 0.41.2
  Version table:
     0.41.2 500
        500 https://download.sysdig.com/stable/deb stable-amd64/ Packages
     0.41.1 500
        500 https://download.sysdig.com/stable/deb stable-amd64/ Packages

Install Sysdig and Kernel Headers

With the repository configured, install Sysdig along with the kernel headers required to build the sysdig-probe kernel module:

sudo apt install linux-headers-$(uname -r) sysdig -y

The kernel headers must match your running kernel version exactly. During installation, DKMS automatically compiles the sysdig-probe module, which allows Sysdig to intercept system calls at the kernel level. Subsequently, if you update your kernel, DKMS will rebuild the module automatically.

Verify Sysdig Installation

Once installation completes, verify the installed Sysdig version to confirm everything is working correctly:

sysdig --version

Example output:

sysdig version 0.41.2

Sysdig Command Examples

Sysdig provides powerful filtering and analysis capabilities for system calls, processes, and network activity. Unlike tools that only show summary statistics, Sysdig can capture every system call with full context, including arguments, return values, and timing. The following examples demonstrate common monitoring tasks that showcase these capabilities.

Basic System Monitoring

To get started, first explore these fundamental commands that help you understand overall system activity.

List Available Filter Fields

To understand what data Sysdig can capture, display all available filter fields:

sysdig -l

This outputs hundreds of available filter fields organized by category. Here is a sample of the event-related fields:

-------------------------------
Field Class:                  evt (All event types)
Description:                  These fields can be used for all event types 
Event Sources:                syscall 

evt.num                       event number. 
evt.time                      event timestamp as a time string that includes the nanosecond part. 
evt.time.s                    event timestamp as a time string with no nanoseconds. 
evt.datetime                  event timestamp as a time string that includes the date.
...

Common fields include proc.name (process name), fd.name (file descriptor name), evt.type (event type like read, write, open), and container.name (Docker container name). As a result, you can use these fields to build targeted queries for specific analysis tasks.

Monitor System Activity

Similarly, you can monitor real-time CPU activity using the topprocs_cpu chisel. Chisels are pre-built Lua scripts that process Sysdig’s raw event stream into useful summaries:

sudo sysdig -c topprocs_cpu

This displays the processes consuming the most CPU in a continuously updating view, helping identify resource-intensive applications. Press Ctrl+C to stop monitoring. For basic process monitoring without kernel-level detail, install htop on Debian as a lightweight alternative.

List Available Chisels

To see all available chisels organized by category, run:

sysdig -cl

Example output showing chisel categories:

Category: CPU Usage
-------------------
topcontainers_cpu    Top containers by CPU usage
topprocs_cpu         Top processes by CPU usage

Category: Errors
----------------
topfiles_errors      Top files by number of errors
topprocs_errors      Top processes by number of errors

Category: Net
-------------
spy_ip               Show the data exchanged with the given IP address
topconns             Top network connections by total bytes
topprocs_net         Top processes by network I/O

Category: Security
------------------
spy_users            Display interactive user activity

Each chisel serves a specific monitoring purpose. For instance, spy_users tracks all commands executed by users, making it particularly valuable for security auditing.

Filter by Process Name

Beyond summary views, Sysdig excels at filtering raw events for specific processes. For example, to monitor all system calls from Nginx on Debian:

sudo sysdig proc.name=nginx

This captures every system call made by Nginx processes, including file reads, network operations, and memory allocations. Consequently, the output streams in real-time, showing the direction (> for entry, < for exit), timestamp, process name, and syscall details.

Filter by Container Name

If you run containers, Sysdig can filter events to a specific Docker container on Debian:

sudo sysdig container.name=my_container

Replace my_container with your actual container name. This approach is particularly useful for debugging container-specific issues, since you see only events from processes inside that container rather than system-wide noise.

Advanced Monitoring Commands

In addition to basic monitoring, Sysdig includes specialized chisels for file I/O analysis, network monitoring, and security investigations. These provide deeper insights than standard Linux tools.

Monitor File I/O Activity

The spy_file chisel shows files being accessed, the processes accessing them, and the actual data being read or written:

sudo sysdig -c spy_file

This is particularly useful for understanding what configuration files an application reads during startup or what log files it writes to. Additionally, you can filter to a specific file:

sudo sysdig -c spy_file /etc/passwd

Analyze Network Connections

Likewise, you can display active network connections with the netstat chisel:

sudo sysdig -c netstat

Output includes source and destination IP addresses, ports, and connection state for all active connections. Similarly, for network traffic analysis, the topconns chisel shows connections sorted by bytes transferred:

sudo sysdig -c topconns

Create Custom Filtered Views

Furthermore, you can combine chisels with filters to create focused monitoring views for specific processes or events.

Custom View for CPU Usage

To create a custom view that displays the CPU usage of processes, use the following command:

sudo sysdig -c topprocs_cpu "evt.type=execve and proc.name=my_process"

Replace my_process with the process name you want to monitor. The filter limits output to only matching processes while the chisel displays CPU consumption rankings. Like all capture commands, this requires root privileges.

Interactive Monitoring with csysdig

While the command-line sysdig tool is powerful for scripted analysis, csysdig provides an interactive terminal interface for navigating system metrics and events. It offers the same powerful filtering as sysdig but presents data in a navigable, menu-driven interface similar to htop. This makes csysdig ideal for real-time troubleshooting sessions where you need to explore system behavior interactively.

Launch csysdig

To begin, launch csysdig with root privileges to access all system events:

sudo csysdig

The interface opens showing the default Processes view. From here, use keyboard shortcuts to navigate between views and filter data.

Navigate csysdig Views

Once csysdig is running, press F2 or type : followed by the view name to switch between built-in views:

• Processes: Displays a list of running processes and their resource usage. (Shortcut: :processes)
• Connections: Shows active network connections, including source and destination IP addresses, ports, and connection state. (Shortcut: :connections)
• Errors: Highlights system errors and exceptions. (Shortcut: :errors)
• Containers: Lists running containers and their resource usage. (Shortcut: :containers)

csysdig Keyboard Shortcuts

The following shortcuts help you navigate csysdig efficiently:

• F1 or h: Display the help menu, providing an overview of available commands and shortcuts.
• F2 or v: Switch between available views.
• F4 or l: Apply a filter to the current view. For example, you can filter processes by their name or containers by their ID.
• F5 or s: Sort the current view by a specific column.
• F6 or a: Add or remove columns from the current view.
• Esc or q: Quit cSysdig or close the current menu.

Create Custom csysdig Views

Additionally, you can create custom views to focus on specific metrics:

1. Press F2 or type :addview to open the "Add View" menu.
2. Enter a name for your custom view.
3. Define the columns you want to include in your view by typing the respective column names.
4. Add a filter to your custom view by pressing F4 and entering the filter criteria.
5. Save your custom view by pressing Enter.

After saving, switch to your custom view with F2 or by typing :your_view_name.

Troubleshoot Sysdig

If you encounter issues when running Sysdig on Debian, the following solutions address the most common problems you may face.

Kernel Module Fails to Load

If Sysdig reports that the kernel module cannot be loaded, first verify that the kernel headers are installed for your running kernel:

sudo apt install linux-headers-$(uname -r)

Afterward, attempt to load the module manually:

sudo modprobe sysdig-probe

However, if the module fails to load due to kernel version incompatibility, Sysdig 0.35.0 and later supports an eBPF driver that does not require a compiled kernel module. The official Sysdig repository provides version 0.41.x which includes this feature:

sudo sysdig --modern-bpf

This modern BPF probe uses the kernel's built-in eBPF virtual machine, eliminating the need for DKMS compilation. It works on kernels 5.8 and later.

Permission Denied Errors

Because Sysdig requires root privileges to access system calls and kernel events, you will see permission errors if you run it as a regular user. Always run Sysdig with sudo:

sudo sysdig -c topprocs_cpu

Likewise, csysdig requires elevated privileges to function properly. Always run with sudo for full functionality.

Manage Sysdig Installation

Finally, here are commands for updating and removing Sysdig from your Debian system.

Update Sysdig

When new versions are released, you can update only Sysdig without upgrading other packages:

sudo apt update && sudo apt install --only-upgrade sysdig

Alternatively, update Sysdig along with all system packages:

sudo apt update && sudo apt upgrade

Remove Sysdig

If you no longer need Sysdig on your system, follow these steps to remove it completely:

Uninstall Sysdig

First, remove the Sysdig package from your system:

sudo apt remove sysdig && sudo apt autoremove

Since you installed Sysdig from the official repository, you should also remove the GPG key and repository file:

Remove the Sysdig GPG Key

Next, remove the GPG key used for package verification:

sudo rm /usr/share/keyrings/sysdig.gpg

Remove the Sysdig APT Repository

Then remove the Sysdig repository file:

sudo rm /etc/apt/sources.list.d/sysdig.sources

Verify Removal

Finally, update the package cache and verify that Sysdig has been removed:

sudo apt update
apt-cache policy sysdig

Expected output after successful removal:

sysdig:
  Installed: (none)
  Candidate: (none)
  Version table:

On Debian 11 and 13, you will see the output above with no candidate version. On Debian 12, you may see a candidate from the default repositories (0.29.3-1+b1), which is an older version not covered by this guide. If you see version 0.41.x or higher in the candidate list, the /etc/apt/sources.list.d/sysdig.sources file may still exist.

Conclusion

You now have Sysdig installed and ready to monitor system calls, network connections, and process activity on your Debian system. To explore more capabilities, run sysdig -cl to discover additional chisels for container monitoring and security analysis. For a complete security monitoring setup, pair Sysdig with Fail2ban on Debian for automated intrusion response.