Doc Updates

cmd/launcher-pummel/README.md

@@ -15,7 +15,7 @@ make launcher-pummel
 ```
 ./build/launcher-pummel \
   --host_path=./path/to/my/host/templates \
-  --server_url=fleet.acme.co \
+  --server_url=fleet.example.co \
   --enroll_secret=mB3XE5kwLt3YryD9FAanjwhm02HoOqll \
   --hosts=mac:100,windows:20,linux:5000
 ```

cmd/launcher/README.md

@@ -30,7 +30,7 @@ To use The Launcher to easily connect osquery to a server that is compliant with
 
 ```
 ./build/launcher \
-  --hostname=fleet.acme.net:443 \
+  --hostname=fleet.example.com:443 \
   --root_directory=/var/kolide-fleet \
   --enroll_secret=32IeN3QLgckHUmMD3iW40kyLdNJcGzP5
 ```
@@ -124,13 +124,13 @@ $ cat queries.json | ./build/launcher query --socket=/tmp/osquery.sock
 
 ### Connecting to Fleet
 
-Let's say that you have [Kolide Fleet](https://github.com/kolide/fleet) running at https://fleet.acme.org, you could simply run the following to connect The Launcher to Fleet (assuming you replace the enroll secret with the correct string):
+Let's say that you have [Kolide Fleet](https://github.com/kolide/fleet) running at https://fleet.example.com, you could simply run the following to connect The Launcher to Fleet (assuming you replace the enroll secret with the correct string):
 
 ```
 launcher \
   --enroll_secret=32IeN3QLgckHUmMD3iW40kyLdNJcGzP5 \
-  --hostname=fleet.acme.org:443 \
-  --root_directory=/var/acme/fleet
+  --hostname=fleet.example.com:443 \
+  --root_directory=/var/launcher/fleet
 ```
 
 If you're running Fleet on the default development location (https://localhost:8080), you can connect a launcher via:
@@ -139,7 +139,7 @@ If you're running Fleet on the default development location (https://localhost:8
 mkdir /tmp/fleet-launcher
 launcher \
   --enroll_secret=32IeN3QLgckHUmMD3iW40kyLdNJcGzP5 \
-  --hostname=fleet.acme.org:443 \
+  --hostname=fleet.example.com:443 \
   --root_directory=/tmp/fleet-launcher \
   --insecure
 ```

cmd/package-builder/README.md

@@ -17,7 +17,7 @@ make package-builder
 Assuming you have built the `package-builder` tool and the `launcher` binaries via `make package-builder`, you can create a set of launcher packages by using the `package-builder make` command. The only required parameter is `--hostname`. If you don't define an enrollment secret via `--enroll_secret`, then a blank enrollment secret will be used when connecting to the gRPC server defined by the supplied hostname.
 
 ```
-./build/package-builder make --hostname=grpc.launcher.acme.biz:443 --enroll_secret=foobar123
+./build/package-builder make --hostname=grpc.launcher.example.com:443 --enroll_secret=foobar123
 ```
 
 If you'd like to customize the keys that are used to sign the enrollment secret and macOS package, consider the following usage:
@@ -27,7 +27,7 @@ If you'd like to customize the keys that are used to sign the enrollment secret
   --hostname=localhost:8082 \
   --enroll_secret=foobar123 \
   --osquery_version=stable \
-  --mac_package_signing_key="Developer ID Installer: Acme Inc (ABCDEF123456)"
+  --mac_package_signing_key="Developer ID Installer: Example Inc (ABCDEF123456)"
 ```
 
 The macOS package will install a LaunchDaemon that will connect the launcher to the server specified by the `--hostname` flag, using an enrollment secret specified by the `--enroll_secret` flag. The Linux packages will currently lay down the launcher and osquery binaries as well as the enrollment secret specified by the `--enroll_secret` flag.

docs/architecture/2018-07-06_control-server-api.md

