Skip to content

install.md

Latest commit

 

History

History
225 lines (162 loc) · 6.95 KB

install.md

File metadata and controls

225 lines (162 loc) · 6.95 KB

Installation Guide

System Requirements

  • Operating System: Linux (kernel 4.4 or later)
    • Required kernel features:
      • eBPF support (CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y)
      • uprobe support (CONFIG_UPROBE_EVENTS=y) - introduced in Linux 3.5
      • BPF_MAP_TYPE_PERF_EVENT_ARRAY - introduced in Linux 4.3
      • Stable eBPF for tracing - recommended Linux 4.4+
  • Architecture: x86_64 (AMD64) only currently

Installation

Quick Install Script (Recommended)

GhostScope ships with an install helper that downloads the latest release binary, copies a default configuration to ~/.ghostscope/config.toml, and installs everything under ~/.ghostscope/bin (no sudo required).

curl -fsSL https://raw.githubusercontent.com/swananan/ghostscope/main/scripts/install.sh | bash

Prerequisites

  • curl, tar, install (usually provided by coreutils)
  • python3 (used to pick the correct release asset)

After the script finishes, add the binary path to your shell configuration:

  • Bash: echo 'export PATH="$HOME/.ghostscope/bin:$PATH"' >> ~/.bashrc
  • Zsh: echo 'export PATH="$HOME/.ghostscope/bin:$PATH"' >> ~/.zshrc
  • Fish: echo 'set -Ux PATH $HOME/.ghostscope/bin $PATH' >> ~/.config/fish/config.fish

Restart the terminal and run ghostscope --version to verify.

Download from GitHub Releases

  1. Download the latest release from GitHub Releases

  2. Extract the binary:

tar -xzf ghostscope-v0.1.3-x86_64-linux.tar.gz
  1. Move to system path (optional):
sudo mv ghostscope /usr/local/bin/
  1. Make it executable:
chmod +x ghostscope
  1. Verify installation:
ghostscope --version

Post-Installation Setup

1. Verify Installation

# Check GhostScope version
ghostscope --version

# View help
ghostscope --help

2. Configure Permissions

GhostScope requires root privileges to attach eBPF programs. You have several options:

Option A: Use sudo (Recommended)

sudo ghostscope -p $(pidof target)

Option B: Set Capabilities

sudo setcap cap_sys_admin,cap_sys_ptrace,cap_bpf+eip /path/to/ghostscope

Option C: Add User to Tracing Group

# Create tracing group if it doesn't exist
sudo groupadd tracing

# Add your user to the group
sudo usermod -a -G tracing $USER

# Configure permissions for the group
echo 'kernel.perf_event_paranoid = -1' | sudo tee /etc/sysctl.d/10-ghostscope.conf
sudo sysctl -p /etc/sysctl.d/10-ghostscope.conf

# Re-login for group changes to take effect

3. Debug Symbols (Required)

GhostScope requires DWARF debug information in the target binary to function properly. The debug symbols are typically embedded in the binary itself.

# Check if your binary has debug info (REQUIRED)
readelf -S your_program | grep debug

# Example output with debug info:
# [28] .debug_aranges    PROGBITS         0000000000000000  0070a3c0
# [29] .debug_info       PROGBITS         0000000000000000  007158a0
# [30] .debug_abbrev     PROGBITS         0000000000000000  011b4eb1
# [31] .debug_line       PROGBITS         0000000000000000  012705a2
# [32] .debug_str        PROGBITS         0000000000000000  01542903

If no .debug_* sections are found, the binary must be recompiled with debug symbols enabled (typically using -g flag or equivalent).

Note: Without debug symbols, GhostScope cannot resolve function names, variables, or source line information.

Separate Debug Files (GNU debuglink)

GhostScope also supports loading debug information from separate debug files using the .gnu_debuglink mechanism. This is useful when working with stripped binaries in production environments.

Check for debuglink section:

# Check if binary has .gnu_debuglink pointing to a separate debug file
readelf -x .gnu_debuglink your_program

# Example output:
# Hex dump of section '.gnu_debuglink':
#   0x00000000 6d795f70 726f6772 616d2e64 65627567 my_program.debug
#   0x00000010 00000000 12345678                   ....4Vx

Create separate debug file for a stripped binary:

# 1. Extract debug information to a separate file
objcopy --only-keep-debug your_program your_program.debug

# 2. Strip debug information from the binary
objcopy --strip-debug your_program

# 3. Add a link from the binary to the debug file
objcopy --add-gnu-debuglink=your_program.debug your_program

# Verify the debuglink was added
readelf -x .gnu_debuglink your_program

Debug file search paths (following GDB conventions):

GhostScope automatically searches for debug files in the following locations:

  1. Same directory as the binary: /path/to/your_program.debug
  2. .debug subdirectory: /path/to/.debug/your_program.debug
  3. Global debug directory: /usr/lib/debug/path/to/your_program.debug

📝 Custom Search Paths: You can configure additional search paths (including user-specific directories like ~/.local/lib/debug) in the configuration file. See the Configuration Reference - DWARF Debug Search Paths for detailed information.

Installing system debug packages:

# Ubuntu/Debian - install debug symbols for libc
sudo apt install libc6-dbg

# Fedora/RHEL - install debug symbols
sudo dnf debuginfo-install glibc

# The debug files are typically installed in /usr/lib/debug/

Verification:

GhostScope will automatically detect and use separate debug files. You can verify this in the logs:

# Run with debug logging to see debuglink resolution
RUST_LOG=debug sudo ghostscope -p $(pidof your_program)

# Look for messages like:
# "Looking for debug file 'your_program.debug' for binary '/path/to/your_program'"
# "Found matching debug file: /path/to/your_program.debug (CRC: 0x12345678)"

Troubleshooting

Permission Denied Errors

If you get permission errors when running GhostScope:

  1. Ensure you're using sudo or have proper capabilities set

  2. Check kernel configuration:

    zcat /proc/config.gz | grep BPF

    Ensure CONFIG_BPF=y and CONFIG_BPF_SYSCALL=y are set

  3. Check if BPF is enabled:

    ls /sys/fs/bpf

  4. Check if bpffs is mounted before running GhostScope:

    mount | grep bpf

    You should see /sys/fs/bpf mounted as filesystem type bpf. If /sys/fs/bpf exists but nothing is mounted there, GhostScope will fail when it tries to pin BPF maps. Some systems, including WSL2 and minimal/container environments, do not mount bpffs by default. In that case, run:

    sudo mount -t bpf bpf /sys/fs/bpf

Next Steps

Getting Help

If you encounter issues during installation:

  1. Check the FAQ for common problems
  2. Search existing issues
  3. File a new issue with installation logs