Self-hosting runZero

View as Markdown

Platform

Background

The self-hosted version of runZero runs the entire platform on-premises or in your own cloud environment. It is functionally identical to the hosted service, has a fully-offline mode, and sends no inventory data back to runZero.

Self-hosting is less common, but your company might choose it for a few reasons:

  • ISO compliance requirement
  • Other compliance requirement
  • Prefer data on-premise

Self-hosting must be enabled for your account. It’s available with a runZero Platform license or during an initial trial for a platform license, but not with the free Community Edition of runZero. Contact your runZero sales representative for details.

Requirements

Check your system against these requirements before you install.

Hardware requirements

Recommended production system requirements:

  • 12 CPU Cores at 2 GHz or faster
  • 1TB of local disk storage
  • 128 GB of RAM

Minimum production system requirements:

  • 4 CPU Cores at 2 GHz or faster
  • 100 GB of local disk storage
  • 32 GB of RAM (more for large sites)

Minimum testing system requirements:

  • 2 CPU Cores at 2 GHz or faster
  • 20 GB of local disk storage
  • 16 GB of RAM (more for large sites)

Sample customer deployments

Up to 1M assets:

  • Two virtual machines (one for console and one for database)
  • 32 CPU Cores at 2 GHz or faster
  • 1TB of local disk storage
  • 128 GB of RAM

Up to 500K assets:

  • 32 CPU Cores at 2 GHz or faster
  • 1TB of local disk storage
  • 128 GB of RAM

Up to 50K assets:

  • 16 CPU Cores at 2 GHz or faster
  • 1TB of local disk storage
  • 64 GB of RAM

Software requirements

  • PostgreSQL 14 or newer (17+ preferred; the installer can install it for you)

Supported operating systems

  • Ubuntu 18.04 and newer running on x86_64
  • Red Hat Enterprise Linux 7.x and newer running on x86_64
  • CentOS Linux 7.x and newer running on x86_64
  • Oracle Linux 7.x and newer running on x86_64
    • 8.x must be 8.4+ with UEK 5.4+ or kernel 4.18+
    • 7.x must be 7.9+ with UEK 5.4+ or kernel 3.10+
  • Debian Linux 9.x and newer running on x86_64

Windows Subsystem for Linux is not supported.

A minimal install of Ubuntu or any RHEL derivative is enough for the runZero console; you don’t need a GUI. The default disk partitioning scheme works, but consider LVM if you plan to resize the disk later.

Note about Debian

Debian Linux uses the su command instead of sudo by default, and you must become root with su -, not just su, so that PATH includes system administration commands such as useradd. If the installer fails with executable file not found in $PATH, this is the most likely reason.

Connectivity

The self-hosted runZero platform needs a connection to the runZero SaaS backend over TCP port 443 (TLS) for online updates. The IP addresses and hostnames depend on your deployment model and region.

United States

The console hostname is console.runzero.com.

IPv4

  • 13.248.161.247
  • 76.223.34.198

IPv6

  • 2600:9000:a415:cd87:fbe5:476a:3533:69f2
  • 2600:9000:a716:ee91:85f9:3c9:48c9:59b9

Germany

The console hostname is console-eu.runzero.com.

IPv4

  • 15.197.131.232
  • 3.33.248.90

IPv6

  • 2600:9000:a603:e925:542d:6d40:6897:bc3a
  • 2600:9000:a70e:635f:71bd:bb0a:8e43:9466

During installation and later software updates, the platform also needs to reach these sites over TCP port 443:

  • apt.postgresql.org

Platform address & TLS configuration

The system running the runZero platform should have a static IP address.

Explorers must be able to validate their HTTPS connection to the platform with a TLS certificate. By default, the runZero platform installer sets up a self-signed certificate for the console’s IP address, and downloaded Explorers come preconfigured with that URL and certificate so they can make a verified connection.

Some parts of the application still use the name "Rumble" for backwards compatibility. We'll update the documentation as they change.

Because Explorers pick up the console address and certificate at download time, changing the IP address or DNS name later means redeploying the Explorers so they receive the new address. Renewing a self-signed certificate also means redeploying them.

We recommend a real certificate from an internal or public CA for your runZero console deployment. With one in place, Explorers don't need reinstalling when the server's IP address changes or the certificate is renewed. As long as the DNS name stays the same and the new certificate still validates, Explorers keep working.

To use a real certificate from an internal or public CA, assign the console server a DNS name and set RUNZERO_CONSOLE in the configuration to the fully qualified domain name. Point TLS_CERT and TLS_KEY at the certificate and private key files, then restart the console with runzeroctl restart. Explorers downloaded after that come preconfigured with the right URL and certificate.

