Add updated proxy settings docs (#271)

* Add updated proxy settings docs

* Add graphics; add standalone section

* Edit + add graphics

* Rename parent

* Keep original name for parent

* Add link to EPR proxy info

docs/en/ingest-management/fleet-agent-proxy-host-variables.asciidoc

@@ -0,0 +1,92 @@
+[[host-proxy-env-vars]]
+= Proxy Server connectivity using default host variables
+
+Set environment variables on the host to configure default proxy settings.
+The {agent} uses host environment settings by default if no proxy settings are
+specified elsewhere. You can override host proxy settings later when you
+configure the {agent} and {fleet} settings. The following environment variables
+are available on the host:
+
+|===
+|Variable |Description
+
+|`HTTP_PROXY`
+|URL of the proxy server for HTTP traffic. 
+
+|`HTTPS_PROXY`
+|URL of the proxy server for HTTPS traffic.
+
+|`NO_PROXY`
+|IP addresses or domain names that should not use the proxy. Supports patterns.
+|===
+
+The proxy URL can be a complete URL or `host[:port]`, in which case the `http`
+scheme is assumed. An error is returned if the value is a different form.
+
+[discrete]
+[[where-to-set-proxy-env-vars]]
+== Where to set proxy environment variables
+
+The location where you set these environment variables is platform-specific and
+based on the system manager you're using. Here are some examples to get you
+started. For more information about setting environment variables, refer to the
+documentation for your operating system.
+
+// lint ignore agent
+* For Windows services, set environment variables for the service in
+the Windows registry.
++
+This PowerShell command sets the
+`HKLM\SYSTEM\CurrentControlSet\Services\Elastic Agent\Environment` registry
+key, then restarts {agent}:
++
+[source,yaml]
+----
+$environment = [string[]]@(
+  "HTTPS_PROXY=https://proxy-hostname:proxy-port",
+  "HTTP_PROXY=http://proxy-hostname:proxy-port"
+  )
+
+Set-ItemProperty "HKLM:SYSTEM\CurrentControlSet\Services\Elastic Agent" -Name Environment -Value $environment
+
+Restart-Service "Elastic Agent"
+----
+
+* For Linux services, the location depends on the distribution you're using.
+For example, you can set environment variables in:
+
+** `/etc/systemd/system/elastic-agent.service` for systems that use `systemd` to
+manage the service. To edit the file, run:
++
+[source,shell]
+----
+sudo systemctl edit --full elastic-agent.service
+----
++
+Then add the environment variables under `[Service]`
++
+[source,shell]
+----
+[Service]
+
+Environment="HTTPS_PROXY=https://my.proxy:8443"
+Environment="HTTP_PROXY=http://my.proxy:8080"
+----
+
+** `/etc/sysconfig/elastic-agent` for Red Hat-like distributions that don't use
+`systemd`.
+
+** `/etc/default/elastic-agent` for Debian and Ubuntu distributions that don't
+use `systemd`.
++
+For example:
++
+[source,shell]
+----
+HTTPS_PROXY=https://my.proxy:8443
+HTTP_PROXY=http://my.proxy:8080
+----
+
+After adding environment variables, restart the service.
+
+NOTE: If you use a proxy server to download new agent versions from `artifacts.elastic.co` for upgrading, configure <<fleet-agent-binary-download-settings>>. 

docs/en/ingest-management/fleet-agent-proxy-managed.asciidoc

@@ -0,0 +1,166 @@
+[[fleet-agent-proxy-managed]]
+= Fleet managed {agent} connectivity using a proxy server
+
+Proxy settings in the {agent} policy override proxy settings specified by environment variables. This means you can specify proxy settings for {agent} that are different from host or system-level environment settings.
+
+This page describes where a proxy server is allowed in your deployment and how to configure proxy settings for {agent} and {fleet}. The steps for deploying the proxy server itself are beyond the scope of this article.
+
+{agents} generally egress two sets of connections, one for Control plane traffic to the {fleet-server}, the other Data plane traffic to an output such as {es}. In a similar fashion operators would place {agent} behind a proxy server, and proxy the control and data plane traffic to their final destinations. 
+
+{fleet} central management enables you to define your proxy servers and then configure an output or the {fleet-server} to be reachable through any of these proxies. This also enables you to modify the proxy server details if needed without having to re-install {agents}. 
+
+image::images/agent-proxy-server-managed-deployment.png[Image showing connections between {fleet} managed {agent}, {fleet-server}, and {es}]
+
+In this scenario Fleet Server and Elasticsearch are deployed in {ecloud} and reachable on port 443.
+
+
+[[fleet-agent-proxy-server-managed-agents]]
+== Configuring proxy servers in {fleet} for managed agents
+
+These steps describe how to set up {fleet} components to use a proxy.
+
+. **Globally add proxy server details to {fleet}.**
+
+.. In {kib}, navigate to the **Fleet** page and go to the **Settings** tab.
+.. Select **Add proxy**. The **Add proxy** or **Edit proxy** flyout opens.
++
+image::images/elastic-agent-proxy-edit-proxy.png[Screen capture of the Edit Proxy UI in Fleet]
++
+.. Add a name for the proxy (in this example `Proxy-A`) and specify the Proxy URL.
+.. Add any other optional settings.
+.. Select **Save and apply settings**. The proxy information is saved and that proxy is ready for other components in {fleet} to reference.
+
+. **Attach the proxy to a {fleet-server}.**
++
+If the control plane traffic to/from the Fleet Server needs to also go through the proxy server, the proxy created needs to also be added to the definition of that Fleet Server.
+
+.. In {kib}, navigate to the **Fleet** page and go to the **Settings** tab.
+.. In the list of **Fleet Server Hosts**, choose a host and select the edit button to configure it.
+.. In the **Proxy** section dropdown list, select the proxy that you configured.
++
+image::images/elastic-agent-proxy-edit-fleet-server.png[Screen capture of the Edit Fleet Server UI]
++
+In this example, All the {agents} in a policy that uses this {fleets-server} will now connect to the {fleet-server} through the proxy server defined in `Proxy-A`.
+
++
+====
+[WARNING]
+Any invalid changes to the {fleet-server} definition that may cause connectivity issues between the {agents} and the {fleet-server} will cause them to disconnect. The only remedy would be to re-install the affected agents. This is because the connectivity to the {fleet-server} ensures policy updates reach the agents. If a policy with an invalid host address reaches the agent it will no longer be able to connect and therefore won't receive any other updates from the {fleet-server} (including the corrected setting). In this regard, adding a proxy server that is not reachable by the agents will break connectivity to the {fleet-server}.
+====
++
+. **Attach the proxy to the output**
++
+Similarly, if the data plane traffic to an output is to traverse via a proxy, that proxy definition would need to be added to the output defined in the Fleet.
+
+.. In {kib}, navigate to the **Fleet** page and go to the **Settings** tab.
+.. In the list of **Outputs**, choose an output and select the edit button to configure it.
+.. In the **Proxy** section dropdown list, select the proxy that you configured.
++
+image::images/elastic-agent-proxy-edit-output.png[Screen capture of the Edit output UI in Fleet]
++
+In this example, All the {agents} in a policy that is configured to write to the chosen output will now write to that output through the proxy server defined in `Proxy-A`.
+
++
+====
+[WARNING]
+If agents are unable to reach the configured proxy server, they will not be able to write data to the output that has the proxy server configured. When changing the proxy of an output, please ensure that the affected agents all have connectivity to the proxy itself.
+====
++
+. **Configure the {agent} policy**
++
+You can now configure the {agent} policy to use the {fleet-server} and the outputs that are reachable through a proxy server.
+
+** If the policy is configured with a {fleet-server} that has a proxy attached to it, all the control plane traffic from the agents in that policy will reach the {fleet-server} through that proxy. 
+** Similarly, if the output definition has a proxy attached to it, all the agents in that policy will write (data plane) to the output through the proxy.
++
+. **Enroll the {agents}**
++
+Now that {fleet} is configured, all policy downloads will update the agent with the latest configured proxies. When the agent is first installed it needs to communicate with {fleet} (through {fleet-server}) in order to download its first policy configuration. 
+
+[discrete]
+[[cli-proxy-settings]]
+== Set the proxy for retrieving agent policies from {fleet}
+
+If there is a proxy between {agent} and {fleet}, specify proxy settings on the
+command line when you install {agent} and enroll in {fleet}. The settings you
+specify at the command line are added to the `fleet.yml` file installed on the
+system where the {agent} is running.
+
+NOTE: If the initial agent communication with {fleet} (i.e control plane) needs to traverse the proxy server, then the agent needs to be configured to do so using the `–proxy-url` command line flag which is applied during the agent installation. Once connectivity to {fleet} is established, proxy server details can be managed through the UI.
+
+NOTE: If {kib} is behind a proxy server, you'll still need to
+<<epr-proxy-setting,configure {kib} settings>> to access the package registry.
+
+The `enroll` and `install` commands accept the following flags:
+
+|===
+| CLI flag | Description
+
+|`--proxy-url <url>`
+|URL of the proxy server. The value may be either a complete URL or a
+`host[:port]`, in which case the `http` scheme is assumed.  The URL accepts optional
+username and password settings for authenticating with the proxy. For example:
+`http://<username>:<password>@<proxy host>/`.
+
+|`--proxy-disabled`
+|If specified, all proxy settings, including the `HTTP_PROXY` and `HTTPS_PROXY`
+environment variables, are ignored.
+
+|`--proxy-header <header name>=<value>`
+|Additional header to send to the proxy during CONNECT requests. Use the
+`--proxy-header` flag multiple times to add additional headers. You can use
+this setting to pass keys/tokens required for authenticating with the proxy.
+
+|===
+
+For example:
+
+[source,sh]
+----
+elastic-agent install --url="https://10.0.1.6:8220" --enrollment-token=TOKEN --proxy-url="http://10.0.1.7:3128" --fleet-server-es-ca="/usr/local/share/ca-certificates/es-ca.crt" --certificate-authorities="/usr/local/share/ca-certificates/fleet-ca.crt"
+----
+
+The command in the previous example adds the following settings to the
+`fleet.yml` policy on the host where {agent} is installed:
+
+[source,yaml]
+----
+fleet:
+  enabled: true
+  access_api_key: API-KEY
+  hosts:
+  - https://10.0.1.6:8220
+  ssl:
+    verification_mode: ""
+    certificate_authorities:
+    - /usr/local/share/ca-certificates/es-ca.crt
+    renegotiation: never
+  timeout: 10m0s
+  proxy_url: http://10.0.1.7:3128
+  reporting:
+    threshold: 10000
+    check_frequency_sec: 30
+  agent:
+    id: ""
+----
+
+NOTE: When {agent} runs, the `fleet.yml` file gets encrypted and renamed to `fleet.enc`.
+
+[[fleet-agent-proxy-server-secure-gateway]]
+== {agent} connectivity using a secure proxy gateway
+
+Many secure proxy gateways are configured to perform mutual TLS and expect all connections to present their certificate. In these instances the Client (in this case the Elastic Agent) would need to present a certificate and key to the Server (the secure proxy). In return the client expects to see a certificate authority chain from the server to ensure it is also communicating to a trusted entity.
+
+image::images/elastic-agent-proxy-gateway-secure.png[Image showing data flow between the proxy server and the Certificate Authority]
+
+If mTLs is a requirement when connecting to your proxy server, then you have the option to add the Client certificate and Client certificate key to the proxy. Once configured, all the Elastic Agents in a policy that connect to this secure proxy (via an output or fleet server), will use the nominated certificates to establish connections to the proxy server.
+
+It should be noted that the user can define a local path to the certificate and key as in many common scenarios the certificate and key will be unique for each Elastic Agent.
+
+Equally important is the Certificate Authority that the agents need to use to validate the certificate they are receiving from the secure proxy server. This can also be added when creating the proxy definition in the Fleet settings.
+
+image::images/elastic-agent-edit-proxy-secure-settings.png[Screen capture of the Edit Proxy UI, highlighting the Certificate and Certificate key settings]
+
+NOTE: Currently {agents} will not present a certificate for Control Plane traffic to the {fleet-server}. Some proxy servers are setup to mandate that the client setting up a connection presents a certificate to them before allowing that client to connect. This issue will be resolved by link:https://github.com/elastic/elastic-agent/issues/2248[issue #2248]. Our recommendation is to avoid adding a secure proxy as such in a {fleet-server} configuration flyout.
+
+NOTE: In case {kib} is behind a proxy server or is otherwise unable to access the {package-registry} to download package metadata and content, refer to <<epr-proxy-setting>>.

docs/en/ingest-management/fleet-agent-proxy-package-registry.asciidoc

@@ -0,0 +1,19 @@
+[[epr-proxy-setting]]
+= Set the proxy URL of the {package-registry}
+
+{fleet} might be unable to access the {package-registry} because {kib} is
+behind a proxy server.
+
+Also your organization might have network traffic restrictions that prevent {kib}
+from reaching the public {package-registry} (EPR) endpoints, like
+https://epr.elastic.co/[epr.elastic.co], to download package metadata and
+content. You can route traffic to the public endpoint of EPR through a network
+gateway, then configure proxy settings in the
+{kibana-ref}/fleet-settings-kb.html[{kib} configuration file], `kibana.yml`. For
+example:
+
+[source,yaml]
+----
+xpack.fleet.registryProxyUrl: your-nat-gateway.corp.net
+----
+

docs/en/ingest-management/fleet-agent-proxy-standalone.asciidoc

@@ -0,0 +1,53 @@
+[[fleet-agent-proxy-standalone]]
+= Standalone {agent} connectivity using a proxy server
+
+Proxy settings in the {agent} policy override proxy settings specified by
+environment variables. This means you can specify proxy settings for {agent}
+that are different from host or system-level environment settings. 
+
+The following proxy settings are valid in the agent policy:
+
+|===
+|Setting | Description
+
+|`proxy_url`
+| (string) URL of the proxy server. If set, the configured URL is used as a
+proxy for all connection attempts by the component. The value may be either a
+complete URL or a `host[:port]`, in which case the `http` scheme is assumed. If
+a value is not specified through the configuration, then proxy environment
+variables are used. The URL accepts optional `username` and `password` settings
+for authenticating with the proxy. For example:
+`http://<username>:<password>@<proxy host>/`.
+
+|`proxy_headers`
+| (string) Additional headers to send to the proxy during CONNECT requests. You
+can use this setting to pass keys/tokens required for authenticating with the
+proxy.
+
+|`proxy_disable`
+| (boolean) If set to `true`, all proxy settings, including the `HTTP_PROXY` and
+`HTTPS_PROXY` environment variables, are ignored.
+
+|===
+
+[discrete]
+=== Set the proxy for communicating with {es}
+
+//To set the proxy for communicating with {es}, specify proxy settings under
+//`outputs` in the agent policy. The procedure for doing this depends on
+//whether you're running {fleet}-managed or standalone agents:
+
+For standalone agents, to set the proxy for communicating with {es}, specify proxy settings in the `elastic-agent.yml` file. For example:
+
+[source,yaml]
+----
+outputs:
+  default:
+    api_key: API-KEY
+    hosts:
+    - https://10.0.1.2:9200
+    proxy_url: http://10.0.1.7:3128
+    type: elasticsearch
+----
+
+For more information, refer to <<elastic-agent-configuration>>.