Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

Documentation Structure (#1101)

Browse Source 
Initial structure and content for the Kolide documentation.
This commit is contained in:
Mike Arpaia
2017-01-25 14:51:00 -07:00
committed by GitHub
parent 3e5ff9060f
commit a4d9fe8dfd
22 changed files with 408 additions and 428 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -394
View File
@@ -1,397 +1,5 @@
# Kolide [![CircleCI](https://circleci.com/gh/kolide/kolide-ose.svg?style=svg&circle-token=2573c239b7f18967040d2dec95ca5f71cfc90693)](https://circleci.com/gh/kolide/kolide-ose)
### Contents
Documentation can be found in the [docs](./docs/README.md) subdirectory of this repository.
- [Development Environment](#development-environment)
- [Installing build dependencies](#installing-build-dependencies)
- [Building](#building)
- [Generating the packaged JavaScript](#generating-the-packaged-javascript)
- [Automatic rebuilding of the JavaScript bundle](#automatic-rebuilding-of-the-javascript-bundle)
- [Compiling the Kolide binary](#compiling-the-kolide-binary)
- [Managing Go dependencies with glide](#managing-go-dependencies-with-glide)
- [Database Modifications](#database-modifications)
- [Testing](#testing)
- [Full test suite](#full-test-suite)
- [Go unit tests](#go-unit-tests)
- [JavaScript unit tests](#javascript-unit-tests)
- [Go linters](#go-linters)
- [JavaScript linters](#javascript-linters)
- [Viewing test coverage](#viewing-test-coverage)
- [Email](#email)
- [Testing email using MailHog](#testing-email-using-mailhog)
- [Viewing email content in the terminal](#viewing-email-content-in-the-terminal)
- [Development Infrastructure](#development-infrastructure)
- [Starting the local development environment](#starting-the-local-development-environment)
- [Stopping the local development environment](#stopping-the-local-development-environment)
- [Setting up the database tables](#setting-up-the-database-tables)
- [Running Kolide](#running-kolide)
- [Using Docker development infrastructure](#using-docker-development-infrastructure)
## Development Environment
### Installing build dependencies
To setup a working local development environment, you must install the following
minimum toolset:
* [Go](https://golang.org/dl/) (1.7 or greater)
* [Node.js](https://nodejs.org/en/download/current/) (and npm)
* [GNU Make](https://www.gnu.org/software/make/)
* [Docker](https://www.docker.com/products/overview#/install_the_platform)
If you're using MacOS or Linux, Make should be installed by default. If you
are using Windows, you will need to install it separately. Additionally, if you
would only like to run an in-memory instance of Kolide (for demonstrations,
testing, etc.), then you do not need to install Docker.
Once you have those minimum requirements, you will need to install Kolide's
dependent libraries. To do this, run the following:
```
make deps
```
When pulling in new revisions to your working source tree, it may be necessary
to re-run `make deps` if a new Go or JavaScript dependency was added.
```
make generate
```
#### Generating the packaged JavaScript
To generate all necessary code (bundling JavaScript into Go, etc), run the
following:
```
make generate
```
#### Automatic rebuilding of the JavaScript bundle
Normally, `make generate` takes the JavaScript code, bundles it into a single
bundle via Webpack, and inlines that bundle into a generated Go source file so
that all of the frontend code can be statically compiled into the binary. When
you build the code after running `make generate`, all of that JavaScript is
included in the binary.
This makes deploying Kolide a dream, since you only have to worry about a single
static binary. If you are working on frontend code, it is likely that you don't
want to have to manually re-run `make generate` and `make build` every time you
edit JavaScript and CSS in order to see your changes in the browser. To solve
this problem, before you build the Kolide binary, run the following command
instead of `make generate`:
```
make generate-dev
```
Instead of reading the JavaScript from a inlined static bundle compiled within
the binary, `make generate-dev` will generate a Go source file which reads the
frontend code from disk and run Webpack in "watch mode".
Note that when you run `make generate-dev`, Webpack will be watching the
JavaScript files that were used to generate the bundle, so the process will be
long lived. Depending on your personal workflow, you might want to run this in a
background terminal window.
After you run `make generate-dev`, run `make build` to build the binary, launch
the binary and you'll be able to refresh the browser whenever you edit and save
frontend code.
#### Compiling the Kolide binary
Use `go build` to build the application code. For your convenience, a make
command is included which builds the code:
```
make build
```
It's not necessary to use Make to build the code, but using Make allows us to
account for cross-platform differences more effectively than the `go build` tool
when writing automated tooling. Use whichever you prefer.
#### Managing Go Dependencies with Glide
[Glide](https://github.com/Masterminds/glide#glide-vendor-package-management-for-golang)
is a package manager for third party Go libraries. See the ["How It Works"](https://github.com/Masterminds/glide#how-it-works)
section in the Glide README for full details.
##### Installing the correct versions of dependencies
To install the correct versions of third package libraries, use `glide install`.
`glide install` will use the `glide.lock` file to pull vendored packages from
remote vcs. `make deps` takes care of this step, as well as downloading the
latest version of glide for you.
##### Adding new dependencies
To add a new dependency, use [`glide get [package name]`](https://github.com/Masterminds/glide#glide-get-package-name)
##### Updating dependencies
To update, use [`glide up`](https://github.com/Masterminds/glide#glide-update-aliased-to-up) which will use VCS and `glide.yaml` to figure out the correct updates.
##### Testing application code with glide
#### Database Modifications
##### Adding/Updating tables
Database schemas are managed by a series of migrations defined in go code. We
use a customized version of the Goose migrations tool to handle these
migrations.
Note: Once committed to the Kolide repo, table migrations should be considered
immutable. Any changes to an existing table should take place in a new
migration executing ALTERs.
* From the project root run the following shell commands:
``` bash
go get github.com/kolide/goose
cd server/datastore/mysql/migrations/tables
goose create AddColumnFooToUsers
```
* Find the file you created in the migrations directory and edit it
``` go
package migration
import (
"database/sql"
"github.com/kolide/goose"
)
func init() {
goose.AddMigration(Up_20161118212656, Down_20161118212656)
}
func Up_20161118212656(tx *sql.Tx) error {
_, err := tx.Exec("ALTER TABLE `users` ADD COLUMN `foo` varchar(10) NOT NULL;")
return err
}
func Down_20161118212656(tx *sql.Tx) error {
_, err := tx.Exec("ALTER TABLE `users` DROP COLUMN `foo`;")
return err
}
```
* Update the database by running the following shell commands:
``` bash
make build
build/kolide prepare db
```
##### Populating the database
Populating built in data is also performed through migrations. All table
migrations are performed before any data migrations.
Note: Data migrations can be mutable. If tables are altered in a way that would
render a data migration invalid (columns changed/removed), data migrations
should be updated to comply with the new schema. Data migrations will not be
re-run when they have already been run against a database, but they must be
updated to maintain compatibility with a fresh DB.
* From the project root run the following shell commands:
``` bash
go get github.com/kolide/goose
cd server/datastore/mysql/migrations/data
goose create PopulateFoo
```
* Proceed as for table migrations, editing and running the newly created
migration file.
### Testing
#### Full test suite
To execute all of the tests that CI will execute, run the following from the
root of the repository:
```
make test
```
It is a good idea to run `make test` before submitting a Pull Request.
#### Go unit tests
To run all Go unit tests, run the following:
```
make test-go
```
### Database Tests
To run database tests set environment variables as follows.
```
export MYSQL_PORT_3306_TCP_ADDR=192.168.99.100
export MYSQL_TEST=1
```
### Email Tests
To run email related unit tests using MailHog set the following environment
variable.
```
export MAIL_TEST=1
```
#### JavaScript unit tests
To run all JavaScript unit tests, run the following:
```
make test-js
```
#### Go linters
To run all Go linters and static analyzers, run the following:
```
make lint-go
```
# Integration Tests
By default, tests that require external dependecies like Mysql or Redis are
skipped. The tests can be enabled by setting `MYSQL_TEST=true` and
`REDIS_TEST=true` environment variables. MYSQL will try to connect with the
following credentials.
```
user = "kolide"
password = "kolide"
database = "kolide"
host = "127.0.0.1"
```
Redis tests expect a redis instance at `127.0.0.1:6379`.
Both the Redis and MySQL tests will also be automatically enabled with Docker
links. You can check out the CircleCI configuration file(`circle.yml`) for an example of
how to use Docker links to run integration tests.
#### JavaScript linters
To run all JavaScript linters and static analyzers, run the following:
```
make lint-js
```
#### Viewing test coverage
When you run `make test` or `make test-go` from the root of the repository, test
coverage reports are generated in every subpackage. For example, the `server`
subpackage will have a coverage report generated in `./server/server.cover`
To explore a test coverage report on a line-by-line basis in the browser, run
the following:
```bash
# substitute ./datastore/datastore.cover, etc
go tool cover -html=./server/server.cover
```
To view test a test coverage report in a terminal, run the following:
```bash
# substitute ./datastore/datastore.cover, etc
go tool cover -func=./server/server.cover
```
### Email
#### Testing email using MailHog
To intercept sent emails while running a Kolide development environment, make
sure that you've set the SMTP address to `<docker host ip>:1025` and leave the
username and password blank. Then, visit `<docker host ip>:8025` in a web
browser to view the [MailHog](https://github.com/mailhog/MailHog) UI.
For example, if docker is running natively on your `localhost`, then your mail
settings should look something like:
```yaml
mail:
address: localhost:1025
```
`localhost:1025` is the default configuration. You can use `kolide config_dump`
to see the values which Kolide is using given your configuration.
#### Viewing email content in the terminal
If you're [running Kolide in dev mode](#using-no-external-dependencies), emails
will be printed to the terminal instead of being sent via an SMTP server. This
may be useful if you want to view the content of all emails that Kolide sends.
### Development infrastructure
#### Starting the local development environment
To set up a canonical development environment via docker,
run the following from the root of the repository:
```
docker-compose up
```
This requires that you have docker installed. At this point in time,
automatic configuration tools are not included with this project.
#### Stopping the local development environment
If you'd like to shut down the virtual infrastructure created by docker, run
the following from the root of the repository:
```
docker-compose down
```
#### Setting up the database tables
Once you `docker-compose up` and are running the databases, you can build
the code and run the following command to create the database tables:
```
kolide prepare db
```
### Running Kolide
#### Using Docker development infrastructure
To start the Kolide server backed by the Docker development infrasturcture, run
the Kolide binary as follows:
```
kolide serve
```
By default, Kolide will try to connect to servers running on default ports on
localhost.
If you're using Docker via [Docker Toolbox](https://www.docker.com/products/docker-toolbox).
you may have to modify the default values use the output of `docker-machine ip`
instead of `localhost`.There is an example configuration file included in this
repository to make this process easier for you. Use the `--config` flag of the
Kolide binary to specify the path to your config. See `kolide --help` for more
options.
![Kolide](./assets/images/rube.png)
assets/images/rube.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

docs/README.md
+10 -2
View File
@@ -1,3 +1,11 @@
# Kolide Documentation
Kolide Documentation
====================
Please make sure that you use the documents that match your Kolide version. The version number should be a part of the page URL. If it's not, you are probably using the documentation of a development branch which may contain changes that are not compatible with your Kolide version.
Welcome to the Kolide documentation.
- Information about using the Kolide web application can be found in the [Application Documentation](./application/README.md).
- Resources for deploying osquery to hosts, deploying the Kolide server, installing Kolide's infrastructure dependencies, etc. can all be found in the [Infrastructure Documentation](./infrastructure/README.md).
- If you are interested in accessing the Kolide REST API in order to programatially interact with your osquery installation, please see the [API Documentation](./api/README.md).
- Finally, if you're interested in interacting with the Kolide source code, you will find information on modifying and building the code in the [Development Documentation](./development/README.md).
If you have any questions, please don't hesitate to reach out to [support@kolide.co](mailto:support@kolide.co).
docs/api/README.md
+2
View File
@@ -0,0 +1,2 @@
API Documentation
=================
docs/application/README.md
+18
View File
@@ -0,0 +1,18 @@
Application Documentation
=========================
Kolide is an application that allows you to take advantage of the power of osquery in order to maintain constant insight into the state of your infrastructure (security, health, stability, performance, compliance, etc). The application documentation contains documents on the following topics:
## Using The Kolide application
- For information on running osquery queries on hosts in your infrastructure, you can refer to the [Running Queries](.running-queries.md) page.
- To learn more about scheduling queries for periodic execution on select hosts, managing query packs, etc, you can refer to the [Scheduling Queries](./scheduling-queries.md) page.
- Kolide also allows you to configure osquery options so that you can endlessly customize your osquery usage. For information on how to customize osquery using Kolide as well as thoughts on what customization you might consider performing, see the [Configuring Osquery Options](./configuring-osquery-options.md) documentation.
## Kolide for the osquery user
If you have extensive existing osquery experience, we've supplied a document which briefly discusses the features, intentions, and philosophies of Kolide's osquery management capabilities. For more information, see the [Kolide For The Osquery User](./kolide-for-the-osquery-user.md) documentation.
## Working With osquery logs
Kolide makes it easy to schedule queries, curate packs, and generate a lot of osquery logs. For more information on how you can access these logs as well as examples on what you can do with them, see the [Working With Osquery Logs](./working-with-osquery-logs.md) documentation.
docs/application/configuring-osquery-options.md
+2
View File
@@ -0,0 +1,2 @@
Configuring Osquery Options
===========================
docs/application/kolide-for-the-osquery-user.md
+2
View File
@@ -0,0 +1,2 @@
Kolide For The Osquery User
===========================
docs/application/running-queries.md
+2
View File
@@ -0,0 +1,2 @@
Running Queries
===============
docs/application/scheduling-queries.md
+2
View File
@@ -0,0 +1,2 @@
Scheduling Queries
==================
docs/application/working-with-osquery-logs.md
+2
View File
@@ -0,0 +1,2 @@
Working With Osquery Logs
=========================
docs/development/README.md
+17
View File
@@ -0,0 +1,17 @@
Development Documentation
=========================
The Kolide application is a Go API server which serves a React/Redux single-page application for the frontend. The development documentation contains documents on the following topics:
## Building and contributing code
- For documentation on building the Kolide source code, see the [Building The Code](./building-the-code.md) guide.
- To learn about how some development practices work within the Kolide application (such as adding database migrations, populating the application with default seed data, etc), see the [Contributing Code](./contributing-code.md) document.
## Running tests
For information on running the various tests that Kolide application contains (JavaScript unit tests, Go unit tests, linters, integration tests, etc), see the [Testing](./testing.md) guide.
## Using development infrastructure and tooling
The Kolide application uses a lot of docker tooling to make setting up a development environment quick and easy. For information on this, see the [Development Infrastructure](./development-infrastructure.md) document.
docs/development/building-the-code.md
+77
View File
@@ -0,0 +1,77 @@
Building The Code
=================
## Installing build dependencies
To setup a working local development environment, you must install the following minimum toolset:
* [Go](https://golang.org/dl/) (1.7 or greater)
* [Node.js](https://nodejs.org/en/download/current/) (and npm)
* [GNU Make](https://www.gnu.org/software/make/)
* [Docker](https://www.docker.com/products/overview#/install_the_platform)
If you're using MacOS or Linux, Make should be installed by default. If you are using Windows, you will need to install it separately.
Once you have those minimum requirements, you will need to install Kolide's dependent libraries. To do this, run the following:
```
make deps
```
When pulling in new revisions to your working source tree, it may be necessary to re-run `make deps` if a new Go or JavaScript dependency was added.
```
make generate
```
## Generating the packaged JavaScript
To generate all necessary code (bundling JavaScript into Go, etc), run the following:
```
make generate
```
### Automatic rebuilding of the JavaScript bundle
Normally, `make generate` takes the JavaScript code, bundles it into a single bundle via Webpack, and inlines that bundle into a generated Go source file so that all of the frontend code can be statically compiled into the binary. When you build the code after running `make generate`, all of that JavaScript is included in the binary.
This makes deploying Kolide a dream, since you only have to worry about a single static binary. If you are working on frontend code, it is likely that you don't want to have to manually re-run `make generate` and `make build` every time you edit JavaScript and CSS in order to see your changes in the browser. To solve this problem, before you build the Kolide binary, run the following command instead of `make generate`:
```
make generate-dev
```
Instead of reading the JavaScript from a inlined static bundle compiled within the binary, `make generate-dev` will generate a Go source file which reads the frontend code from disk and run Webpack in "watch mode".
Note that when you run `make generate-dev`, Webpack will be watching the JavaScript files that were used to generate the bundle, so the process will be long lived. Depending on your personal workflow, you might want to run this in a background terminal window.
After you run `make generate-dev`, run `make build` to build the binary, launch the binary and you'll be able to refresh the browser whenever you edit and save frontend code.
## Compiling the Kolide binary
Use `go build` to build the application code. For your convenience, a make command is included which builds the code:
```
make build
```
It's not necessary to use Make to build the code, but using Make allows us to account for cross-platform differences more effectively than the `go build` tool when writing automated tooling. Use whichever you prefer.
## Managing Go Dependencies with Glide
[Glide](https://github.com/Masterminds/glide#glide-vendor-package-management-for-golang) is a package manager for third party Go libraries. See the ["How It Works"](https://github.com/Masterminds/glide#how-it-works) section in the Glide README for full details.
### Installing the correct versions of dependencies
To install the correct versions of third package libraries, use `glide install`. `glide install` will use the `glide.lock` file to pull vendored packages from remote vcs. `make deps` takes care of this step, as well as downloading the latest version of glide for you.
### Adding new dependencies
To add a new dependency, use [`glide get [package name]`](https://github.com/Masterminds/glide#glide-get-package-name)
### Updating dependencies
To update, use [`glide up`](https://github.com/Masterminds/glide#glide-update-aliased-to-up) which will use VCS and `glide.yaml` to figure out the correct updates.
docs/development/contributing-code.md
+67
View File
@@ -0,0 +1,67 @@
Contributing Code
=================
## Database Modifications
### Adding/Updating tables
Database schemas are managed by a series of migrations defined in go code. We use a customized version of the Goose migrations tool to handle these migrations.
Note: Once committed to the Kolide repo, table migrations should be considered immutable. Any changes to an existing table should take place in a new migration executing ALTERs.
* From the project root run the following shell commands:
``` bash
go get github.com/kolide/goose
cd server/datastore/mysql/migrations/tables
goose create AddColumnFooToUsers
```
* Find the file you created in the migrations directory and edit it
``` go
package migration
import (
"database/sql"
"github.com/kolide/goose"
)
func init() {
goose.AddMigration(Up_20161118212656, Down_20161118212656)
}
func Up_20161118212656(tx *sql.Tx) error {
_, err := tx.Exec("ALTER TABLE `users` ADD COLUMN `foo` varchar(10) NOT NULL;")
return err
}
func Down_20161118212656(tx *sql.Tx) error {
_, err := tx.Exec("ALTER TABLE `users` DROP COLUMN `foo`;")
return err
}
```
* Update the database by running the following shell commands:
``` bash
make build
build/kolide prepare db
```
### Populating the database with default data
Populating built in data is also performed through migrations. All table migrations are performed before any data migrations.
Note: Data migrations can be mutable. If tables are altered in a way that would render a data migration invalid (columns changed/removed), data migrations should be updated to comply with the new schema. Data migrations will not be re-run when they have already been run against a database, but they must be updated to maintain compatibility with a fresh DB.
* From the project root run the following shell commands:
``` bash
go get github.com/kolide/goose
cd server/datastore/mysql/migrations/data
goose create PopulateFoo
```
* Proceed as for table migrations, editing and running the newly created migration file.
docs/development/development-infrastructure.md
+40
View File
@@ -0,0 +1,40 @@
Development Infrastructure
==========================
## Starting the local development environment
To set up a canonical development environment via docker, run the following from the root of the repository:
```
docker-compose up
```
This requires that you have docker installed. At this point in time, automatic configuration tools are not included with this project.
#### Stopping the local development environment
If you'd like to shut down the virtual infrastructure created by docker, run the following from the root of the repository:
```
docker-compose down
```
#### Setting up the database tables
Once you `docker-compose up` and are running the databases, you can build the code and run the following command to create the database tables:
```
kolide prepare db
```
## Running Kolide using Docker development infrastructure
To start the Kolide server backed by the Docker development infrasturcture, run the Kolide binary as follows:
```
kolide serve
```
By default, Kolide will try to connect to servers running on default ports on localhost.
If you're using Docker via [Docker Toolbox](https://www.docker.com/products/docker-toolbox), you may have to modify the default values use the output of `docker-machine ip` instead of `localhost`. There is an example configuration file included in this repository to make this process easier for you. Use the `--config` flag of the Kolide binary to specify the path to your config. See `kolide --help` for more options.
docs/development/testing.md
+112
View File
@@ -0,0 +1,112 @@
Testing
=======
## Full test suite
To execute all of the tests that CI will execute, run the following from the root of the repository:
```
make test
```
It is a good idea to run `make test` before submitting a Pull Request.
#### Go unit tests
To run all Go unit tests, run the following:
```
make test-go
```
### Database Tests
To run database tests set environment variables as follows.
```
export MYSQL_PORT_3306_TCP_ADDR=192.168.99.100
export MYSQL_TEST=1
```
### Email Tests
To run email related unit tests using MailHog set the following environment
variable.
```
export MAIL_TEST=1
```
#### JavaScript unit tests
To run all JavaScript unit tests, run the following:
```
make test-js
```
#### Go linters
To run all Go linters and static analyzers, run the following:
```
make lint-go
```
# Integration Tests
By default, tests that require external dependecies like Mysql or Redis are skipped. The tests can be enabled by setting `MYSQL_TEST=true` and `REDIS_TEST=true` environment variables. MYSQL will try to connect with the following credentials.
```
user = "kolide"
password = "kolide"
database = "kolide"
host = "127.0.0.1"
```
Redis tests expect a redis instance at `127.0.0.1:6379`.
Both the Redis and MySQL tests will also be automatically enabled with Docker links. You can check out the CircleCI configuration file(`circle.yml`) for an example of how to use Docker links to run integration tests.
#### JavaScript linters
To run all JavaScript linters and static analyzers, run the following:
```
make lint-js
```
#### Viewing test coverage
When you run `make test` or `make test-go` from the root of the repository, test coverage reports are generated in every subpackage. For example, the `server` subpackage will have a coverage report generated in `./server/server.cover`
To explore a test coverage report on a line-by-line basis in the browser, run the following:
```bash
# substitute ./datastore/datastore.cover, etc
go tool cover -html=./server/server.cover
```
To view test a test coverage report in a terminal, run the following:
```bash
# substitute ./datastore/datastore.cover, etc
go tool cover -func=./server/server.cover
```
### Email
#### Testing email using MailHog
To intercept sent emails while running a Kolide development environment, make sure that you've set the SMTP address to `<docker host ip>:1025` and leave the username and password blank. Then, visit `<docker host ip>:8025` in a web browser to view the [MailHog](https://github.com/mailhog/MailHog) UI.
For example, if docker is running natively on your `localhost`, then your mail settings should look something like:
```yaml
mail:
address: localhost:1025
```
`localhost:1025` is the default configuration. You can use `kolide config_dump` to see the values which Kolide is using given your configuration.
#### Viewing email content in the terminal
If you're [running Kolide in dev mode](#using-no-external-dependencies), emails will be printed to the terminal instead of being sent via an SMTP server. This may be useful if you want to view the content of all emails that Kolide sends.
docs/hosts/images/adding-hosts.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 366 KiB

docs/hosts/mac-enterprise.md
-27
View File
@@ -1,27 +0,0 @@
# Enrolling multiple Macs
If you're managing an enterprise environment with multiple Mac devices, you likely have an enterprise deployment tool like [Munki](https://www.munki.org/munki/) or [Jamf Pro](https://www.jamf.com/products/jamf-pro/) to deliver software to your mac. You can deploy osqueryd and enroll all your macs into kolide using your software management tool of choice.
First, [download](https://osquery.io/downloads/) and import the osquery package into your software management repository. You can also use the community supported autopkg [recipe](https://github.com/autopkg/keeleysam-recipes/tree/master/osquery)
to keep osqueryd updated.
Next, you will have to create an enrollment package to get osqueryd running and talking to kolide. Here, you'll have to create a custom package because you have to provide specific information about your kolide setup. We created a Makefile to help you build a macOS enrollment package.
First, download the kolide repository from Github and navigate to the `tools/mac` directory.
Next, you'll have to edit the `config.mk` file. You'll find all the necessary information by clicking "Add New Host" in your kolide server.
- Set the `KOLIDE_HOSTNAME` variable to the FQDN of your kolide server.
- Set the `ENROLL_SECRET` variable to the enroll secret you got from kolide.
- Paste the contents of the kolide TLS certificate after the following line:
```
define KOLIDE_TLS_CERTIFICATE
```
Note that osqueryd requires a full certificate chain, even for certificates which might be trusted by your keychain. The "Fetch Kolide Certificate" button in the Add New Host screen will attempt to fetch the full chain for you.
Once you've configured the `config.mk` file with the corect variables, you can run `make` in the `tools/mac` directory. Running `make` will create a new `kolide-enroll.pkg` file which you can import into your software repository and deploy to your macs.
The enrollment package must installed after the osqueryd package, and will install a LaunchDaemon to keep the osqueryd process running.
docs/infrastructure/README.md
+18
View File
@@ -0,0 +1,18 @@
Infrastructure Documentation
============================
Kolide is an infrastructure instrumentation application which has it's own infrastructure dependencies and requirements. The infrastructure documentation contains documents on the following topics:
## Deploying and configuring osquery
- For information on installing osquery on hosts that you own, see our [Adding Hosts To Kolide](./adding-hosts-to-kolide.md) document, which compliments existing [osquery documentation](https://osquery.readthedocs.io/en/stable/).
- To add hosts to Kolide, you will need to provide a minimum set of configuration to the osquery agent on each host. These configurations are defined in the aforementioned [Adding Hosts To Kolide](./adding-hosts-to-kolide.md) document. If you'd like to further customize the osquery configurations and options, this can be done via the Kolide application UI. You can find more documentation on this feature in the [application documentation for this feature](../application/configuring-osquery-options.md).
- To manage osquery configurations at your organization, we strongly suggest using some form of configuration management tooling. For more information on configuration management, see the [Managing Client Configurations](./managing-client-configurations.md) document.
## Installing Kolide and it's dependencies
The Kolide server has a few dependencies. To learn more about installing the Kolide server and it's dependencies, see the [Installing Kolide](./installing-kolide.md) guide.
## Managing a Kolide server
Running the Kolide server is a relatively simple process. We're prepared a brief guide to help you manage and maintain your Kolide server. Check out the [Running Kolide](./running-kolide.md) guide for more information.
docs/hosts/adding-hosts.md → docs/infrastructure/adding-hosts-to-kolide.md
+27 -5
View File
@@ -25,7 +25,7 @@ You can specify the path to this certificate with the `--tls_server_certs` flag
## Launching osqueryd
Assuming that you arere deploying your enrollment secret as the environment variable `OSQUERY_ENROLL_SECRET` and your osquery server certificate is at `/etc/osquery/kolide.crt`, you could copy and paste the following command with the following flags (be sure to replace acme.kolide.co with the hostname for your Kolide installation):
Assuming that you are deploying your enrollment secret as the environment variable `OSQUERY_ENROLL_SECRET` and your osquery server certificate is at `/etc/osquery/kolide.crt`, you could copy and paste the following command with the following flags (be sure to replace acme.kolide.co with the hostname for your Kolide installation):
```
osqueryd
@@ -52,12 +52,34 @@ If your osquery server certificate is deployed to a path that is not `/etc/osque
### Using a flag file to manage flags
For your convenience, osqueryd supports putting all of your flags into a single file. This file is commonly deployed to `/etc/osquery/osquery.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via:
For your convenience, osqueryd supports putting all of your flags into a single file. We suggest deploying this file to `/etc/osquery/kolide.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via:
```
osqueryd --flagfile=/etc/osquery/osquery.flags
osqueryd --flagfile=/etc/osquery/kolide.flags
```
## Configuration Management
## Enrolling multiple macOS hosts
We recommend that you use an infrastructure configuration management tool to manage these osquery configurations consistently across your environment. If you're unsure about what configuration management tools your organization uses, contact your company's system administrators. If you are evaluating new solutions for this problem, the founders of Kolide have successfully managed configurations in large production environments using [Chef](https://www.chef.io/chef/) and [Puppet](https://puppet.com/).
If you're managing an enterprise environment with multiple Mac devices, you likely have an enterprise deployment tool like [Munki](https://www.munki.org/munki/) or [Jamf Pro](https://www.jamf.com/products/jamf-pro/) to deliver software to your mac fleet. You can deploy osqueryd and enroll all your macs into Kolide using your software management tool of choice.
First, [download](https://osquery.io/downloads/) and import the osquery package into your software management repository. You can also use the community supported [autopkg recipe](https://github.com/autopkg/keeleysam-recipes/tree/master/osquery)
to keep osqueryd updated.
Next, you will have to create an enrollment package to get osqueryd running and talking to Kolide. Specifically, you'll have to create a custom package because you have to provide specific information about your Kolide deployment. To make this as easy as possible, we've created a Makefile to help you build a macOS enrollment package.
First, download the Kolide repository from GitHub and navigate to the `tools/mac` directory of the repository.
Next, you'll have to edit the `config.mk` file. You'll find all of the necessary information by clicking "Add New Host" in your kolide server.
- Set the `KOLIDE_HOSTNAME` variable to the FQDN of your Kolide server.
- Set the `ENROLL_SECRET` variable to the enroll secret you got from Kolide.
- Paste the contents of the Kolide TLS certificate after the following line:
```
define KOLIDE_TLS_CERTIFICATE
```
Note that osqueryd requires a full certificate chain, even for certificates which might be trusted by your keychain. The "Fetch Kolide Certificate" button in the Add New Host screen will attempt to fetch the full chain for you.
Once you've configured the `config.mk` file with the correct variables, you can run `make` in the `tools/mac` directory. Running `make` will create a new `kolide-enroll.pkg` file which you can import into your software repository and deploy to your mac fleet.
The enrollment package must installed after the osqueryd package, and will install a LaunchDaemon to keep the osqueryd process running.
docs/infrastructure/installing-kolide.md
+2
View File
@@ -0,0 +1,2 @@
Installing Kolide
=================
docs/infrastructure/managing-client-configurations.md
+4
View File
@@ -0,0 +1,4 @@
Managing Client Configurations
==============================
We recommend that you use an infrastructure configuration management tool to manage these osquery configurations consistently across your environment. If you're unsure about what configuration management tools your organization uses, contact your company's system administrators. If you are evaluating new solutions for this problem, the founders of Kolide have successfully managed configurations in large production environments using [Chef](https://www.chef.io/chef/) and [Puppet](https://puppet.com/).
docs/infrastructure/running-kolide.md
+2
View File
@@ -0,0 +1,2 @@
Running Kolide
==============