Behind a reverse proxy, the proxy may need extra configuration to pass the Origin header through to the runZero Console. CSRF protection requires this header, and some features (such as the data tables throughout the product) stop working if it is missing or incorrect.

Offline mode

The self-hosted version of runZero can run in offline mode. In this mode the console doesn’t use the runZero update service, so you must apply offline updates manually. Enable it on an isolated network, or whenever you don’t want your self-hosted runZero console making any connection to the internet. Offline mode also disables certain DNS probes that could reflect responses to the internet during a scan.

Installation steps

For offline installs, see offline installation. For installs that use your own database credentials, see Installation with your own PostgreSQL database.

The installer:

  • Sets up PostgreSQL and creates a dedicated user with a strong password.
  • Generates TLS certificates for your IP address in /etc/runzero/certs.
  • Generates a configuration file at /etc/runzero/config with some defaults.
  • Creates a systemD or RC service for the runZero platform.

Step 0: Start from a clean environment

If an earlier run of the installer hit a problem with disk space, memory, or repository verification, you may need to clean up its temporary files before retrying the install.

Remove any temporary files left from the previous install:

# rm -rf /tmp/update-tmp* /tmp/runzero-updates*

On RHEL and CentOS systems, clear any PostgreSQL remnants:

# dnf remove postgresql
# rm -rf /var/lib/pgsql/

Use the installer binary to purge any leftovers:

# ./runzero-install.bin uninstall --purge

Step 1: Download and run the installer

  • Go to https://console.runzero.com/deploy/download/platform.
  • Copy the command from the download page and run it in your terminal. It downloads the installer and marks it executable. The download path is uniquely keyed.
  • Run the installer.
  • The console installs to /opt/runzero by default. To change that, use the --install-directory option.

Step 2: Check disk space

The runZero console stores data in the storage directory under the install directory, /opt/runzero/storage by default. The storage directory must have room for all unexpired scan data and asset data. To move it, set the RUNZERO_STORAGE_PATH variable in the runZero configuration file /etc/runzero/config.

The temporary directory also needs plenty of space for software and content updates. If the TMPDIR environment variable is set, runZero uses that directory; otherwise it uses /tmp.

Step 3: Initialize the admin user

Installing the runZero platform gives you the runZero CLI, runzeroctl. To initialize an admin user, run:

runzeroctl initial [email address]

Step 4: Sign in to your self-hosted console

If everything is set up correctly, you can sign in to your console at https://YourInternalIPAddress.

You may need to allow HTTPS through the Linux system firewall. Example commands:

Ubuntu Linux: sudo ufw allow https/tcp

RHEL/CentOS/Oracle: sudo firewall-cmd --add-service=https

To make a firewall-cmd change permanent across reboots, run the command a second time with the --permanent flag.

Installation with your own PostgreSQL database

By default, runZero installs and configures a PostgreSQL user and database for you. To supply your own, install with the manual database option described below.

Requirements

  • PostgreSQL 13 or newer (16+ preferred)
  • Password authentication must be enabled.
  • Two extensions are required: pg_trgm and uuid-ossp. Depending on where you get your PostgreSQL packages, these may ship in a contrib package rather than with the main PostgreSQL server install.

This PostgreSQL example enables the extensions and adds a database and user:

CREATE DATABASE runzero TEMPLATE='template0' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
CREATE USER runzero WITH PASSWORD 'YOURPASSWORD';
GRANT ALL PRIVILEGES ON DATABASE runzero TO runzero;
\connect runzero;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

To install the self-hosted runZero platform with your own database credentials:

  1. Run this install command as root:
./runzero-platform-[VERSION]-linux-amd64.bin install --manual-database
  1. Add your database details to the runZero configuration in /etc/runzero/config. The line to edit is:
DATABASE_URL=postgres://runzero:{DB_PASSWORD}@127.0.0.1:5432/runzero?sslmode=disable

Change it to match your credentials. You need to set the user, password, host, port, and database name, in this format:

DATABASE_URL=postgres://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}?{DB_OPTIONS}
  1. Verify that the self-hosted runZero platform can connect to your database: sudo runzeroctl database verify
  2. Once the database is configured and verified, restart the self-hosted runZero platform service: sudo systemctl restart runzero-console

runZero updates

Update the self-hosted runZero platform before first use. You can use the runzeroctl command to download the update and then restart the service once the update completes. For offline updates, see CLI update with offline mode.

You can update the platform and scanners together or separately with the CLI update management commands.

Managing users

Manage users in your self-hosted runZero platform console at https://YourInternalIPAddress/team or with the runZero CLI. Tasks include:

  • Adding, deleting, and listing users
  • Resetting passwords
  • Changing default roles
  • Viewing details
  • Changing organization roles

CLI service management

Start the runZero service

Starts the runZero platform service.

