docs: document limits

Taken more or less verbatim from Consul.

Author: schmichael

website/source/docs/configuration/index.html.md

@@ -177,6 +177,57 @@ testing.
   server agents if it is expected that a terminated server instance will never
   join the cluster again.
 
+- `limits` - Available in Nomad 0.10.3 and later, this is a nested object that
+  configures limits that are enforced by the agent. The following parameters
+  are available:
+
+  - `https_handshake_timeout` `(string: "5s")` - Configures the limit for how
+    long the HTTPS server in both client and server agents will wait for a
+    client to complete a TLS handshake. This should be kept conservative as it
+    limits how many connections an unauthenticated attacker can open if
+    [`tls.http = true`][tls] is being used (strongly recommended in
+    production).  Default value is `5s`. `0` disables HTTP handshake timeouts.
+
+  - `http_max_conns_per_client` `(int: 100)` - Configures a limit of how many
+    concurrent TCP connections a single client IP address is allowed to open to
+    the agent's HTTP server. This affects the HTTP servers in both client and
+    server agents. Default value is `100`. `0` disables HTTP connection limits.
+
+  - `rpc_handshake_timeout` `(string: "5s")` - Configures the limit for how
+    long servers will wait after a client TCP connection is established before
+    they complete the connection handshake. When TLS is used, the same timeout
+    applies to the TLS handshake separately from the initial protocol
+    negotiation. All Nomad clients should perform this immediately on
+    establishing a new connection. This should be kept conservative as it
+    limits how many connections an unauthenticated attacker can open if
+    TLS is being using to authenticate clients (strongly recommended in
+    production). When `tls.rpc` is true on servers, this limits how long the
+    connection and associated goroutines will be held open before the client
+    successfully authenticates. Default value is `5s`. `0` disables RPC handshake
+    timeouts.
+
+  - `rpc_max_conns_per_client` `(int: 100)` - Configures a limit of how
+    many concurrent TCP connections a single source IP address is allowed
+    to open to a single server. Client agents do not accept RPC TCP connections
+    directly and therefore are not affected. It affects both clients connections
+    and other server connections. Nomad clients multiplex many RPC calls over a
+    single TCP connection, except for streaming endpoints such as [log
+    streaming][log-api] which require their own connection when routed through
+    servers. A server needs at least 2 TCP connections (1 Raft, 1 RPC) per peer
+    server locally and in any federated region. Servers also need a TCP connection
+    per routed streaming endpoint concurrently in use. Only operators use streaming
+    endpoints; as of 0.10.3 Nomad client code does not. A reasonably low limit
+    significantly reduces the ability of an unauthenticated attacker to consume
+    unbounded resources by holding open many connections. You may need to
+    increase this if WAN federated servers connect via proxies or NAT gateways
+    or similar causing many legitimate connections from a single source IP.
+    Default value is `100` which is designed to support the majority of users.
+    `0` disables RPC connection limits. `26` is the minimum as `20` connections
+    are always reserved for non-streaming connections (Raft and RPC) to ensure
+    streaming RPCs do not prevent normal server operation. This minimum may be
+    lowered in the future when streaming RPCs no longer require their own TCP
+    connection.
+
 - `log_level` `(string: "INFO")` - Specifies  the verbosity of logs the Nomad
   agent will output. Valid log levels include `WARN`, `INFO`, or `DEBUG` in
   increasing order of verbosity.
@@ -250,7 +301,7 @@ testing.
 - `syslog_facility` `(string: "LOCAL0")` - Specifies the syslog facility to
   write to. This has no effect unless `enable_syslog` is true.
 
-- `tls` `(`[`TLS`]`: nil)` - Specifies configuration for TLS.
+- `tls` `(`[`TLS`][tls]`: nil)` - Specifies configuration for TLS.
 
 - `vault` `(`[`Vault`]`: nil)` - Specifies configuration for
   connecting to Vault.
@@ -283,7 +334,8 @@ http_api_response_headers {
 [`Plugin`]: /docs/configuration/plugin.html "Nomad Agent Plugin Configuration"
 [`Sentinel`]: /docs/configuration/sentinel.html "Nomad Agent sentinel Configuration"
 [`Server`]: /docs/configuration/server.html "Nomad Agent server Configuration"
-[`TLS`]: /docs/configuration/tls.html "Nomad Agent tls Configuration"
+[tls]: /docs/configuration/tls.html "Nomad Agent tls Configuration"
 [`Vault`]: /docs/configuration/vault.html "Nomad Agent vault Configuration"
 [go-sockaddr/template]: https://godoc.org/github.com/hashicorp/go-sockaddr/template
+[log-api]: /api/client.html#stream-logs
 [hcl]: https://github.com/hashicorp/hcl "HashiCorp Configuration Language"

website/source/guides/upgrade/upgrade-specific.html.md

@@ -15,6 +15,30 @@ details provided for their upgrades as a result of new features or changed
 behavior. This page is used to document those details separately from the
 standard upgrade flow.
 
+## Nomad 0.10.3
+
+### Connection Limits Added
+
+Nomad 0.10.3 introduces the [limits][limits] agent configuration parameters for
+mitigating denial of service attacks from users who are not authenticated via
+mTLS. The default limits stanza is:
+
+```hcl
+limits {
+  https_handshake_timeout   = "5s"
+  http_max_conns_per_client = 100
+  rpc_handshake_timeout     = "5s"
+  rpc_max_conns_per_client  = 100
+}
+```
+
+If your Nomad agent's endpoints are protected from unauthenticated users via
+other mechanisms these limits may be safely disabled by setting them to `0`.
+
+However the defaults were chosen to be safe for a wide variety of Nomad
+deployments and may protect against accidental abuses of the Nomad API that
+could cause unintended resource usage.
+
 ## Nomad 0.10.2
 
 ### Preemption Panic Fixed
@@ -385,6 +409,7 @@ deleted and then Nomad 0.3.0 can be launched.
 [dangling-containers]:  /docs/drivers/docker.html#dangling-containers
 [gh-6787]: https://github.com/hashicorp/nomad/issues/6787
 [hcl2]: https://github.com/hashicorp/hcl2
+[limits]: /docs/configuration/index.html#limits
 [lxc]: /docs/drivers/external/lxc.html
 [migrate]: /docs/job-specification/migrate.html
 [plugins]: /docs/drivers/external/index.html