Merge pull request #1402 from mickem/feature/installer-fleet-enrollment

feature: Enroll with a fleet server from the installer

Author: mickem

docs/docs/setup/installing.md

@@ -23,6 +23,7 @@ See [Supported platforms](supported-platforms.md) for the Windows and Linux vers
   - [Silent install](#silent-install)
   - [Debugging](#debugging)
 - [Specifying your monitoring tool](#specifying-your-monitoring-tool)
+- [Enrolling with a fleet server](#enrolling-with-a-fleet-server)
 - [Copy configuration from a HTTP server](#copy-configuration-from-a-http-server)
 - [Use configuration from a HTTP server](#use-configuration-from-a-http-server)
 
@@ -243,6 +244,12 @@ A list of all the MSI options can be found below.
 | TLS_CA              | The CA file to use for TLS connections (defaults to the Windows ROOT store)                                             |
 | CONF_SET            | Set a configuration value in the form of section1;key1;value1;section2;key2;value2...                                   |
 | IMPORT_CONFIG       | URL or file path to a configuration file to copy during install and use as the configuration for NSClient++             |
+| FLEET_SERVER        | Fleet server url (`https://fleet.example.com`) to enroll this host with during install                                  |
+| FLEET_TOKEN         | The one-time bootstrap token from the install command generated by the fleet server (required with FLEET_SERVER)        |
+| FLEET_HOSTNAME      | Host name to report to the fleet server (defaults to this machine's host name)                                          |
+| FLEET_CA            | CA bundle used to verify the fleet server certificate (defaults to the Windows ROOT store)                              |
+| FLEET_VERIFY_MODE   | TLS verify mode for the enrollment call (*certificate*, none). `none` requires FLEET_INSECURE=1                         |
+| FLEET_INSECURE      | Set to 1 to allow an unauthenticated enrollment: a plain `http://` FLEET_SERVER, or FLEET_VERIFY_MODE=none              |
 
 ### Features
 
@@ -314,6 +321,51 @@ In this case setting `MONITORING_TOOL` is done automatically when ever `OP5_SERV
 msiexec /i NSClient++.msi OP5_SERVER=https://op5.com OP5_USER=monitor OP5_PASSWORD=rotinom
 ```
 
+## Enrolling with a fleet server
+
+If you manage your agents from an NSClient fleet server, the installer can enroll the host while it installs, so the
+machine is managed from the moment the service starts. Generate an install command on the fleet server and pass the
+server url and the bootstrap token it gives you:
+
+```
+msiexec /qn /i NSCP-<version>-x64.msi FLEET_SERVER=https://fleet.example.com FLEET_TOKEN=<bootstrap-token>
+```
+
+During the install NSClient++ generates a key pair, sends a certificate request together with the token to
+`FLEET_SERVER`, and stores the certificate material it gets back as `agent-state.json` in the `security` folder of the
+installation. It also adds an include for the fleet-managed configuration
+(`[/includes] fleet = ${shared-path}/fleet/fleet.ini`). The service picks all of this up on the next start and begins
+syncing its configuration from the fleet server; there is no module to enable.
+
+A few things worth knowing:
+
+- **Enrollment is required to succeed.** If the fleet server cannot be reached, or rejects the token, the install fails
+  with an error explaining what went wrong rather than leaving you with an agent that never joined the fleet. Bootstrap
+  tokens are one-time and are burned on first use, so a rejected token means generating a new install command.
+- **The installer has to be allowed to write the configuration.** Enrollment is what adds the include that makes the
+  host read what the fleet server sends it, so combining `FLEET_SERVER` with `ALLOW_CONFIGURATION=0` - or installing
+  onto a configuration the installer cannot update - fails the install rather than enrolling a host that then ignores
+  everything the fleet server tells it. The install log names the reason the configuration was held to be unchangeable.
+- **An already enrolled host keeps its identity.** If `agent-state.json` already exists (an upgrade, a repair, or a
+  re-install over an existing installation) the enrollment is skipped and the existing identity is kept. Delete the file
+  to enroll again.
+- **Uninstalling discards the enrollment.** `agent-state.json` holds this host's private key and client certificate, so
+  uninstalling removes it along with the other key material. The identity does not survive an uninstall/reinstall cycle,
+  and because bootstrap tokens are one-time you need a fresh install command from the fleet server to enroll again -
+  keep the host's registration on the server in mind before uninstalling to reinstall. Upgrading in place is unaffected.
+- **The fleet server is verified.** The enrollment response supplies the certificate the agent pins for every later call
+  and the key it trusts for executable bundles, so the connection is verified against the Windows ROOT store by default.
+  Use `FLEET_CA=<file>` if the fleet server uses a private CA. `FLEET_INSECURE=1` (with a `http://` url and/or
+  `FLEET_VERIFY_MODE=none`) opts out of that, which is only reasonable on a trusted network or for testing.
+- **Keep the token out of your logs.** The token is hidden from the MSI log, but treat the deployment script that
+  carries it as a secret; the token is a credential that exchanges for this host's client certificate.
+
+The same enrollment can be done after installation with the command line:
+
+```
+nscp enroll --server https://fleet.example.com --token <bootstrap-token>
+```
+
 ## Copy configuration from a HTTP server
 
 Staring with version 0.10.5 it is possible to download a configuration file from a HTTP server and use that as

include/onboarding/onboarding.hpp

@@ -80,6 +80,15 @@ struct enrollment_request {
   std::string ca;           // CA bundle used to verify the server
 
   unsigned int max_attempts = 3;  // attempts for retryable failures (429/5xx/network)
+
+  // Deadline for a single read or write on the enrollment call, in seconds (0
+  // waits forever). max_attempts does not bound the wait on its own: it only
+  // counts requests that finished, and a server that accepts the connection
+  // and then stops answering never produces one. That matters most from the
+  // installer, where the call runs inside a deferred custom action - an
+  // unbounded wait wedges msiexec mid-script on an unattended install with
+  // nobody there to interrupt it. Same default as the fleet sync's `timeout`.
+  unsigned int timeout_seconds = 60;
 };
 
 // Everything a successful enrollment returns plus the locally generated