runzeroctl start

Stop the runZero service

Stops the runZero platform service.

runzeroctl stop

Restart the runZero service

Restarts the runZero platform service.

runzeroctl restart

Install the runZero platform

Installs the runZero platform service and its dependencies, such as PostgreSQL. Creates a systemd service, generates cron jobs, and writes a configuration file to /etc/runzero/config.

runzeroctl install

Uninstall the runZero platform

Stops the runZero platform service, removes it from systemd, and removes the generated cron jobs. Your PostgreSQL database and data stay in place.

runzeroctl uninstall

Purge the runZero platform

Stops the runZero platform service, removes it from systemd, and removes the generated cron jobs. It also deletes your runZero database and removes the runZero directories /etc/runzero and /opt/runzero.

runzeroctl purge

To uninstall and purge everything except the database and your PostgreSQL settings, use this flag:

runzeroctl uninstall --purge --ignore-database

Run the runZero platform manually

Starts the runZero platform manually and writes logs to standard output.

runzeroctl server

Verify your database is reachable

Tries to connect to your database using your self-hosted runZero platform configuration, and either succeeds or shows an error.

runzeroctl database verify

CLI update management

Update the runZero platform and scanners

Updates the runZero platform service and the runZero scanners. The optional force parameter forces the update even when the current installation is already the latest version.

runzeroctl update [--force]

Update the runZero platform

Updates just the runZero platform service. The optional force parameter forces the update even when the current install is already the latest version.

runzeroctl update-platform [--force]

Update the runZero scanners

Updates just the runZero scanners. The optional force parameter forces the update even when the current installation is already the latest version.

runzeroctl update-scanner [--force]

CLI user management

Create the initial administrator account

Creates the initial admin user for a new installation. You must provide an email address.

runzeroctl initial <email>

List user accounts

Lists all users with their email address, full name, and current roles.

runzeroctl user list

Add a user account

Creates a new user account under the initial administrator user. You must provide an email address.

runzeroctl user add <email>

Delete a user account

Deletes a user account. You must provide an email address. This cannot be undone.

runzeroctl user delete <email>

Get user details

Shows the details for a user account, such as full name, date created, last sign-in IP, last sign-in time, last activity, default organization role, and current roles. You must provide an email address.

runzeroctl user details <email>

Set a user role

Sets a user’s role to the role provided. You must provide the email and the role; the organization is optional. Without an organization, this sets the user’s default role.

runzeroctl user set-role <email> [organization name or organization ID]:<role>

Reset a user password and MFA

Generates and applies a new password for the specified user and prints it to the terminal. You must provide an email address. The reset also clears any associated MFA tokens.

runzeroctl user reset <email>

CLI organization management

List all organizations

Lists all organizations by name and ID.

runzeroctl organization list

Advanced configuration

The file at /etc/runzero/config holds the settings described below. After editing it, apply the changes with runzeroctl restart.

Email server

runZero sends user account invitations and notifications through an SMTP server. The default configuration expects an SMTP server on localhost that needs no authentication:

SMTP_SERVER=127.0.0.1:25
SMTP_AUTH_METHOD=none

With plaintext SMTP servers, runZero uses STARTTLS automatically and validates the certificate. If your internal SMTP server lacks a valid TLS certificate, disable verification with:

SMTP_TLS_NOVERIFY=true

For transport-layer TLS instead of STARTTLS, set:

SMTP_TLS=true

If the server requires authentication, configure these three settings:

SMTP_AUTH_METHOD=plain
SMTP_AUTH_USER=YourUsername
SMTP_AUTH_PASS=YourPassword

The only supported authentication methods at this time are “login” and “plain”.

Emails come from noreply@runzero.com by default. To change the sender, set the FROM_EMAIL option:

FROM_EMAIL=runzero@yourcompany.int

Hostname and port

The RUNZERO_CONSOLE variable is the address that users and deployed Explorers use to connect to the platform. runZero also uses it to build inbound links, configure deployed Explorers, and generate the default self-signed TLS certificate.

RUNZERO_CONSOLE=https://{IP ADDRESS OR HOSTNAME}:443

Changing it may require regenerating the TLS certificate and redeploying Explorers.

runzeroctl generate-certificate

To run runZero on a different port, set CONSOLE_PORT. This is the port the console listens on; users and Explorers still connect to the RUNZERO_CONSOLE value, so in most cases the two should match.

CONSOLE_PORT=443

TLS configuration

runZero generates a self-signed TLS certificate and serves all web requests using HTTP over TLS. The standard configuration uses a self-signed certificate stored in the filesystem:

TLS=true
TLS_CERT=/etc/runzero/certs/cert.pem
TLS_KEY=/etc/runzero/certs/key.pem

