Basic Console configuration

Notes

• This list only documents the most important options to configure the Console

Before performing the steps in this article please ensure that the Capsule8 Console and PostgreSQL has been successful installed (see Getting Started with the Console).

It is also important to note that for setting up the Capsule8 Console to connect to the PostgreSQL database, the frontend value must be correct. If the frontend value is set incorrectly, you will be able to view the Console but alerts will not show up without a page refresh. You will also see a banner that mentions connectivity issues.

Therefore, make sure that the frontend value is set to the same base URL you visit in the browser.

Configuring the Capsule8 Console

The Capsule8 Console may be configured with environment variables as well as a YAML file. To configure the Capsule8 Console please modify the file using your preferred editor and save.

/etc/capsule8/capsule8-console.yaml   #This is the file to configure to enable you view alerts using the example below

An example configuration file:

console:
  address: 0.0.0.0:80
  https_enabled: false
  frontend: http://capsule8.mycompany.com
  database: postgresql://console:password@db.mycompany.com:5432/console?sslmode=disable
  auth_session_key: YU0SCP8XNGB58C31BMIMSG9SBZAF97BDOOHN16RYKEMJYTH1G9X7QOPM3J05MXZ8
  csrf_auth_key: 980a0f64b82dcc4693b2ea0fea2c3b7095ef64b348e1690b2b3c75b1d71dba88
  strict_transport_security_header: false
  package_token: abcdef012314f29dc850878c6747b70f5b3ff01234567891092f0
  api_url: http://capsule8.internal.mycompany.com
  default_admin_password: legitimatepassword

(A comprehensive configuration file example can be found in /etc/capsule8/capsule8-console.example.yaml)

Setting the Address

address: # The combined host and port to serve from

Since version 4.5 it is recommended to use listen_address instead of address.

Setting the HTTP(s)

https_enabled: # See our HTTPS Documentation for more configuration options

Setting the Frontend

frontend: # Specify the public URL browser that you need to connect to

Setting the Database

database: # Postgres Connection URI, including host, database name, database user, and password

The environment variable CAPSULE8_CONSOLE_DATABASE may be used instead.

Setting the Auth Session

auth_session_key: # This should be the 64 character key used to sign JSON Web Tokens that authenticate users and services

The environment variable CAPSULE8_CONSOLE_AUTH_SESSION_KEY may be used instead.

Enabling HSTS (Optional)

This tells the console to enable HTTP Strict Transport Security. This security protection tells the browser "Only connect to me via HTTPS, never via HTTP." We recommend all users configure HTTPS and enable this setting.

strict_transport_security_header: true # Enable HSTS

The environment variable CAPSULE8_CONSOLE_STRICT_TRANSPORT_SECURITY_HEADER may be used instead.

Setting the Cross Site Request Forgery protection key (Optional)

This configures the signing key used for CSRF tokens, a security protection measure defending against third party websites stealing your Console account. Most Console deployments may safely omit this configuration; it defaults to a random string and will still protect your requests. Console deployments that run multiple Console processes behind a load balancer must configure each process with an identical console.csrf_auth_key.

csrf_auth_key: # This should be a 64 character key used to sign CSRF tokens

The environment variable CAPSULE8_CONSOLE_CSRF_AUTH_KEY may be used instead.

Setting the Package Token (Optional)

package_token: # (Optional) A token used to authenticate with Capsule8’s repository host, PackageCloud. Required for generating a Capsule8 Sensor install script from the Console GUI

The environment variable CAPSULE8_CONSOLE_PACKAGE_TOKEN may be used instead. Contact your Capsule8 representative for a token.

Setting the API URL (Optional)

This configuration is used by the console to craft URL's that are provided to sensors. Most Console deployments may safely omit this configuration; sensors added through the console will be configured to communicate with the console at the console.frontend address. The only time this needs to be set, is if your sensors must communicate with your Console at a different URL than your browser (for example, a deployment whose sensors are behind a different VPN than Console users' browsers.)

api_url: https://console.internal.company:9090 # (Optional) An address that is routable from outside the Console, it defaults to the frontend address

The environment variable CAPSULE8_CONSOLE_API_URL may be used instead.

Setting the Default Admin Password

As of Console 4.6.0, the hardcoded default password used in earlier versions is no longer permitted.

This configuration must be set for consoles that:

- Are version 4.6.0 or later, and,

- Have never changed the admin password from the hardcoded default.

default_admin_password: legitimatepassword # (Required once) The new admin password

Once the console starts, if the password was the default, it is set to this new value.

This configuration can and should be removed after the first successful admin login.

The environment variable CAPSULE8_CONSOLE_DEFAULT_ADMIN_PASSWORD may be used instead. If using an environment, avoid writing the password on a command line, so it doesn't get stored in your shell's history file. 

Setting the Crypto Key

This configuration must be set for consoles that:

- Are version 4.7.0 or later

The crypto key should be kept as long there are Integrations or any provider configured to the running Console.

crypto_key: # This should be a 64 character key

Restart the Console

Restart the console after changing the configuration file.

$ sudo systemctl restart capsule8-console

Check for status

$ sudo systemctl status capsule8-console

Check for Logs

$ sudo journalctl -efu capsule8-console