How to Install Osquery on Ubuntu VPS

This article provides a guide describing how to install Osquery on Ubuntu VPS.

What is Osquery?

Osquery is a lightweight, SQL-powered agent that lets you query your Linux system like a database. Need to list running processes, open ports, installed packages, or detect file changes? You can do it all with plain SELECT statements and automate them on a schedule.

Below is a production-ready, step-by-step guide tailored for Ubuntu VPS servers.

What You’ll Need

• An Ubuntu VPS (Ubuntu 20.04/Ubuntu 22.04/Ubuntu 24.04 LTS) with sudo/root access
• Internet connectivity (to fetch packages)
• ~100MB disk space for binaries + logs (more if you log verbosely)

How to Install Osquery on Ubuntu VPS

To install Osquery on Ubuntu VPS, follow the steps below:

1. Update the system & install helpers

   sudo apt update
   sudo apt -y install curl gpg ca-certificates lsb-release
   

2. Add the official Osquery APT repository

   Why the repo? Ubuntu’s built-in package can lag behind. The official repo ships current, security-patched builds for amd64/arm64.

   Create a keyring and source list:

   # Import GPG key into a dedicated keyring (no deprecated apt-key)
   curl -fsSL https://pkg.osquery.io/deb/pubkey.gpg \
     | sudo gpg --dearmor -o /usr/share/keyrings/osquery-archive-keyring.gpg
   
   # Add the repository (auto-detect architecture)
   ARCH=$(dpkg --print-architecture)
   echo "deb [arch=${ARCH} signed-by=/usr/share/keyrings/osquery-archive-keyring.gpg] https://pkg.osquery.io/deb deb main" \
    | sudo tee /etc/apt/sources.list.d/osquery.list
   
   sudo apt update
   

3. Install Osquery

   sudo apt -y install osquery
   

   Verify:

   osqueryi --version
   # osqueryi version x.y.z
   

4. Know the file layout (Ubuntu/Debian packages)

   • Binaries:
   • Interactive shell: /usr/bin/osqueryi
   • Daemon (service): /usr/bin/osqueryd
   • Config directory: /etc/osquery/
   • Default config file: /etc/osquery/osquery.conf (you create it)
   • Optional flags file: /etc/osquery/osquery.flags
   • Packs (ready-made queries): /usr/share/osquery/packs/
   • State/DB: /var/osquery/
   • Logs: /var/log/osquery/
   • Systemd unit: osqueryd.service

5. Create a minimal, production-safe config

   Create /etc/osquery/osquery.conf:

   sudo tee /etc/osquery/osquery.conf >/dev/null <<'JSON'
   {
     "options": {
       "host_identifier": "hostname",
       "config_refresh": 300,
       "schedule_splay_percent": 10,
       "pidfile": "/var/osquery/osquery.pid",
       "database_path": "/var/osquery/osquery.db",
       "logger_plugin": "filesystem",
       "logger_path": "/var/log/osquery",
       "utc": true,
   
       "disable_events": false,
       "events_expiry": 3600
     },
   
     "schedule": {
       "system_info_hourly": {
         "query": "SELECT hostname, cpu_brand, physical_memory FROM system_info;",
         "interval": 3600
       },
       "os_version_hourly": {
         "query": "SELECT name, version, major, minor, patch FROM os_version;",
         "interval": 3600
       },
       "listening_ports_5m": {
         "query": "SELECT pid, port, address, protocol, state FROM listening_ports;",
         "interval": 300
       },
       "installed_packages_6h": {
         "query": "SELECT name, version, revision, arch FROM deb_packages;",
         "interval": 21600
       },
   
       "fim_events": {
         "query": "SELECT * FROM file_events;",
         "interval": 60,
         "removed": false
       }
     },
   
     "file_paths": {
       "etc": ["/etc/%%"],
       "binaries": ["/bin/%%", "/sbin/%%", "/usr/bin/%%", "/usr/sbin/%%"],
       "logs": ["/var/log/%%"],
       "web": ["/var/www/%%"]
     },
   
     "exclude_paths": {
       "logs": ["/var/log/journal/%%"]
     },
   
     "decorators": {
       "load": [
         "SELECT uuid AS host_uuid FROM system_info;",
         "SELECT hostname AS host FROM system_info;"
       ]
     },
   
     "packs": {
       "osquery-monitoring": "/usr/share/osquery/packs/osquery-monitoring.conf"
     }
   }
   JSON
   

   What this does

   See Also: How to Install Prometheus on Debian VPS

   • Writes logs to /var/log/osquery/ in UTC
   • Splays (randomizes) schedules to avoid thundering herd on fleets
   • Enables eventing and FIM (file event) collection
   • Schedules a few safe, useful queries
   • Loads the built-in “osquery-monitoring” pack for self-health checks

   Note: file_events needs disable_events=false (already set). It tracks changes under the file_paths categories you defined.

6. (Optional) Flags file for early-boot options

   Some settings are better as flags. Create /etc/osquery/osquery.flags:

   sudo tee /etc/osquery/osquery.flags >/dev/null <<'FLAGS'
   --config_path=/etc/osquery/osquery.conf
   --logger_path=/var/log/osquery
   --pidfile=/var/osquery/osquery.pid
   --database_path=/var/osquery/osquery.db
   FLAGS
   

   If you later integrate with a central manager (Fleet/Kolide), you’ll add TLS flags here (see the optional section below).

7. Enable & start the service

   sudo systemctl daemon-reload
   sudo systemctl enable --now osqueryd
   sudo systemctl status osqueryd --no-pager
   

   Check logs:

   sudo ls -l /var/log/osquery/
   sudo tail -n 100 /var/log/osquery/osqueryd.results.log
   sudo journalctl -u osqueryd -n 50 --no-pager
   