The certificate and key file are PEM encoded, and you can replace them with any valid certificate. Any new certificate must list the value of RUNZERO_CONSOLE among its Subject Alternative Names.

The key file must be unencrypted (not password protected). If it has a passphrase, remove it with OpenSSL. For example:

# RSA key
openssl rsa -in key.pem -out newkey.pem
# DSA key
openssl dsa -in key.pem -out newkey.pem

Behind a TLS-terminating reverse proxy (AWS ELB, nginx, etc), you can disable TLS at the application level:

TLS=false

The web interface is then reachable over plain HTTP, but Explorers refuse to connect to a plain HTTP port, and features like WebAuthn MFA only work when the site is accessed through TLS.

You can also set specific TLS versions and ciphers.

TLS versions are chosen by minimum and maximum:

TLS_VERSION_MIN=1.2
TLS_VERSION_MAX=1.3

TLS ciphers may be chosen by profile name:

  • default: a set of strong ciphers, a good fit for most configurations
  • nist80052: a set of strong ciphers, approved in NIST 800-52r2
  • nist80052-aes256: a set of strong ciphers, approved in NIST 800-52r2, restricted to AES-256 variants

TLS 1.3 ciphers work differently, so if you need a specific set of ciphers, set both TLS_VERSION_MIN and TLS_VERSION_MAX to 1.2. For example, to restrict runZero to only the NIST 800-52r2 approved ciphers using AES-256:

TLS_VERSION_MIN=1.2
TLS_VERSION_MAX=1.2
TLS_CIPHERS=nist80052-aes256

TLS ciphers may also be chosen as a comma-separated list of cipher constants.

Certificate authorities (CAs)

The server validates TLS connections against the system-installed certificate authorities and an internal CA certificate bundle. By default, both the system roots and the bundled roots are considered for every secure TLS connection.

  • Set RUNZERO_TLS_IGNORE_SYSTEM_ROOTCA to true to ignore the system CA roots.
  • Set RUNZERO_TLS_IGNORE_EMBEDDED_ROOTCA to true to ignore the bundled CA roots.
  • Set RUNZERO_TLS_ADDITIONAL_ROOTCA to the path of a file containing additional CA roots in PEM format.

Database configuration

runZero keeps all platform data in a PostgreSQL database, except raw scan files, change reports, and images processed from scans. By default, runZero configures a local PostgreSQL server on the same system, with a random password and without TLS encryption:

DATABASE_URL=postgres://runzero:{DB_PASSWORD}@127.0.0.1:5432/runzero?sslmode=disable

If you prefer a separate database, any PostgreSQL server running 12.x or newer should work. TLS (sslmode=require) should be enabled whenever the database server is not local.

For high-throughput environments, you can change the default database pool (connection count):

DATABASE_POOL_COUNT=50

Proxy configuration

runZero makes outbound connections to receive platform updates (in online mode), to reach third-party APIs, and to deliver webhooks for notifications. If those connections need a proxy server, set:

HTTPS_PROXY=host:port

You can set a separate proxy for AWS connections; it takes precedence over HTTPS_PROXY:

HTTPS_PROXY_AWS=host-for-aws-services:port

Besides standard HTTP proxies, you can use a SOCKS proxy by specifying a URL like:

HTTPS_PROXY=socks5://socks.example.com:1080

Storage configuration

runZero stores raw scan data, change reports, and images retrieved from assets in local file storage. The storage directory must be owned by the runzero user and mounted below the /opt/runzero path.

RUNZERO_STORAGE_MODE=local
RUNZERO_STORAGE_PATH=/opt/runzero/storage

Files in the storage directory are split into two groups, assets and scans. To rename them, set:

ASSET_BUCKET=assets
SCAN_BUCKET=scans

To use AWS S3 for file storage instead, set:

RUNZERO_STORAGE_MODE=s3
ASSET_BUCKET=company-runzero-assets
SCAN_BUCKET=company-runzero-scans

For a non-AWS backend that is compatible with the S3 API, use the same AWS and bucket variables, override AWS_REGION, and set AWS_ENDPOINT_URL_S3 or RUNZERO_STORAGE_ENDPOINT to the endpoint. Reach out to runZero support if you run into trouble with the endpoint configuration.

If the S3 buckets are in a different region than the environment, set RUNZERO_STORAGE_REGION to the buckets’ region.

With S3, AWS must also be configured with at least the AWS_REGION variable set, even when a non-AWS backend is enabled.

Secret configuration

runZero secures the platform with three randomly generated secret tokens. Each is a hexadecimal string made from 16 random bytes, and OpenSSL can generate compatible values:

$ openssl rand -hex 16

The authentication key for local storage HMAC operations can be rotated as long as you restart the service afterwards:

RUNZERO_STORAGE_KEY_SECRET={SECRET_32_HEX}

