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](https://osquery.readthedocs.io/en/stable/deployment/remote/)
- To serve the [Kolide web application](https://kolide.co/product), 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](https://jwt.io/) 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.
The [JWT](https://jwt.io/) key to use when signing and validating session keys. If this value is not specified the Kolide server will fail to start and a randomly generated key will be provided for use.
