fleet/docs/infrastructure/configuring-the-kolide-binary.md

Configuring The Kolide Binary

For information on how to run the kolide binary, detailed usage information can be found by running kolide --help. This document is a more detailed version of the information presented in the help output text. If you prefer to use a CLI instead of a web browser, we hope that you like the binary interface to the Kolide application!

High-level configuration overview

To get the most out of running the Kolide server, it is helpful to establish a mutual understanding of what the desired architecture looks like and what it's trying to accomplish.

Your Kolide server's two main purposes are:

• To serve as your osquery TLS server
• To serve the Kolide web application, which allows you to manage osquery configuration, query hosts, perform interesting analytics, etc.

The Kolide server allows you persist configuration, manage users, etc. Thus, it needs a database. Kolide uses MySQL and requires you to supply configurations to connect to a MySQL server. Kolide also uses Redis to perform some more high-speed data access action throughout the lifecycle of the application (for example, distributed query result ingestion). Thus, Kolide also requires that you supply Redis connention configurations.

Since Kolide is a web application, when you run Koldie there are some other configurations that are worth defining, such as:

• The TLS certificates that Kolide should use to terminate TLS.
• The JWT Key which is used to sign and verify session tokens.

Since Kolide is an osquery TLS server, you are also able to define configurations that can customize your experience there, such as:

• The destination of the osquery status and result logs on the local filesystem
• Various details about the refresh/check-in intervals for your hosts

Commands

The kolide binary contains several "commands". Similarly to how git has many commands (git status, git commit, etc), the kolide binary accepts the following commands:

• kolide prepare db
• kolide serve
• kolide version
• kolide config_dump

Options

How do you specify options?

In order of precedence, options can be specified via:

• A configuration file (in YAML format)
• Environment variables
• Command-line flags

For example, all of the following ways of launching Kolide are equivalent:

Using only CLI flags

$ /usr/bin/kolide serve \
  --mysql_address=127.0.0.1:3306 \
  --mysql_database=kolide \
  --mysql_username=root \
  --mysql_password=toor \
  --redis_address=127.0.0.1:6379 \
  --server_cert=/tmp/server.cert \
  --server_key=/tmp/server.key \
  --logging_json

Using only environment variables

$ KOLIDE_MYSQL_ADDRESS=127.0.0.1:3306 \
  KOLIDE_MYSQL_DATABASE=kolide \
  KOLIDE_MYSQL_USERNAME=root \
  KOLIDE_MYSQL_PASSWORD=toor \
  KOLIDE_REDIS_ADDRESS=127.0.0.1:6379 \
  KOLIDE_SERVER_CERT=/tmp/server.cert \
  KOLIDE_SERVER_KEY=/tmp/server.key \
  KOLIDE_LOGGING_JSON=true \
  /usr/bin/kolide serve

Using a config file

$ echo '
mysql:
  address: 127.0.0.1:3306
  database: kolide
  username: root
  password: toor
redis:
  address: 127.0.0.1:6379
server:
  cert: /tmp/server.cert
  key: /tmp/server.key
logging:
  json: true
' > /tmp/kolide.yml
$ kolide serve --config /tmp/kolide.yml

What are the options?

Note that all option names can be converted consistently from flag name to environment variable and visa-versa. For example, the --mysql_address flag would be the KOLIDE_MYSQL_ADDRESS. Further, specifying the mysql_address option in the config would follow the pattern:

mysql:
  address: 127.0.0.1:3306

Basically, just capitalize the option and prepend KOLIDE_ to it in order to get the environment variable. The conversion works the same the opposite way.

MySQL

mysql_address

The address of the MySQL server which Kolide should connect to. Include the hostname and port.

• Default value: localhost:3306

• Environment variable: KOLIDE_MYSQL_ADDRESS

• Config file format:

  mysql:
  	address: localhost:3306
  

mysql_database

The name of the MySQL database which Kolide will use.

• Default value: kolide

• Environment variable: KOLIDE_MYSQL_DATABASE

• Config file format:

  mysql:
  	database: kolide
  

mysql_username

The username to use when connecting to the MySQL instance.

• Default value: kolide

• Environment variable: KOLIDE_MYSQL_USERNAME

• Config file format:

  mysql:
  	username: kolide
  

mysql_password

The password to use when connecting to the MySQL instance.

• Default value: kolide

• Environment variable: KOLIDE_MYSQL_PASSWORD

• Config file format:

  mysql:
  	password: kolide
  

Redis

redis_address

The address of the Redis server which Kolide should connect to. Include the hostname and port.

• Default value: localhost:3306

• Default value: localhost:6379

• Environment variable: KOLIDE_REDIS_ADDRESS