The session secret key signs and validates browser session cookies. You can rotate it, but doing so invalidates all existing web sign-ins:

SESSION_SECRET={SECRET_32_HEX}

The DB key encrypts sensitive fields (user password hashes). It cannot be rotated without breaking password authentication: if it changes, users must reset their password from the command line or the web interface using email before they can sign back in:

DB_KEY={SECRET_32_HEX}

AWS configuration

The AWS region is required:

AWS_REGION=us-east-1

The Access Key ID and Secret must be valid and belong to a user with read-write access to the S3 buckets and read-only access to Secrets Manager.

AWS_ACCESS_KEY_ID=AKIA....
AWS_SECRET_ACCESS_KEY=SECRET....

runZero can load almost any configuration setting from AWS Secrets Manager at startup. The Secrets Manager entries should match the key names in the configuration file. Set the secret name with:

AWS_SECRETS_MANAGER_KEY=runzero/production

Most AWS CLI environment variables are also available alongside these variables for finer tuning.

These settings change where the Explorer and scanner binaries are stored. They should still live under /opt/runzero, or the service can’t load them:

RUNZERO_RELEASE_DIR=/opt/runzero/agent/
RUNZERO_SCANNER_RELEASE_DIR=/opt/runzero/scanner/

Content security policy

With a non-standard S3 configuration (or an S3-like deployment such as minio), the Content Security Policy headers must allow external image loads.

Set CSP_IMAGES to one or more (comma-delimited) external image sources:

CSP_IMAGES=https://*.custom-storage-backend.lan

These CSP settings are also available:

CSP_SCRIPTS=https://*.myscripts.lan
CSP_FONTS=https://*.myfonts.lan
CSP_STYLES=https://*.mystyles.lan

Logging

The self-hosted runZero console writes its logging output to standard output. On Linux, systemd picks this up and stores it in the journal, where you can query it with the journalctl tool. For example, this command shows the most recent hour of logs, newest first:

journalctl --unit=runzero-console --since=-1hour --reverse

You can pipe the journalctl output to a text file to send to runZero support.

You can configure the systemd logging subsystem to send log messages to a local syslog daemon as well as the journal. Once logs are in syslog, you can forward them across the network to remote logging servers using the standard syslog protocol. Some Linux distributions, such as RHEL, forward logs from systemd to syslog by default. Others, such as Ubuntu and Debian, don’t include a syslog daemon in their default minimal server installs.

To make systemd send logs to syslog, use the ForwardToSyslog option in /etc/systemd.conf. Alternatively, some syslog daemons can read the systemd journal themselves; rsyslog, for example, has imjournal.

runZero writes its logs in CEE-enhanced JSON format, which works with rsyslog, syslog-ng, DataDog, and other common logging tools. For rsyslog, the mmjsonparse module can filter the logs on individual JSON fields and forward them to ElasticSearch or other JSON databases.

Set LOG_MAX_LENGTH in runZero’s config file to cap the length of each log line, in bytes of UTF-8 text. A value of 0 means no limit, and other values below 480 are treated as 480. When truncating, runZero tries to preserve the most useful logging fields, and the result stays valid JSON. The limit applies before systemd or syslog adds anything to the start of the line.

Set LOG_FORMAT to text to turn off the CEE and JSON format and log in plain text. For example:

LOG_FORMAT=text
LOG_MAX_LENGTH=512

HTTP timeouts

Three configuration variables set the built-in web server’s HTTP idle, read, and write timeouts. The defaults are below and don’t usually need changing.

HTTP_IDLE_TIMEOUT_MINUTES=3
HTTP_READ_TIMEOUT_MINUTES=60
HTTP_WRITE_TIMEOUT_MINUTES=720

Concurrent processing

The runZero Console can process more than one completed task at a time when RUNZERO_CRUNCHER_INSTANCES is set to a value greater than 1. Tasks run concurrently only when they belong to different organizations, or to different sites within the same organization when the task doesn’t require cross-site asset merging. Most third-party connectors and integrations require cross-site merging, so they can’t take advantage of concurrent site processing within one organization. Resource requirements for concurrent task processing scale linearly with the instance count.

This example lets the console process up to four concurrent tasks across all organizations:

RUNZERO_CRUNCHER_INSTANCES=4

Custom JavaScript

The self-hosted runZero Console can run your own JavaScript on its web pages. Add your JavaScript to /opt/runzero/etc/custom.js. The custom.js file doesn’t exist until you create it in the /opt/runzero/etc folder.

Then enable the feature by adding this variable to your configuration:

RUNZERO_CUSTOM_JS=true

HTTP headers

You can disable the security headers sent by the runZero Console as needed with these options:

