mirror of
https://github.com/empayre/fleet.git
synced 2024-11-06 17:05:18 +00:00
fc859321dc
* remove outdated config file description
`example_config.json` was removed in f11da7b05b but the documentation
was still there, this removes the description from the README as well.
* add a note about how to use scripts with premium features
113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# Configs and Tools for Testing Fleet
|
|
|
|
The files in this directory are intended to assist with Fleet development.
|
|
|
|
- `docker-compose.yml`: This docker-compose file helps with starting `osqueryd` instances for testing Fleet. More on this [below](#testing-with-containerized-osqueryd).
|
|
|
|
- `example_osquery.conf`: An example osquery config file that sets up basic configuration for distributed queries.
|
|
|
|
- `example_osquery.flags`: An example osquery flagfile setting the config options that must be loaded before the full JSON config.
|
|
|
|
- `fleet.crt` & `fleet.key`: Self-signed SSL certificate & key useful for testing locally with `osqueryd`. Works with the domain `host.docker.internal` (exposed within docker containers as the host's IP). Should **never** be used in production.
|
|
|
|
## Testing with containerized osqueryd
|
|
|
|
Using Docker enables us to rapidly spin up and down pre-configured `osqueryd` instances for testing Fleet. Currently we have container images for Ubuntu14 and Centos7 osquery installations.
|
|
|
|
### Setup
|
|
|
|
Docker and docker-compose are the only dependencies. The necessary container images will be pulled from Docker Cloud on first run.
|
|
|
|
Set the environment variable `ENROLL_SECRET` to the value of your Fleet enroll secret (available on the manage hosts page, or via `fleetctl get enroll-secret`).
|
|
|
|
(Optionally) Set `FLEET_SERVER` if you want to connect to a fleet server
|
|
besides `host.docker.internal:8080`.
|
|
|
|
### Running osqueryd
|
|
|
|
The osqueryd instances are configured to use the TLS plugins at `host.docker.internal:8080`. Using the `example_osquery.flags` in this directory should configure Fleet with the appropriate settings for these `osqueryd` containers to connect.
|
|
|
|
To start one instance each of Centos 6, Centos 7, Ubuntu 14, and Ubuntu 16
|
|
`osqueryd`, use:
|
|
|
|
```
|
|
docker-compose up
|
|
```
|
|
|
|
Linux users should use the overrides (which add DNS entries for
|
|
`host.docker.internal` based on the `DOCKER_HOST` env var):
|
|
|
|
```
|
|
docker-compose -f docker-compose.yml -f docker-compose.linux-overrides.yml up
|
|
```
|
|
|
|
The logs will be displayed on the host shell. Note that `docker-compose up` will reuse containers (so the state of `osqueryd` will be maintained across calls). To remove the containers and start from a fresh state on the next call to `up`, use:
|
|
|
|
```
|
|
docker-compose rm
|
|
```
|
|
|
|
If you want to only start one instance of `osqueryd`, use:
|
|
|
|
```
|
|
docker-compose run ubuntu14-osquery
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
docker-compose run centos7-osquery
|
|
```
|
|
|
|
Note that `docker-compose run` does not save state between calls.
|
|
|
|
This system can also be used to start many instances of osqueryd running in containers on the same host:
|
|
|
|
```
|
|
docker-compose up -d && docker-compose up --scale ubuntu14-osquery=20
|
|
```
|
|
|
|
To stop the containers when running in detached mode like this, use:
|
|
|
|
```
|
|
docker-compose stop
|
|
```
|
|
|
|
And to delete the containers when wanting a fresh state, or when finished testing, use:
|
|
|
|
```
|
|
docker-compose rm
|
|
```
|
|
|
|
We have had no trouble running up to 100 containerized osqueryd instances on a single processor core and about 1GB of RAM.
|
|
|
|
### Generating a osqueryd core file
|
|
|
|
The docker containers are configured to allow core files to be generated if osqueryd
|
|
crashes for some reason. You can attach to the container hosting the errant osqueryd
|
|
instance, install gdb and use it to read the core file to find out where the crash
|
|
occurred. The other scenario where you might find a core dump useful is if osqueryd
|
|
stops responding. In this case you can generate a core dump using the following instructions.
|
|
|
|
1. Open a shell session on a container
|
|
|
|
```
|
|
docker exec -t -i <container id> /bin/bash
|
|
```
|
|
|
|
2. Find the process ID of osqueryd
|
|
|
|
```
|
|
ps aux
|
|
```
|
|
|
|
There will be two osqueryd processes, you'll probably be interested in the child process (the one with the higher pid)
|
|
|
|
3. Send a signal to the process to core dump
|
|
|
|
```
|
|
kill -3 <pid>
|
|
```
|
|
|
|
The core file should be in your current working directory on the container.
|