From 7f83ae1fafa5f5ab1c56fab4dd93db4702fb9e34 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 12 Jun 2018 17:58:31 +0200 Subject: [PATCH] website: document proxy security settings --- website/source/docs/agent/options.html.md | 8 ++++- website/source/docs/agent/services.html.md | 33 ++++++++++++++++----- website/source/docs/connect/proxies.html.md | 7 +++++ 3 files changed, 39 insertions(+), 9 deletions(-) diff --git a/website/source/docs/agent/options.html.md b/website/source/docs/agent/options.html.md index 0a558c0e53..2ff49d3f64 100644 --- a/website/source/docs/agent/options.html.md +++ b/website/source/docs/agent/options.html.md @@ -703,7 +703,13 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass duration value such as `720h`. Only applies in the case where the private key or root certificate are left blank. Defaults to `2160h` (90 days). - * `proxy_defaults` TODO + * `proxy` This object allows setting options for the Connect proxies. The following sub-keys are available: + + * `allow_managed_api_registration` Allows managed proxies to be configured with services that are registered via the Agent HTTP API. Enabling this would allow anyone with permission to register a service to define a command to execute for the proxy. By default, this is false to protect against arbitrary process execution. + + * `allow_managed_root` Allows Consul to start managed proxies if Consul is running as root (EUID of the process is zero). We recommend running Consul as a non-root user. By default, this is false to protect inadvertently running external processes as root. + + * `proxy_defaults` This object configures the default proxy settings for [service definitions with managed proxies](/docs/agent/services.html). It accepts the fields `exec_mode`, `daemon_command`, and `config`. These are used as default values for the respective fields in the service definition. * `datacenter` Equivalent to the [`-datacenter` command-line flag](#_datacenter). diff --git a/website/source/docs/agent/services.html.md b/website/source/docs/agent/services.html.md index bfac46d4d7..bf9204690b 100644 --- a/website/source/docs/agent/services.html.md +++ b/website/source/docs/agent/services.html.md @@ -17,7 +17,15 @@ or added at runtime over the HTTP interface. ## Service Definition -A service definition is a script that looks like: +To configure a service, either provide the service definition as a `-config-file` option to +the agent or place it inside the `-config-dir` of the agent. The file +must end in the `.json` or `.hcl` extension to be loaded by Consul. Check +definitions can be updated by sending a `SIGHUP` to the agent. +Alternatively, the service can be registered dynamically using the [HTTP +API](/api/index.html). + +A service definition is a configuration that looks like the following. This +example shows all possible fields, but note that only a few are required. ```javascript { @@ -35,7 +43,14 @@ A service definition is a script that looks like: "args": ["/usr/local/bin/check_redis.py"], "interval": "10s" } - ] + ], + "connect": { + "native": false, + "proxy": { + "command": [], + "config": {} + } + } } } ``` @@ -117,12 +132,14 @@ For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 supports both `enable_tag_override` and `enableTagOverride` but the latter is deprecated and has been removed as of Consul 1.1. -To configure a service, either provide it as a `-config-file` option to -the agent or place it inside the `-config-dir` of the agent. The file -must end in the `.json` or `.hcl` extension to be loaded by Consul. Check -definitions can be updated by sending a `SIGHUP` to the agent. -Alternatively, the service can be registered dynamically using the [HTTP -API](/api/index.html). +The `connect` field can be specified to configure [Connect](/docs/connect/index.html) +for a service. This field is available in Consul 1.2 and later. The `native` +value can be set to true to advertise the service as +[Connect-native](/docs/connect/native.html). If the `proxy` field is set +(even to an empty object), then this will enable a +[managed proxy](/docs/connect/proxies.html) for the service. The fields within +`proxy` are used to configure the proxy and are specified in the +[proxy docs](/docs/connect/proxies.html). ## Multiple Service Definitions diff --git a/website/source/docs/connect/proxies.html.md b/website/source/docs/connect/proxies.html.md index 8cbcf38d52..deb36a9eac 100644 --- a/website/source/docs/connect/proxies.html.md +++ b/website/source/docs/connect/proxies.html.md @@ -47,6 +47,13 @@ integrating with advanced proxies in the near future to support more complex configurations and higher performance. The configuration below is all for the built-in proxy. +-> **Security note:** 1.) Managed proxies can only be configured +via agent configuration files. They _cannot_ be registered via the HTTP API. +And 2.) Managed proxies are not started at all if Consul is running as root. +Both of these default configurations help prevent arbitrary process +execution or privilege escalation. This behavior can be configured +[per-agent](/docs/agent/options.html#connect_proxy). + ### Minimal Configuration Managed proxies are configured within a