# Disable Strict-Transport-Security
RUNZERO_DISABLE_HSTS=true

# Disable X-Frame-Options
RUNZERO_DISABLE_HXFO=true

# Disable X-Content-Type-Options
RUNZERO_DISABLE_HXCTO=true

# Disable X-XSS-Protection
RUNZERO_DISABLE_HXXP=true

# Disable Referrer-Policy
RUNZERO_DISABLE_HRP=true

# Disable Content-Security-Policy
RUNZERO_DISABLE_HCSP=true

# Disable CSRF-Protection
RUNZERO_DISABLE_CSRF=true

API availability

This setting controls whether public APIs such as /health are enabled:

# Disable all unauthenticated API endpoints (/health)
RUNZERO_DISABLE_PUBLIC_APIS=true

Disabling entitlements

You can force-disable any license entitlement for the entire instance by setting RUNZERO_DISABLE_<ENTITLEMENT> to true, where <ENTITLEMENT> is the uppercased entitlement name. This overrides the license: it can only remove an entitlement, never grant one, and it applies to every account and organization on the instance.

For example, to disable autonomous (autoscan) discovery everywhere:

RUNZERO_DISABLE_AUTOSCAN=true

The full set of supported variables is below, one per entitlement. Each is commented out; set the value to true to disable that entitlement.

# Asset ownership
# RUNZERO_DISABLE_ASSET_OWNERSHIP=true

# Risky assets
# RUNZERO_DISABLE_RISKY_ASSETS=true

# Passive monitoring, traffic sampling, and PCAP import
# RUNZERO_DISABLE_PASSIVE_MONITORING=true

# Manage Explorer groups
# RUNZERO_DISABLE_EXPLORER_GROUPS=true

# Goal tracking
# RUNZERO_DISABLE_GOAL_TRACKING=true

# Unlimited organizations (not just one)
# RUNZERO_DISABLE_ORGS_UNLIMITED=true

# Unlimited projects (not just one)
# RUNZERO_DISABLE_PROJECTS_UNLIMITED=true

# Continuous scanning and variable TTL
# RUNZERO_DISABLE_SCANS_UNLIMITED=true

# Concurrent scanning on Explorers
# RUNZERO_DISABLE_SCANS_CONCURRENT=true

# Subnet ping and host ping (sampling) modes
# RUNZERO_DISABLE_SCANS_SAMPLING=true

# Advanced scan targeting
# RUNZERO_DISABLE_SCANS_TARGETING=true

# Autonomous (autoscan) discovery scanning
# RUNZERO_DISABLE_AUTOSCAN=true

# AI features
# RUNZERO_DISABLE_AI=true

# Organization API access
# RUNZERO_DISABLE_API_ORG=true

# Account (client) API access
# RUNZERO_DISABLE_API_ACCOUNT=true

# Adjust organization data retention settings
# RUNZERO_DISABLE_DATA_RETENTION=true

# Rule engine processing
# RUNZERO_DISABLE_RULES_BASIC=true

# Basic reporting
# RUNZERO_DISABLE_REPORTS_BASIC=true

# Disable external (shareable, email-verified) report links
# RUNZERO_DISABLE_DISABLE_EXTERNAL_REPORTING=true

# ServiceNow export APIs
# RUNZERO_DISABLE_INT_SERVICENOW=true

# Splunk sync APIs
# RUNZERO_DISABLE_INT_SPLUNK=true

# Cisco export APIs
# RUNZERO_DISABLE_INT_CISCO=true

# HP export APIs
# RUNZERO_DISABLE_INT_HP=true

# Censys search import
# RUNZERO_DISABLE_INT_CENSYS=true

# CrowdStrike import
# RUNZERO_DISABLE_INT_CROWDSTRIKE=true

# Microsoft 365 Defender import
# RUNZERO_DISABLE_INT_MS365DEFENDER=true

# Miradore import
# RUNZERO_DISABLE_INT_MIRADORE=true

# Nessus import
# RUNZERO_DISABLE_INT_NESSUS=true

# Rapid7 Nexpose import
# RUNZERO_DISABLE_INT_RAPID7=true

# SentinelOne import
# RUNZERO_DISABLE_INT_SENTINELONE=true

# VMware API import
# RUNZERO_DISABLE_INT_VMWARE=true

# Tenable vulnerability management
# RUNZERO_DISABLE_INT_TENABLE=true

# Prisma Cloud integration
# RUNZERO_DISABLE_INT_PRISMA=true

# Tenable Security Center integration
# RUNZERO_DISABLE_INT_TENABLE_SECURITY_CENTER=true

# Rapid7 InsightVM vulnerability management
# RUNZERO_DISABLE_INT_INSIGHTVM=true

# Qualys vulnerability management
# RUNZERO_DISABLE_INT_QUALYS=true

