Merge pull request #1804 from theopolis/fix_1769

Documentation updates for TLS client-auth and FIM

docs/wiki/deployment/remote.md

@@ -9,12 +9,12 @@ The most important differentiator to the **filesystem** suite of plugins is an a
 The initial step is called an "enroll step" and in the case of **tls** plugins, uses an implicit *enroll* plugin, also called **tls**. If you enable either config or logger **tls** plugins the enrollment plugin will turn on automatically. Enrollment provides an initial secret to the remote server in order to negotiate a private node secret used for future identification. The process is simple:
 
 1. Configure a target `--tls_hostname`, `--enroll_tls_endpoint`.
-2. Place your server's root certificate authority's PEM-encoded certificate into a file, for example `/path/to/server-root.pem` and configure the client to pin this root: `--tls_server_certs=`.
+2. Place your server's root certificate authority's PEM-encoded certificate into a file, for example `/path/to/server-root.pem` and configure the note client to pin this root: `--tls_server_certs=`.
 3. Submit an `--enroll_secret_path`, an `--enroll_secret_env`, or use TLS-client authentication, to the enroll endpoint.
-4. Receive a **node_key** and store within RocksDB.
+4. Receive a **node_key** and store within the node's backing store (RocksDB).
 5. Make config/logger requests while providing **node_key** as identification/authentication.
 
-The validity of a **node_key** is determined and implemented in the TLS server. The client only manages to ask for the content during enroll, and posts the content during subsequent requests.
+The validity of a **node_key** is determined and implemented in the TLS server. The node only manages to ask for the content during enroll, and posts the content during subsequent requests.
 
 With osquery version 1.7.0, OS X clients **MUST** use a `--tls_server_certs` bundle since osquery is built using LibreSSL and no default certificate bundle is available on OS X.
 
@@ -22,7 +22,7 @@ With osquery version 1.7.0, OS X clients **MUST** use a `--tls_server_certs` bun
 
 A deployment key, called an enrollment shared secret, is the simplest **tls** plugin enrollment authentication method. A protected shared secret is written to disk and osquery reads then posts the content to `--enroll_tls_endpoint` once during enrollment. The TLS server may implement an enrollment request approval process that requires manual intervention/approval for each new enrollment request.
 
-After enrollment a client maintains the response **node_key** for authenticated requests to config and logger TLS endpoints.
+After enrollment, a node maintains the response **node_key** for authenticated requests to config and logger TLS endpoints.
 
 The shared secret can be stored in a plain-text file which is specified at runtime with the flag `--enroll_secret_path=/path/to/file.ext`.
 The shared secret can alternatively be kept in an environment variable which is specified with the flag `--enroll_secret_env=NAME_OF_VARIABLE`.
@@ -31,6 +31,8 @@ The shared secret can alternatively be kept in an environment variable which is
 
 If the **node** machines have a deployed TLS client certificate and key they should include those paths using `--tls_client_cert` and `--tls_client_key`. The TLS server may implement an enroll process to supply **nodes** with identifying **node_key**s or return blank keys during enrollment and require TLS client authentication for every endpoint request.
 
+If using TLS client authentication the enrollment step can be skipped entirely. Note that it is NOT skipped automatically. If your service does not need/implement enrollment include `--disable_enrollment` in the osquery configuration.
+
 ## Remote server API
 
 The most basic TLS-based server should implement 3 HTTP POST endpoints. This API is a simple reference and should be built upon using custom plugins based on the included **tls** plugin suite. Although this API is basic, it is functional using the built-in plugins.
@@ -153,6 +155,8 @@ There are several unlisted flags to further control the remote settings. These c
 
 In most cases the client plugins default to "3-strikes-you're-out" when attempting to GET/POST to the configured endpoints. If a configuration cannot be retrieved the client will exit non-0 but a non-responsive logger endpoint will cause logs to buffer in RocksDB. The logging buffer size can be controlled by a [CLI flag](../installation/cli-flags.md), and if the size overflows the logs will drop.
 
+The TLS client does not handle HTTP errors, if the service returns a bad request or otherwise an indicator of overflowed length, the request will fail. The default max size of values combined with the maximum number of log events to send per request are sane and should not overflow default HTTP server maximum request limits.
+
 ## Server testing
 
 We include a very basic example python TLS/HTTPS server: [./tools/tests/test_http_server.py](https://github.com/facebook/osquery/blob/master/tools/tests/test_http_server.py). And a set of unit/integration tests: [./osquery/remote/transports/tests/tls_transports_tests.cpp](https://github.com/facebook/osquery/blob/master/osquery/remote/transports/tests/tls_transports_tests.cpp) for a reference server implementation.

docs/wiki/development/pubsub-framework.md

@@ -26,7 +26,7 @@ The pubsub runflow is exposed as a publisher `setUp()`, a series of `addSubscrip
 
 Filesystem events are the simplest example, let's consider Linux's inotify framework. [osquery/events/linux/inotify.cpp](https://github.com/facebook/osquery/blob/master/osquery/events/linux/inotify.cpp) is exposed as an osquery publisher.
 
-There's an array of yet-to-be-implemented uses of the inotify publisher, but a simple example includes querying for every change to "/etc/passwd". The [osquery/tables/events/linux/passwd_changes.cpp](https://github.com/facebook/osquery/blob/master/osquery/tables/events/linux/passwd_changes.cpp) table uses a pubsub subscription and implements a subscriber.
+There's an array of yet-to-be-implemented uses of the inotify publisher, but a simple example includes querying for every change to "/etc/passwd". The [osquery/tables/events/linux/file_events.cpp](https://github.com/facebook/osquery/blob/master/osquery/tables/events/linux/file_events.cpp) table uses a pubsub subscription and implements a subscriber. The subscriptions are constructed from the configuration. See the file [integrity monitoring deployment](../deployment/file-integrity-monitoring.md) guide for details.
 
 ## Event Subscribers
 

osquery/logger/plugins/filesystem.cpp

@@ -29,7 +29,7 @@ FLAG(string,
      "/var/log/osquery/",
      "Directory path for ERROR/WARN/INFO and results logging");
 
-FLAG(int32, logger_mode, 0640, "Mode for log files (default '0640')");
+FLAG(int32, logger_mode, 0640, "Decimal mode for log files (default '0640')");
 
 /// Legacy, backward compatible "osquery_log_dir" CLI option.
 FLAG_ALIAS(std::string, osquery_log_dir, logger_path);