Skip to main content

Install the Praxis collector on Linux

Run praxis-collector on bare metal or a VM when you are not using Kubernetes. The binary connects to Praxis with OpAMP over a secure WebSocket, receives the pipeline configuration from Praxis the same way the Kubernetes path does, and runs your sources, processors, and destinations on the host.

Pipelines, credentials, and the collector instance you attach in Praxis are still the source of truth; this page describes the host install and runtime expectations.

:::tip Enterprise Linux & SELinux Deploying on RHEL, Rocky, AlmaLinux, Oracle Linux, Amazon Linux, SLES, Ubuntu, or Debian — or running SELinux in enforcing mode? See Enterprise Linux & SELinux support for the full distribution matrix, the unprivileged security model, exactly what the installer does on rpm/deb hosts, and the signed self-upgrade flow. The collector installs from signed native packages, runs as a dedicated unprivileged account with a scoped set of Linux capabilities (the default Praxis install enables packet-capture, root-log read, and host-process-metrics caps — drop the flags you don't need to fall back to the CAP_NET_BIND_SERVICE-only least-privilege baseline), and is validated on SELinux enforcing hosts. :::

Before you begin​

  • Prerequisites from Praxis — A published pipeline, an OpAMP URL (wss://.../v1/opamp or ws://... in non-production only), OAuth2 client key and secret for machine access, org ID, tenant ID, and pipeline ID. Praxis shows these when you add or enroll a Linux collector, or your administrator shares them in your runbook.
  • Network — The host must reach Praxis (OpAMP and token exchange) and any export destinations your pipeline uses (for example public cloud or corporate endpoints) according to your firewall rules.
  • Privileges — Plan to run the collector with the least privilege that still allows your chosen sources (for example file tailing under /var/log may require read access to specific paths or group membership).

Install (script pattern)​

Your environment may show a copy-paste command from Praxis. It typically:

  1. Downloads an install script from the download location your organization or Praxis provides.
  2. Passes --url, --key, --secret, --org, --tenant, and --pipeline (and optionally --version / --image where applicable).
  3. Enables the host-capability flags --enable-pcap, --enable-dac-read-search, and --enable-sys-ptrace so the broad source/scraper set (packet capture, root-only logs, host-wide process metrics) works out of the box.
  4. Installs a system service that starts the collector and reconnects to Praxis on boot.

A representative shape (placeholders only — use the exact command and URL from your Praxis UI or runbook):

sudo bash -c '$(curl -k -L https://<artifact-host>/path/linux_install.sh)' -- \
  --url wss://<praxis-host>/v1/opamp \
  --secret <oauth2-client-secret> \
  --key <oauth2-client-key> \
  --org <org-id> \
  --tenant <tenant-id> \
  --pipeline <pipeline-id> \
  --enable-pcap --enable-dac-read-search --enable-sys-ptrace
note

Some distributions ship curl without TLS verification flags on the download step; if your security policy disallows that, download the script, inspect it, and run it from disk instead of piping to bash, the same way described in the Kubernetes install guide.

:::warning Default capability set The default Praxis install command grants all three host capabilities (CAP_NET_RAW, CAP_DAC_READ_SEARCH, CAP_SYS_PTRACE) so every source and scraper works without a reinstall. Two of these are broad: CAP_DAC_READ_SEARCH lets the collector read any file on the host and CAP_SYS_PTRACE lets it read any process's memory. For a hardened, least-privilege install, drop the flags you don't need — see each section below. Removing all three leaves the lean default (CAP_NET_BIND_SERVICE only). :::

Packet capture (--enable-pcap, enabled by default)​

The PCAP source captures raw network packets, which requires the CAP_NET_RAW Linux capability. The default install command grants it via --enable-pcap. To harden a host that will never capture packets, omit --enable-pcap so the collector keeps least privilege:

# Hardened: packet capture NOT granted (omit --enable-pcap)
sudo bash -c '$(curl -k -L https://<artifact-host>/path/linux_install.sh)' -- \
  --url wss://<praxis-host>/v1/opamp \
  --secret <oauth2-client-secret> --key <oauth2-client-key> \
  --org <org-id> --tenant <tenant-id> --pipeline <pipeline-id> \
  --enable-dac-read-search --enable-sys-ptrace

Key points:

  • It's host-level and install-time. A remote pipeline change can't grant or revoke the capability — only a reinstall/upgrade can. The installer records the choice (PRAXIS_ENABLE_PCAP=true in /etc/default/praxis-collector on Debian/Ubuntu or /etc/sysconfig/praxis-collector on RHEL-family) and the package grants the capability and persists it across auto-updates.
  • No reinstall to use it. Once a host is enabled, you can add or remove a pcap source in the pipeline and it takes effect over OpAMP — no reinstall.
  • Safe if disabled. If a pipeline adds a pcap source to a host where the flag was omitted, the source fails closed with a clear permission error (it never captures silently).
  • Linux only. Packet capture is not supported on macOS or Windows.

To turn packet capture off on an already-installed host, remove the PRAXIS_ENABLE_PCAP line from the env file (or re-run the install command without --enable-pcap) and reinstall/upgrade. See the PCAP source for configuration.

Root-only log access (--enable-dac-read-search, enabled by default)​

Some log sources read files that only root can open — most notably the Linux audit log at /var/log/audit/audit.log, which auditd writes root:root 0600 with no group to join. Reaching those files needs the CAP_DAC_READ_SEARCH capability, which the default install command grants via --enable-dac-read-search. Because this is a broad capability (see the warning below), omit --enable-dac-read-search on any host that does not ingest root-only logs:

# Hardened: root-only file read NOT granted (omit --enable-dac-read-search)
sudo bash -c '$(curl -k -L https://<artifact-host>/path/linux_install.sh)' -- \
  --url wss://<praxis-host>/v1/opamp \
  --secret <oauth2-client-secret> --key <oauth2-client-key> \
  --org <org-id> --tenant <tenant-id> --pipeline <pipeline-id> \
  --enable-pcap --enable-sys-ptrace
warning

CAP_DAC_READ_SEARCH bypasses all Linux DAC read/search permission checks — a process that holds it can read any file on the host (including /etc/shadow, private keys, and other secrets), not just logs. The default install command grants it; drop the flag on hosts where that broader read scope is not acceptable to your security team. If you actually need general root access, prefer the explicit run-as-root option instead.

Key points:

  • Host-level, install-time. The installer records PRAXIS_ENABLE_DAC_READ_SEARCH=true (in /etc/default/praxis-collector on Debian/Ubuntu or /etc/sysconfig/praxis-collector on RHEL-family) and the package grants the capability via a 25-dac-read-search.conf systemd drop-in that persists across auto-updates. A remote pipeline change can never grant or revoke it.
  • SELinux. On enforcing hosts the capability works in the default domain. If you run the optional confined SELinux module, the module must include the matching type-enforcement rules; verify with ausearch -m avc after enabling.
  • Linux only, and applies to the praxiscollector (unprivileged) run mode — it has no effect when PRAXIS_RUN_AS_ROOT=true (root already reads everything).

To turn this off on an already-installed host, remove the PRAXIS_ENABLE_DAC_READ_SEARCH line from the env file (or re-run the install command without --enable-dac-read-search) and reinstall/upgrade.

Host process metrics (--enable-sys-ptrace, enabled by default)​

The host-metrics process scraper (per-process CPU, memory, I/O, open files, and command line) reads /proc/<pid>/ entries for processes owned by other users. The kernel only permits that for a process holding CAP_SYS_PTRACE (which also bypasses the yama ptrace_scope restriction). The default install command grants it via --enable-sys-ptrace. Because this is a broad capability (see the warning below), omit --enable-sys-ptrace on hosts that don't need host-wide process metrics:

# Hardened: cross-user process visibility NOT granted (omit --enable-sys-ptrace)
sudo bash -c '$(curl -k -L https://<artifact-host>/path/linux_install.sh)' -- \
  --url wss://<praxis-host>/v1/opamp \
  --secret <oauth2-client-secret> --key <oauth2-client-key> \
  --org <org-id> --tenant <tenant-id> --pipeline <pipeline-id> \
  --enable-pcap --enable-dac-read-search
warning

CAP_SYS_PTRACE also permits attaching to and reading the memory of any process on the host, which can expose in-memory secrets. The default install command grants it; drop the flag on hosts where host-wide process metrics are not required.

Key points:

  • Host-level, install-time. The installer records PRAXIS_ENABLE_SYS_PTRACE=true in the same env file and grants the capability via a 30-sys-ptrace.conf systemd drop-in that persists across auto-updates. Without it, the process scraper still reports the collector's own processes but cannot see processes owned by other users.
  • SELinux. Same as above — works in the default domain; the optional confined module needs the matching sys_ptrace rule plus cross-domain /proc read. Verify with ausearch -m avc.
  • Linux only, and no effect under PRAXIS_RUN_AS_ROOT=true.

To turn this off on an already-installed host, remove the PRAXIS_ENABLE_SYS_PTRACE line from the env file (or re-run the install command without --enable-sys-ptrace) and reinstall/upgrade. For the full capability matrix and the underlying env variables, see Host capability opt-ins.

After install​

  • Confirm the service is active and logs show a healthy OpAMP session to Praxis.
  • In Praxis, confirm the collector instance is online and the pipeline is attached as you expect.
  • If you are not on Kubernetes, ignore Kubernetes-only receiver RBAC; on Linux use the right file, syslog, journald, or OTLP sources for the host.

Behind an HTTP/HTTPS Proxy​

If the host's egress to Praxis or to your destinations must traverse a corporate proxy, configure the collector with the standard Go HTTP proxy environment variables — HTTPS_PROXY, HTTP_PROXY, and NO_PROXY.

The Linux installer accepts proxy flags directly. It writes a systemd drop-in at /etc/systemd/system/praxis-collector.service.d/proxy.conf that survives package upgrades, then starts the service with the proxy already applied.

sudo bash -c '$(curl -k -L https://<artifact-host>/path/linux_install.sh)' -- \
  --url wss://<praxis-host>/v1/opamp \
  --secret <oauth2-client-secret> --key <oauth2-client-key> \
  --org <org-id> --tenant <tenant-id> --pipeline <pipeline-id> \
  --https-proxy http://proxy.corp.local:3128 \
  --no-proxy "localhost,127.0.0.1,::1,.corp.local,169.254.169.254"

If --no-proxy is omitted but --https-proxy (or --http-proxy) is set, a sensible loopback/IMDS default is applied automatically.

After install (manual)​

To add or change proxy settings on an existing install, write the drop-in yourself:

sudo mkdir -p /etc/systemd/system/praxis-collector.service.d

sudo tee /etc/systemd/system/praxis-collector.service.d/proxy.conf >/dev/null <<'EOF'
[Service]
Environment="HTTPS_PROXY=http://proxy.corp.local:3128"
Environment="HTTP_PROXY=http://proxy.corp.local:3128"
Environment="NO_PROXY=localhost,127.0.0.1,::1,.corp.local,169.254.169.254"
EOF

sudo systemctl daemon-reload
sudo systemctl restart praxis-collector

Verify the env is applied and the OpAMP session reconnects:

sudo systemctl show praxis-collector -p Environment
sudo journalctl -u praxis-collector -f | grep -iE "proxy|dial|connect"

NO_PROXY checklist​

Always include localhost, 127.0.0.1, ::1, 169.254.169.254 (cloud instance metadata), and the internal hostnames/CIDRs of any LAN log sources (for example a local syslog or HEC source) the collector connects to.

Auth-required proxies​

Use HTTPS_PROXY=http://user:[email protected]:3128. URL-encode any special characters in the password.

TLS-inspecting (MITM) proxies​

Install the corporate root CA into the OS trust store so outbound TLS handshakes validate.

# Debian/Ubuntu
sudo cp corp-root-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# RHEL/CentOS/Rocky
sudo cp corp-root-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

sudo systemctl restart praxis-collector
note

All outbound paths honor the standard proxy env vars, including the OpAMP WebSocket (collector ↔ Praxis), the OAuth2 token endpoint, the Google SecOps HTTP and gRPC exporters, Splunk HEC, Snowflake, M365, the GitHub receiver, and other confighttp-based exporters.

The Google SecOps gRPC path uses gRPC-Go's built-in CONNECT tunneling, which inspects HTTPS_PROXY / https_proxy only — never HTTP_PROXY. Always set HTTPS_PROXY when proxying Chronicle gRPC traffic, even if you also set HTTP_PROXY for HTTP-based exporters.

Uninstall​

Use the uninstall script or package command in Praxis or in your runbook (often a companion linux_uninstall.sh style script), or remove the package the install step registered. Stopping the service before removal avoids orphaned processes.