Advanced Installation

This page includes instructions for monitoring only one server on a host running multiple databases, as well as manual installation instructions and instructions on installing the VividCortex agent using Chef, Puppet, or Ansible.

Specifying Hosts to Monitor

If you have multiple databases running on one host, the VividCortex agent will automatically detect and begin monitoring all of them automatically. However, if you want to monitor only some of those databases, you can instruct VividCortex to do so using configuration files.

First, download and install VividCortex. You will need your API token, which you can find in the web application by clicking “Add New Host” and then “Containerized”:

curl > install
sh install --token <API_TOKEN> --autostart --proxy=auto

To specify what database (or databases) to monitor, you will need the URI of your database(s). URIs have the following format:

Database URI syntax
MongoDB mongo://user:pass@
MySQL mysql://user:pass@
PostgreSQL postgres://user:pass@
Redis redis://:pass@

Replace user, pass, and port with the VividCortex username, the password for that user, and the database listening port. For PostgreSQL, you may also need to specify the name of the database to connect to, db. It is important to specify; this will instruct the agent to sniff all traffic to the entered port. If skip_name_resolve is active, login permissions will be necessary for If it is not active, it will likely be localhost but may be different.

Create /etc/vividcortex/vc-agent-007.conf and copy & paste the following, replacing <HOST URI> with the correct host URI. You can monitor multiple databases by specifying a comma-separated list of URIs.

    "use-drv-mongo": "false",
    "use-drv-mysql": "false",
    "use-drv-pgsql": "false",
    "use-drv-redis": "false",
    "drv-manual-query-capture": "sniff",
    "drv-manual-host-uri": "<HOST URI>[,<HOST URI>][,...]"  

Save this file, and start the VividCortex service with service vividcortex start, /etc/init.d/vividcortex start, or whatever is appropriate for your system. Log-in to the VividCortex web application, and you should see your database(s) appear in the Inventory page.

Contact Support in-app or by emailing if you have any questions.

Manual Installation

You will need your agent API token. You can find your token in the Add Host wizard from the Hosts dashboard. Open the wizard and click “Containerized,” which will show you the token.

For Linux and FreeBSD, this installation script will download the supervisor and install a VividCortex init script:

curl > install
sh install

For Windows, download and run the VividCortex installer. If you don’t have a packet capture driver in place, it will ask you to install one if you intend to do on-host monitoring. Please download Npcap. Make sure to use following configuration:

  • Automatically start the Npcap driver at boot time TICK
  • Support loopback traffic (“Npcap Loopback Adapter” will be created) TICK
  • Use DLT_NULL as the loopback interface link layer protocol instead of DLT_EN10MB TICK (default)
  • Restrict Npcap driver’s access to Administrators only TICK
  • Support raw 802.11 traffic (and monitor mode) for wireless adaptors UNTICK
  • Support 802.1Q VLAN tag when capturing and sending data TICK (default)
  • Install Npcap in WinPcap API-compatible mode TICK (default)

Then, for both Linux and Windows, continue the installation by waiting a few moments and then check the Hosts list in the VividCortex app. You should see the new OS host appear as the supervisor registers it.

The database-specific metrics agent needs a login to capture status metrics and the like. You can use an existing user, or create a new one, provided that it has the correct permissions. For MySQL, you could use:

CREATE USER vividcortex@'%' IDENTIFIED BY '<password here>';

For PostgreSQL:


For more information on the privileges the VividCortex user needs, and what data each privilege provides, see here.

After creating this user, find the host on the Hosts List and click on the settings gear to the right:

Edit Host

Enter the credentials in the dialog that appears.

Installing With Chef

We also provide a Chef cookbook that acts as an installation wrapper:

In order to use it, you must set the vividcortex['token'] attribute to your API token, and add its default recipe to your runlist. To find your API token, open the Add Hosts wizard and click “Containerized”; your API token will be displayed.

# Attribute example
    "vividcortex" => {
        "token" => "12345678901234567890123456789012"

# Add it to your runlist:
    "run_list": ["recipe[vividcortex]"]

Installing From RPM Packages

We can provide an RPM repository with packages for your convenience. The RPM does not contain a complete set of agent binaries; instead it contains a stable version of the agent (and any plugins) which will upgrade and install itself.

Installing From Puppet

We also provide a Puppet manifest for installing the repo, at This installs the repo and the agent. It accepts various parameters such as your API token.

If you do not use a configuration management system such as Ansible, Chef, or Puppet to generate the /etc/vividcortex/global.conf file, you must generate it manually. The agent will not work without it, and the RPM installation will fail as a result. The configuration file must be created before installing the RPM.

To install the repository and then the agent, run the following commands:

rpm -Uvh
yum install vividcortex-agents