• Config file format:

  redis:
  	address: 127.0.0.1:7369
  

redis_password

The password to use when connecting to the Redis instance.

• Default value: <empty>

• Environment variable: KOLIDE_REDIS_PASSWORD

• Config file format:

  redis:
  	password: foobar
  

Server

server_address

The address to serve the Kolide webserver.

• Default value: 0.0.0.0:8080

• Environment variable: KOLIDE_SERVER_ADDRESS

• Config file format:

  server:
  	address: 0.0.0.0:443
  

server_cert

The TLS cert to use when terminating TLS.

• Default value: ./tools/osquery/kolide.crt

• Environment variable: KOLIDE_SERVER_CERT

• Config file format:

  server:
  	cert: /tmp/kolide.crt
  

server_key

The TLS key to use when terminating TLS.

• Default value: ./tools/osquery/kolide.key

• Environment variable: KOLIDE_SERVER_KEY

• Config file format:

  server:
  	key: /tmp/kolide.key
  

server_tls

Whether or not the server should be served over TLS.

• Default value: true

• Environment variable: KOLIDE_SERVER_TLS

• Config file format:

  server:
  	tls: false
  

Auth

auth_jwt_key

The JWT key to use when signing and validating session keys.

• Default value: CHANGEME

• Environment variable: KOLIDE_AUTH_JWT_KEY

• Config file format:

  auth:
  	jwt_key: JVnKw7CaUdJjZwYAqDgUHVYP
  

auth_bcrypt_cost

The bcrypt cost to use when hashing user passwords.

• Default value: 12

• Environment variable: KOLIDE_AUTH_BCRYT_COST

• Config file format:

  auth:
  	bcrypt_cost: 14
  

auth_salt_key_size

The key size of the salt which is generated when hashing user passwords.

• Default value: 24

• Environment variable: KOLIDE_AUTH_SALT_KEY_SIZE

• Config file format:

  auth:
  	salt_key_size: 36
  

App

app_token_key

Secret key for generating invite and reset tokens.

• Default value: CHANGEME

• Environment variable: KOLIDE_APP_TOKEN_KEY

• Config file format

  app:
  	token_key: JVnKw7CaUdJjZwYAqDgUHVYP
  

app_token_key_size

Size of generated app tokens.

• Default value: 24

• Environment variable: KOLIDE_APP_TOKEN_KEY_SIZE

• Config file format:

  app:
  	token_key_size: 36
  

app_invite_token_validity_period

How long invite tokens should be valid for.

• Default value: 5 days

• Environment variable: KOLIDE_APP_TOKEN_VALIDITY_PERIOD

• Config file format:

  app:
  	invite_token_validity_period: 1d
  

Session

session_key_size

The size of the session key.

• Default value: 64

• Environment variable: KOLIDE_SESSION_KEY_SIZE

• Config file format:

  session:
  	key_size: 48
  

session_duration

The amount of time that a session should last for.

• Default value: 90 days

• Environment variable: KOLIDE_SESSION_DURATION

• Config file format:

  session:
  	duration: 30d
  

Osquery

osquery_node_key_size

The size of the node key which is negotiated with osqueryd clients.

• Default value: 24

• Environment variable: KOLIDE_OSQUERY_NODE_KEY_SIZE

• Config file format:

  osquery:
  	node_key_size: 36
  

osquery_status_log_file

The path which osquery status logs will be logged to.

• Default value: /tmp/osquery_status

• Environment variable: KOLIDE_OSQUERY_STATUS_LOG_FILE

• Config file format:

  osquery:
  	status_log_file: /var/log/osquery/status.log
  

osquery_result_log_file

The path which osquery result logs will be logged to.

• Default value: /tmp/osquery_result

• Environment variable: KOLIDE_OSQUERY_RESULT_LOG_FILE

• Config file format:

  osquery:
  	result_log_file: /var/log/osquery/result.log
  

osquery_label_update_interval

The interval at which Kolide will ask osquery agents to update their results for label queries.

• Default value: 1h

• Environment variable: KOLIDE_OSQUERY_LABEL_UPDATE_INTERVAL

• Config file format:

  osquery:
  	label_query_update_interval: 30m
  

Logging

logging_debug

Whether or not to enable debug logging.

• Default value: false

• Environment variable: KOLIDE_LOGGING_DEBUG

• Config file format:

  logging:
  	debug: true
  

logging_json

Whether or not to log in JSON.

• Default value: false

• Environment variable: KOLIDE_LOGGING_JSON

• Config file format:

  logging:
  	json: true
  

logging_disable_banner

Whether or not to log the welcome banner.

• Default value: false

• Environment variable: KOLIDE_LOGGING_DISABLE_BANNER

• Config file format:

  logging:
  	diable_banner: true