Fleet: Connect Hosts to Kolide Fleet

This guide will walk through creating packages to tie clients into Kolide Fleet. For using Launcher and the actual osquery binary, basic guidelines will be provided and relevant documentation will be linked to.

Methods for Tying Clients Into Fleet:

There are three ways to get clients to start communicating with Kolide Fleet:

1. Using Kolide Launcher's package-builder.
2. Using Kolide's Launcher
3. Installing osquery manually on hosts and configuring the binary to connect to Kolide Fleet.

Obtaining your Fleet Enroll Secret:

Your enroll secret will be needed in all methods to get clients to connect to Fleet.

In the Fleet Interface's home page, go to Add New Host > Reveal Secret.

Using Kolide Launcher's package-builder to Create Installer Package:

The following link has documentation on using package-builder: https://github.com/kolide/fleet/blob/master/docs/infrastructure/adding-hosts-to-fleet.md

The most convenient method for connecting hosts to Kolide Fleet is using Launcher's package-builder to create a package that bundles osquery with all of its necessary configurations and with a pre-configured system service to connect to the server running Fleet.

Limitations:

1. package-builder currently only runs on MacOS.
2. package-builder can only create packages for Linux and MacOS. Windows needs to use Launcher's binary or the osquery binary.

Install package-builder on MacOS:

First, install Golang, the programming language Launcher was written in: https://golang.org/doc/install

Once go is installed, clone the Launcher Github repository and cd into its directory:

mkdir -p ~/go/src/github.com/kolide/
cd ~/go/src/github.com/kolide/
git clone https://github.com/kolide/launcher/
cd launcher
make deps
make package-builder

Upon compilation, there should be a binary called package-builder in your current working directory.

Using package-builder:

Here is an example package-builder command

./package-builder make --hostname=[my-hostname]:8080 --enroll_secret=[your-enroll-secret] --osquery_version=stable

Use the --help flag for further help on using the package-builder binary.

When package-builder successfully creates a package, it will output the paths of the saved packages, like so:

{"caller":"level.go:63","deb":"/tmp/packages_053435455/launcher-linux-0.5.5-19-ga7b9229.deb","level":"info","mac":"
  /tmp/packaging_015415749/launcher-darwin-0.5.5-19-ga7b9229.pkg","msg":"created packages","rpm":"/tmp/packages_05343
  5455/launcher-linux-0.5.5-19-ga7b9229.rpm","ts":"2018-08-20T16:00:22.943515Z"}

Save the files for your relevant operating system and use them to install the package on your host.

Start and Enable the Launcher service on Linux:

Once the launcher package has been installed on the Linux remote server, make sure the launcher service is enabled and started:

sudo systemctl enable launcher.service
sudo systemctl start launcher.service

Using Kolide's Launcher to Connect to Fleet:

Download Kolide Launcher releases from the Github repository. Place the launcher binary in $PATH.

Here is an example command for running Launcher:

./launcher --hostname=172.16.27.168:8080 --osqueryd_path=~/Downloads/darwin/osqueryd --enroll_secret=[my-enroll-secret] --autoupdate --insecure

Best practice would be to create a system service for your respective operating system.

Linux Systemd Service for Launcher:

The following example systemd service can be used to run Launcher on Linux:

[Unit]
Description=The Kolide Launcher
After=network.service syslog.service

[Service]
ExecStart= $LauncherPath \
  --hostname=$FleetServer:FleetPort \
  --enroll_secret=$FleetSecret \
  --autoupdate \
  --osqueryd_path=$OsquerydPath
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

Using osquery to Connect to Fleet:

Use the following documentation for instructions to run the osquery binary: https://github.com/kolide/fleet/blob/master/docs/infrastructure/adding-hosts-to-fleet.md#launching-osqueryd