@@ -61,7 +61,7 @@ As a result of receiving requests to start a shell session, *the Launcher will e
 
 ```bash
 curl -X POST \
-  http://launcher.acme.com/api/shells/991464f3-2745-4034-bcb7-64143422cd19 \
+  http://launcher.example.com/api/shells/991464f3-2745-4034-bcb7-64143422cd19 \
   -H 'Content-Type: application/json' \
 	-H 'Authorization: Bearer 0bf30053-d699-4808-a177-74a56946b181'
   -d '{}'

docs/launcher-debugging.md

@@ -0,0 +1,79 @@
+# Debugging Launcher
+
+To debug launcher, look at the logs. Depending on what's happening,
+you may need to enable debug level logs.
+
+## Logs
+
+Launcher logs to stdout and stderr. Where these are placed, depends on
+your system, and how launcher is packaged.
+
+### Package Identifier
+
+When launcher is packaged, it uses an _identifier_ to allow multiple
+instances to co-exist. This _identifier_ appears in the systemd unit
+name, and the logging paths. It default to `launcher`
+
+For [Kolide
+Cloud](https://kolide.com/?utm_source=oss&utm_medium=readme&utm_campaign=launcher),
+this identifier has been `kolide`, `launcher` and `kolide-app`.
+
+### MacOS Logs
+
+On MacOS Launcher will generally be running via launchd. Launchd has
+an option for where to route logs. The launcher packaging usually sets
+this to be in the directory `/var/log/<identifier>/`
+
+### Linux Logs
+
+Most modern linux systems use systemd, and the associated
+journald. The unit file is likely named `launcher`, so logs can be
+viewed with `journalctl -u launcher`
+
+### Windows Logs
+
+When launcher is running as a service, it logs to the windows event
+log system. You should be able to see logs there. 
+
+## Enabling Debug Mode
+
+When running on a posix system, launcher can be toggled into debug
+logging mode. You can do this by sending launcher a `USR2` signal.
+
+For example `pkill -USR2 launcher`
+
+Note: windows does not support this as a runtime change
+
+## Running in the foreground
+
+Often, the easiest way to debug launcher is to simply run it in the
+foreground.
+
+1. Ensure it's stopped in your init system
+2. Look at your init script / systemd unit file / service definition
+3. Add a debug option, and run
+
+### Special windows foreground mode
+
+Windows services are a bit different than programs. On windows,
+launcher has three modes of running, they all support the `-config`
+option.
+
+1. Foreground mode. Invoked as `launcher`, it runs as a windows exe utable
+1. Service Mode. Invoked as `launcher svc`, this will only work as a service
+1. Service Foreground. Invoked as `launcher svc-fg` this uses golang's
+   debug framework to run the service in the foreground. It
+   additionally sets the logging to debug mode.
+
+Using `svc-fg` is the recommended approach
+
+## Getting Help
+
+For support with our SaaS, [Kolide K2](https://app.kolide.com/?utm_source=oss&utm_medium=readme&utm_campaign=launcher),
+please use the Intercom Help links inside that application, these are
+floating in the lower right. Or, email support@kolide.co
+
+For support regarding issues with our open-source projects, please
+feel free to reach out to us in the osquery Slack team in the #kolide
+channel, [invites are
+here](https://join.slack.com/t/osquery/shared_invite/zt-h29zm0gk-s2DBtGUTW4CFel0f0IjTEw)

docs/launcher.md

@@ -12,13 +12,23 @@ make launcher
 ./build/launcher --help
 ```
 