# Shodan integration
# RUNZERO_DISABLE_INT_SHODAN=true

# Azure AD import
# RUNZERO_DISABLE_INT_AZURE_AD=true

# LDAP import
# RUNZERO_DISABLE_INT_LDAP=true

# Intune import
# RUNZERO_DISABLE_INT_INTUNE=true

# Google Workspace import
# RUNZERO_DISABLE_INT_GOOGLE_WORKSPACE=true

# Wiz import
# RUNZERO_DISABLE_INT_WIZ=true

# Meraki integration
# RUNZERO_DISABLE_INT_MERAKI=true

# Microsoft MECM integration
# RUNZERO_DISABLE_INT_MECM=true

# Tanium integration
# RUNZERO_DISABLE_INT_TANIUM=true

# NetBox integration
# RUNZERO_DISABLE_INT_NETBOX=true

# Dragos integration
# RUNZERO_DISABLE_INT_DRAGOS=true

# Jira integration
# RUNZERO_DISABLE_INT_JIRA=true

# Palo Alto Networks integration
# RUNZERO_DISABLE_INT_PAN=true

# Manage directory users
# RUNZERO_DISABLE_DIRECTORY_USERS=true

# Manage directory groups
# RUNZERO_DISABLE_DIRECTORY_GROUPS=true

# Cloud connections (AWS, GCP, Azure)
# RUNZERO_DISABLE_INT_CLOUD=true

# Create custom integrations
# RUNZERO_DISABLE_INT_CUSTOM_INTEGRATIONS=true

# Custom integration scripts
# RUNZERO_DISABLE_INT_CUSTOM_INTEGRATION_SCRIPTS=true

# Advanced reports
# RUNZERO_DISABLE_REPORTS_ADVANCED=true

# Self-hosted platform
# RUNZERO_DISABLE_SELFHOSTED=true

# Bulk user management
# RUNZERO_DISABLE_BULK_USER_MANAGEMENT=true

# Group expiration
# RUNZERO_DISABLE_GROUP_EXPIRATION=true

# SSO group mapping
# RUNZERO_DISABLE_GROUP_MAPPING=true

# Hosted external scans (hosted zones)
# RUNZERO_DISABLE_HOSTED_ZONES=true

# Rebrand
# RUNZERO_DISABLE_REBRAND=true

# Knowledge base sidebar
# RUNZERO_DISABLE_KNOWLEDGE_BASE=true

# Customizable dashboards
# RUNZERO_DISABLE_CUSTOM_DASHBOARDS=true

# Multiple customizable dashboards
# RUNZERO_DISABLE_MULTIPLE_DASHBOARDS=true

# Query builder
# RUNZERO_DISABLE_QUERY_BUILDER=true

# Metadata minimization
# RUNZERO_DISABLE_METAMIN=true

# Offline mode
# RUNZERO_DISABLE_OFFLINE=true

# Certificate inventory
# RUNZERO_DISABLE_CERTIFICATE_INVENTORY=true

# Findings inventory
# RUNZERO_DISABLE_FINDINGS=true

# Risk management event rule types
# RUNZERO_DISABLE_RISK_EVENTS=true

# Baseline goals
# RUNZERO_DISABLE_BASELINE_GOALS=true

# Immediate analysis recalculation on rapid response publish
# RUNZERO_DISABLE_IMMEDIATE_RAPID_RESPONSE_RECALC=true

# Create new sites
# RUNZERO_DISABLE_CREATE_SITES=true

# Suppress vulnerabilities, vulnerability groups, and findings
# RUNZERO_DISABLE_SUPPRESSION=true

# Issues
# RUNZERO_DISABLE_ISSUES=true

# Archive vulnerabilities
# RUNZERO_DISABLE_ARCHIVE_VULNERABILITIES=true

Unofficial CPEs

When runZero fingerprints an asset’s operating system, it generates a CPE. If the NIST database has no official match, runZero generates an unofficial CPE by default. To turn this off, set RUNZERO_GENERATE_UNOFFICIAL_CPE to false:

RUNZERO_GENERATE_UNOFFICIAL_CPE=false

Unofficial CPEs include r0_unofficial in the other field of the CPE by default. You can change this to any alphanumeric-constrained tag of up to 32 characters:

RUNZERO_UNOFFICIAL_CPE_TAG=custom_unoffical_tag

Rewriting cve.org URLs

To rewrite the cve.org links in the product UI to point at an internal mirror or another site, set the environment variable RUNZERO_REPLACE_URL_PREFIX_CVEORG. For example:

RUNZERO_REPLACE_URL_PREFIX_CVEORG=https://cve.mirror.local/cve/

With this example, cve.org URLs in the product interface are rewritten to https://cve.mirror.local/cve/$1, where $1 is replaced with the CVE identifier, such as CVE-12345.