8. Try interactive queries

   Use the shell for ad-hoc questions:

   # Open the interactive shell
   sudo osqueryi
   
   # Examples inside osqueryi:
   SELECT * FROM system_info;
   SELECT name, version FROM deb_packages WHERE name LIKE 'openssh%';
   SELECT pid, name, path FROM processes WHERE name='sshd';
   SELECT address, port, protocol, pid FROM listening_ports ORDER BY port;
   .quit
   

   For machine-readable output:

   sudo osqueryi --json "SELECT hostname, cpu_brand, physical_memory FROM system_info;"
   

9. File Integrity Monitoring (FIM) check

   With the config above, Osquery watches common paths. Generate a test event:

   sudo touch /etc/test-osquery-fim.txt
   sudo rm /etc/test-osquery-fim.txt
   sudo tail -n 200 /var/log/osquery/osqueryd.results.log | grep file_events | tail -n 5
   

   You should see file_events entries for create/delete.

   If you’re also running auditd and decide to use Osquery’s audit framework deeply, avoid conflicting configurations. For typical FIM via file_events, the default Osquery setup is fine.

   See Also: 🚀 Deploy ScyllaDB on Ubuntu VPS

10. (Optional) Log to syslog/journald

    If you prefer central log shipping via rsyslog/journal collectors, set:

    sudo sed -n '1,200p' /etc/osquery/osquery.conf | sudo tee /tmp/osq.tmp >/dev/null
    sudo jq '.options.logger_plugin="filesystem,syslog"' /tmp/osq.tmp | sudo tee /etc/osquery/osquery.conf >/dev/null
    sudo systemctl restart osqueryd
    

    Check syslog:

    sudo tail -n 100 /var/log/syslog | grep osquery
    

11. (Optional) Enroll with Fleet (central management)

    If you use [FleetDM] or a similar manager, add TLS flags. Replace values with your server details:

    # Enroll secret (place provided secret here)
    echo "YOUR-ENROLL-SECRET" | sudo tee /etc/osquery/enroll_secret >/dev/null
    sudo chmod 600 /etc/osquery/enroll_secret
    
    # Server CA (public cert for your Fleet server)
    # Save your PEM to /etc/osquery/fleet.pem
    # sudo nano /etc/osquery/fleet.pem
    
    # Add TLS flags
    sudo tee -a /etc/osquery/osquery.flags >/dev/null <<'FLAGS'
    --enroll_secret_path=/etc/osquery/enroll_secret
    --tls_hostname=fleet.example.com:443
    --tls_server_certs=/etc/osquery/fleet.pem
    
    # Use TLS for configuration and logging (keep filesystem too for local copies)
    --config_plugin=tls
    --logger_plugin=tls,filesystem
    --config_tls_endpoint=/api/osquery/config
    --enroll_tls_endpoint=/api/osquery/enroll
    --logger_tls_endpoint=/api/osquery/log
    --disable_distributed=false
    --distributed_tls_read_endpoint=/api/osquery/distributed/read
    --distributed_tls_write_endpoint=/api/osquery/distributed/write
    FLAGS
    
    sudo systemctl restart osqueryd
    

12. Hardening & performance tips

    • Least privilege: Osquery can run as non-root, but many tables require elevated permissions. If you run it as root (default), tightly control who can edit /etc/osquery/ and read /var/log/osquery/.
    • Splay your schedules: Already enabled to reduce spikes (schedule_splay_percent).
    • Tune intervals: Increase interval for heavy queries (e.g., deb_packages) to reduce I/O.
    • Log rotation: Ensure your log manager rotates /var/log/osquery/* to prevent disk growth.
    • Packs: Explore /usr/share/osquery/packs/ (e.g., incident-response, it-compliance) and enable only what you need.

13. Troubleshooting

    • Validate config syntax:

      sudo osqueryi --config_path=/etc/osquery/osquery.conf --enable_monitor=true --verbose
    

    • Service/logs:

      sudo systemctl status osqueryd --no-pager
      sudo journalctl -u osqueryd -e --no-pager
      sudo tail -n 200 /var/log/osquery/osqueryd.INFO
    

    • Common issues:
    • No file_events data: Make sure "disable_events": false is set and you scheduled a query against file_events.
    • Repo fetch errors: Re-download the GPG key and confirm /etc/apt/sources.list.d/osquery.list matches your architecture.
    • High CPU from heavy queries: Increase intervals, remove unneeded packs, or narrow queries.

14. Upgrades & removal

    • Upgrade with normal apt flows:

      sudo apt update && sudo apt -y upgrade
    

    • Remove (keeping config/data):

      sudo systemctl disable --now osqueryd
      sudo apt -y remove osquery
    

    • Purge (removes config):

      sudo apt -y purge osquery
      sudo rm -rf /var/osquery /var/log/osquery /etc/osquery
    

Quick-install one-liner (optional)

sudo bash -c '
set -e
apt update && apt -y install curl gpg ca-certificates
curl -fsSL https://pkg.osquery.io/deb/pubkey.gpg | gpg --dearmor -o /usr/share/keyrings/osquery-archive-keyring.gpg
ARCH=$(dpkg --print-architecture)
echo "deb [arch=${ARCH} signed-by=/usr/share/keyrings/osquery-archive-keyring.gpg] https://pkg.osquery.io/deb deb main" > /etc/apt/sources.list.d/osquery.list
apt update && apt -y install osquery
systemctl enable --now osqueryd
osqueryi --version
'

See Also: How to Install and Run Zulip on Debian VPS

You’re done!

You now know how to install Osquery on Ubuntu VPS. You now have Osquery installed, scheduled, logging, and ready for deeper monitoring.