<commit_before>Configuring The Fleet Binary
=============================

For information on how to run the `fleet` binary, detailed usage information can be found by running `fleet --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 Fleet application!

## High-level configuration overview

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

Your Fleet server's two main purposes are:

- To serve as your [osquery TLS server](https://osquery.readthedocs.io/en/stable/deployment/remote/)
- To serve the [Fleet web application](https://kolide.com/fleet), which allows you to manage osquery configuration, query hosts, perform interesting analytics, etc.

The Fleet server allows you persist configuration, manage users, etc. Thus, it needs a database. Fleet uses MySQL and requires you to supply configurations to connect to a MySQL server. Fleet 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, Fleet also requires that you supply Redis connention configurations.

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

- The TLS certificates that Fleet should use to terminate TLS.
- The [JWT](https://jwt.io/) Key which is used to sign and verify session tokens.

Since Fleet 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 `fleet` binary contains several "commands". Similarly to how `git` has many commands (`git status`, `git commit`, etc), the `fleet` binary accepts the following commands:

- `fleet prepare db`
- `fleet serve`
- `fleet version`
- `fleet 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 Fleet are equivalent:

#### Using only CLI flags

```
$ /usr/bin/fleet serve \
  --mysql_address=127.0.0.1:3306 \
  --mysql_database=kolide \
  --mysql_username=root \
  --mysql_password=<PASSWORD> \
  --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=<PASSWORD> \
  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/fleet serve
```

#### Using a config file

```
$ echo '
mysql:
  address: 127.0.0.1:3306
  database: kolide
  username: root
  password: <PASSWORD>
redis:
  address: 127.0.0.1:6379
server:
  cert: /tmp/server.cert
  key: /tmp/server.key
logging:
  json: true
' > /tmp/kolide.yml
$ fleet 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
```
<commit_msg>Add jwt_key to the example Fleet configurations (#1993)<commit_after>Configuring The Fleet Binary
=============================

For information on how to run the `fleet` binary, detailed usage information can be found by running `fleet --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 Fleet application!

## High-level configuration overview

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

Your Fleet server's two main purposes are:

- To serve as your [osquery TLS server](https://osquery.readthedocs.io/en/stable/deployment/remote/)
- To serve the [Fleet web application](https://kolide.com/fleet), which allows you to manage osquery configuration, query hosts, perform interesting analytics, etc.

The Fleet server allows you persist configuration, manage users, etc. Thus, it needs a database. Fleet uses MySQL and requires you to supply configurations to connect to a MySQL server. Fleet 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, Fleet also requires that you supply Redis connention configurations.

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

- The TLS certificates that Fleet should use to terminate TLS.
- The [JWT](https://jwt.io/) Key which is used to sign and verify session tokens.

Since Fleet 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 `fleet` binary contains several "commands". Similarly to how `git` has many commands (`git status`, `git commit`, etc), the `fleet` binary accepts the following commands:

- `fleet prepare db`
- `fleet serve`
- `fleet version`
- `fleet 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 Fleet are equivalent:

#### Using only CLI flags

```
$ /usr/bin/fleet serve \
  --mysql_address=127.0.0.1:3306 \
  --mysql_database=kolide \
  --mysql_username=root \
  --mysql_password=<PASSWORD> \
  --redis_address=127.0.0.1:6379 \
  --server_cert=/tmp/server.cert \
  --server_key=/tmp/server.key \
  --logging_json \
  --auth_jwt_key=changeme
```

#### Using only environment variables

```
$ KOLIDE_MYSQL_ADDRESS=127.0.0.1:3306 \
  KOLIDE_MYSQL_DATABASE=kolide \
  KOLIDE_MYSQL_USERNAME=root \
  KOLIDE_MYSQL_PASSWORD=<PASSWORD> \
  KOLIDE_REDIS_ADDRESS=127.0.0.1:6379 \
  KOLIDE_SERVER_CERT=/tmp/server.cert \
  KOLIDE_SERVER_KEY=/tmp/server.key \
  KOLIDE_LOGGING_JSON=true \
  KOLIDE_AUTH_JWT_KEY=changeme \
  /usr/bin/fleet serve
```

#### Using a config file

```
$ echo '
mysql:
  address: 127.0.0.1:3306
  database: kolide
  username: root
  password: <PASSWORD>
redis:
  address: 127.0.0.1:6379
server:
  cert: /tmp/server.cert
  key: /tmp/server.key
logging:
  json: true
auth:
  jwt_key: changeme
' > /tmp/kolide.yml
$ fleet 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
```

{'fraction_non_alphanumeric': 0.09363198333116292, 'fraction_numerical': 0.018752441724182837, 'mean_word_length': 4.206779661016949, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 11, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 14, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4147736', 'n_tokens_mistral': 2368, 'n_tokens_neox': 2218, 'n_words': 924}