Permissions

Installing and managing the self-hosted platform from the command line requires root access.

The platform service (runzero-console) runs as root and spawns a worker subprocess that runs as the runzero user account inside a chroot environment (/opt/runzero). All substantive work happens in that isolated subprocess. Older installations use rumble instead of runzero in directory, file, and user names.

The self-hosted platform uses these filesystem locations:

/etc/runzero

Path Owner Permission Notes
/etc/runzero root 0700 Configuration files and certificates
/etc/runzero/config root 0600 A plain-text configuration file
/etc/runzero/certs root 0700 A directory containing the TLS certificate and key
/etc/runzero/certs/cert.pm root 0600 The TLS certificate in PEM format
/etc/runzero/certs/key.pm root 0600 The TLS certificate private key in PEM format

/opt/runzero

Path Owner Permission Notes
/opt/runzero/tmp runzero 0755 A temporary directory
/opt/runzero/storage runzero 0700 Contains asset and scan artifacts
/opt/runzero/console root 0755 Contains the platform executable
/opt/runzero/console/runzero-console.bin root 0755 The platform executable
/opt/runzero/agent root 0755 Contains the Explorer binaries
/opt/runzero/agent/runzero-agent-* root 0755 The Explorer binaries
/opt/runzero/scanner root 0755 Contains the CLI binaries
/opt/runzero/agent/runzero-scanner-* root 0755 The CLI binaries
/opt/runzero/proc root 0755 Contains copies of system /proc files
/opt/runzero/proc/cpuinfo root 0644 A copy of /proc/cpuinfo
/opt/runzero/proc/meminfo root 0644 A copy of /proc/meminfo
/opt/runzero/proc/version root 0644 A copy of /proc/version
/opt/runzero/etc root 0755 Contains copies of system files
/opt/runzero/etc/resolv.conf root 0644 A copy of /etc/resolv.conf
/opt/runzero/etc/hosts root 0644 A copy of /etc/hosts
/opt/runzero/etc/ca-certificates.crt root 0644 A copy of the system root CA store
/opt/runzero/etc/runzero runzero 0700 Contains instance identifiers
/opt/runzero/etc/runzero/cruncher.id runzero 0700 A unique ID to identify the cruncher instance
/opt/runzero/etc/runzero/hub.id runzero 0700 A unique ID to identify the hub instance
/opt/runzero/config root 0700 Unused today

Backup and restoration

You can back up and restore your runZero installation and data to preserve your configuration.

runZero data backup

To back up a self-hosted installation, archive the file system and the database.

The file system archive includes these paths:

  • /etc/runzero
  • /opt/runzero
  • /lib/systemd/system/runzero-console.service
  • /etc/systemd/system/multi-user.target.wants/runzero-console.service
  • /usr/bin/runzeroctl

A sample file system backup command:

# tar zcvf runzero-backup-fs.tar.gz /etc/runzero/ /opt/runzero/ \
/lib/systemd/system/runzero-console.service \
/etc/systemd/system/multi-user.target.wants/runzero-console.service \
/usr/bin/runzeroctl

Back up the PostgreSQL database separately. A sample command:

# sudo su - postgres
$ pg_dumpall -f runzero.sql && gzip runzero.sql

runZero data restoration

To restore the runZero install:

  1. Stop any running runZero service:
# runzeroctl stop
  1. Unpack the filesystem archive:
# tar -C / -zxvf /path/to/runzero-backup-fs.tar.gz
  1. Restore the PostgreSQL database:
# sudo su - postgres
$ dropdb runzero; gzip -dc runzero.sql.gz | psql
  1. Restart the runZero service:
sudo systemctl restart runzero-console

Support and debugging

The runzeroctl command includes a debugging tool that collects diagnostics from your server and assembles them into a zip file you can send to support. If support asks for it, run:

runzeroctl diagnostics run-script

Data is written to /opt/runzero/collector.

To examine the script before running it, save a copy to the current directory instead:

runzeroctl diagnostics write-script

For more on the diagnostics collection script, see Self-hosted troubleshooting.

Manual migrations

Starting with version 4.0.240221.0, the runZero self-hosted upgrade runs migrations before restarting the service. If you run an older version and want to avoid downtime while upgrading a single-node self-hosted installation, use these steps:

  1. Get the self-hosted download link from the runZero SaaS.

  2. Download the file manually to your self-hosted systems:

$ curl -o platform.bin https://console.runzero.com/....../runzero-platform.bin

  1. Mark the file executable and run it with the task db:migrate parameter:

$ chmod u+x platform.bin; ./platform.bin task db:migrate

  1. Once the migrations finish, install the update as usual:

$ runzeroctl update

Updated