-Note that this style of build is generally only for development instances of Launcher. You should have `osqueryd` already installed on your system, as `launcher` will fall-back to looking for it in your `$PATH` in this case. For additional, more distributable, build options and commands, see the [Additional Build Options](#additional-build-options) section.
+Note that this style of build is generally only for development
+instances of Launcher. You should have `osqueryd` already installed on
+your system, as `launcher` will fall-back to looking for it in your
+`$PATH` in this case. For additional, more distributable, build
+options and commands, see the [Additional Build
+Options](#additional-build-options) section.
 
-For more distributable packages of Launcher and Osquery, consider using the [`package-builder`](./package-builder.md) tool that is provided with this repository.
+For more distributable packages of Launcher and Osquery, consider
+using the [`package-builder`](./package-builder.md) tool that is
+provided with this repository.
 
 ## General Usage
 
-To use The Launcher to easily connect osquery to a server that is compliant with the [gRPC specification](https://github.com/kolide/agent-api/blob/master/agent_api.proto), invoke the binary with just a few flags:
+To use The Launcher to easily connect osquery to a server that is
+compliant with the [gRPC
+specification](https://github.com/kolide/agent-api/blob/master/agent_api.proto),
+invoke the binary with just a few flags:
 
 - `--hostname`: the hostname of the gRPC server for your environment
 - `--root_directory`: the location of the local database, pidfiles, etc.
@@ -27,14 +37,29 @@ To use The Launcher to easily connect osquery to a server that is compliant with
 
 ```
 ./build/launcher \
-  --hostname=fleet.acme.net:443 \
+  --hostname=fleet.example.net:443 \
   --root_directory=/var/kolide-fleet \
   --enroll_secret=32IeN3QLgckHUmMD3iW40kyLdNJcGzP5
 ```
 
-You can also define the enroll secret via a file path (`--enroll_secret_path`) or an environment variable (`KOLIDE_LAUNCHER_ENROLL_SECRET`). See `launcher --help` for more information.
+You may need to define the `--insecure` and/or `--insecure_grpc` flag
+depending on your server configurations.
+
+## Configuring Launcher
+
+Launcher supports runtime configuration via three mechanisms. It reads
+environmental variables, then a config file, and lastly command line
+flags. As an example, to set the hostname, you would do one of:
+
+1. set the environmental variable `KOLIDE_LAUNCHER_HOSTNAME=fleet.example.net:443`
+1. Include `hostname fleet.example.net:443` in a config.flags file
+1. invoke with `--hostname=fleet.example.net:443` on the command line
+
+While any of these can be used in conjunction with your init system,
+we generally recommend using config files for simplicity. As a side
+note, environmental variables on windows are global, and thus
+contraindicated for configuration data.
 
-You may need to define the `--insecure` and/or `--insecure_grpc` flag depending on your server configurations.
 
 ## Override Osquery Flags
 
@@ -64,13 +89,13 @@ Because of likely breakage, the following flags cannot be overridden:
 
 ### Connecting to Fleet
 
-Let's say that you have [Kolide Fleet](https://github.com/kolide/fleet) running at https://fleet.acme.org, you could simply run the following to connect The Launcher to Fleet (assuming you replace the enroll secret with the correct string):
+Let's say that you have [Kolide Fleet](https://github.com/kolide/fleet) running at https://fleet.example.org, you could simply run the following to connect The Launcher to Fleet (assuming you replace the enroll secret with the correct string):
 
 ```
 launcher \
   --enroll_secret=32IeN3QLgckHUmMD3iW40kyLdNJcGzP5 \
-  --hostname=fleet.acme.org:443 \
-  --root_directory=/var/acme/fleet
+  --hostname=fleet.example.org:443 \
+  --root_directory=/var/launcher/fleet
 ```
 
 If you're running Fleet on the default development location (https://localhost:8080), you can connect a launcher via:
@@ -79,7 +104,7 @@ If you're running Fleet on the default development location (https://localhost:8
 mkdir /tmp/fleet-launcher
 launcher \
   --enroll_secret=32IeN3QLgckHUmMD3iW40kyLdNJcGzP5 \
-  --hostname=fleet.acme.org:443 \
+  --hostname=fleet.example.org:443 \
   --root_directory=/tmp/fleet-launcher \
   --insecure
 ```

docs/package-builder.md

@@ -97,7 +97,7 @@ Or to build signed:
 
 ```
 # Replace this with your codesign information
-export CODESIGN_IDENTITY='Developer ID Application: Acme Inc (ABCDEF123456)'
+export CODESIGN_IDENTITY='Developer ID Application: Example Inc (ABCDEF123456)'
 make xp-codesign
 ```