From 0bd699c999611ec8735e30b747b57612caabd530 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Tue, 15 Oct 2024 08:21:31 -0400 Subject: [PATCH] Dheath 0.18.0 assembly (#5175) * docs: TS public beta docs * docs: Updates * docs: Move Client Agent sections * docs: Updates * docs: Fix typo * docs: Remove x86 * docs: Add lead in sentence for links * docs: FAQ updates * docs: Edits and file name fixes * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Irena Rindos * docs: Add alias refresh interval * docs: Remove recurse only option * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn * Update website/content/docs/concepts/transparent-sessions.mdx Co-authored-by: Johan Brandhorst-Satzkorn * docs: Updates from code review * docs: Update support request * docs: Fix a typo * Update website/content/docs/api-clients/client-agent.mdx Co-authored-by: Johan Brandhorst-Satzkorn * docs: Delete log example, create tabs * client-agent: rework configuration docs The section in the configuration talking about reloading the config was repetitive and verbose. Combine the different sections into two separate sections, one for updating general values and one for reloading values, on MacOS only. This also removes the specific Log section. * docs: Minor rewrites * client-agent: consistently use $ for shell sessions * aliases: discourage single-word aliases The use of single-word aliases breaks Transparent Sessions on Windows, so we should discourage it. See ICU-15255 for more information. * transparent-sessions: add known issues Add two new known issues. * client-agent: add troubleshooting section * transparent-sessions: emphasize troubleshooting guide * correct links I haven't actually validated these links, but they are now consistent with the rest of the links. * Review comments * client-agent: clarify that not all sessions are listed by command * transparent-session: add known issue regarding Windows installer * docs: Minor rewrites * docs: Fix a typo * docs: Add AssumeRole support * docs: Add Backblaze support * docs: Minor revision * docs: Update MinIO reqs * docs: Add supported Hitachi version * docs: Trigger a new build * docs: Clarify Desktop compatibility with control plane * Update website/content/docs/enterprise/supported-versions.mdx Co-authored-by: Robin Beck * docs: Release notes 0.18.0 * docs: Add link to Client Agent docs * docs: Update ts definition * docs: Remove stray line * docs: Fix minor issues with the assembly branch * docs: Move section * docs: Add section * docs: Remove duplicate section --------- Co-authored-by: Irena Rindos Co-authored-by: Johan Brandhorst-Satzkorn Co-authored-by: Robin Beck --- .../content/docs/api-clients/client-agent.mdx | 629 ++++++++++++++++++ website/content/docs/concepts/aliases.mdx | 26 +- .../concepts/connection-workflows/index.mdx | 14 +- .../docs/concepts/host-discovery/aws.mdx | 6 +- .../docs/concepts/transparent-sessions.mdx | 97 +++ .../storage-providers/configure-minio.mdx | 3 + .../configure-s3-compliant.mdx | 16 +- .../docs/enterprise/supported-versions.mdx | 18 +- .../content/docs/release-notes/v0_18_0.mdx | 172 +++++ website/content/partials/alerts/beta.mdx | 6 + .../partials/alerts/enterprise-only.mdx | 1 + website/data/docs-nav-data.json | 22 + 12 files changed, 1001 insertions(+), 9 deletions(-) create mode 100644 website/content/docs/api-clients/client-agent.mdx create mode 100644 website/content/docs/concepts/transparent-sessions.mdx create mode 100644 website/content/docs/release-notes/v0_18_0.mdx create mode 100644 website/content/partials/alerts/beta.mdx create mode 100644 website/content/partials/alerts/enterprise-only.mdx diff --git a/website/content/docs/api-clients/client-agent.mdx b/website/content/docs/api-clients/client-agent.mdx new file mode 100644 index 0000000000..c3206a3113 --- /dev/null +++ b/website/content/docs/api-clients/client-agent.mdx @@ -0,0 +1,629 @@ +--- +layout: docs +page_title: Client Agent +description: |- + Learn how the Boundary Client Agent intercepts DNS requests as the primary resolver on the system, allowing Boundary to proxy connections transparently. +--- + +# Boundary Client Agent + +@include 'alerts/enterprise-only.mdx' + +@include 'alerts/beta.mdx' + +The Boundary Client Agent is Boundary's DNS daemon. +When the Boundary Client Agent runs alongside an authenticated Boundary client, the agent establishes itself as the primary resolver on the system and intercepts DNS requests. + +If you enter a hostname that matches a Boundary alias that the client is authorized to establish a session to, Boundary automatically generates the session and transparently proxies the connection on your behalf. +If the Boundary Client Agent cannot find an alias, or if there are any issues with authentication, network connectivity, or latency, the Client Agent defers DNS resolution to the previously configured DNS resolvers. + +## Security + +When you successfully authorize a session on a Boundary controller, the response includes a list of any brokered credentials, which include the decoded secrets. +When the Boundary Client Agent receives a DNS request, Boundary creates a new session. +An OS user can only connect to an authorized session managed by the Boundary Client Agent daemon if they are the same OS user that added the Boundary auth token used for authorizing the session. + + + +Currently, you cannot authenticate to multiple Boundary controllers at once. +If you authenticate to a different Boundary controller, any existing sessions are terminated and any new transparent sessions would be established with the new controller. + + + +The Boundary Client Agent stores the credentials and some other information related to the session in memory. +The in-memory store removes the session information: + +- when the session ends. +- if the auth token stored in the Boundary expires. +- if the current OS user authenticates with a different Boundary user. +- if the current OS user authenticates to a new Boundary controller. +- if the Boundary Client Agent is paused. +- if the Boundary Client Agent is terminated. + +API requests are authenticated in the same way as session proxy access. + +Credential brokering is supported for transparent sessions. +A notification appears when you establish a session against a target that is configured with credential brokering. +You can retrieve the credentials later using the following command: + +```shell-session +$ boundary client-agent sessions +``` + +### Grants + +The default grants that Boundary creates for anonymous and authenticated users are sufficient to get started with the Client Agent for the public beta. +However, in a production scenario, you may want to provide the least amount of privileges necessary for users. +For a Boundary user to be able to use the Client Agent to establish a transparent session, they must: + +- be able to authenticate using an auth method. +- have read permissions for their auth token. +- have permission to establish a session to one or more targets. + +You can use the following grant strings to grant those permissions: + +``` +type=auth-method;ids=*;actions=authorize +type=target;ids=*;actions=authorize-session +type=auth-token;ids=*;actions=read:self +``` + +HashiCorp highly recommends that you also grant users the permission to list resolvable aliases, as the Client Agent periodically fetches a list of aliases to match incoming DNS requests against. +Without that permission, every DNS request on the system is sent to the Boundary controller, which can easily overwhelm it. +You can use the following grant string to grant the permission to list resolvable aliases: + +``` +type=user;ids=*;actions=list-resolvable-aliases +``` + +## Configuration + +The default configuration included with the Boundary Client Agent upon installation will be suitable for most users. If you want to make changes to the configuration, the configuration file is located in the following directory: + + + + + `/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.hcl` + + + + + `C:\Program Files\Hashicorp Boundary\boundary-client-agent.hcl` + + + + +The configuration file contains the following fields: + +- `alias_refresh_interval` - Specifies how often to refresh the alias cache. The default value is 1 minute. + + Example: + ```hcl + alias_refresh_interval=60s + ``` + +- `dns_request_timeout` - Specifies for how long the Client Agent DNS request handling, including any recursion, is allowed to run before it is canceled. + + Example: + ```hcl + dns_request_timeout=300s + ``` + +- `interface_to_use` - Specifies the interface to use instead of the default. + + Example: + ```hcl + interface_to_use=en1 + ``` + +- `log_file` - Specifies where to write the Boundary Client Agent log file to. + + Example: + ```hcl + log_file="/Library/Application\ /Support/HashiCorp/Boundary/boundary-client-agent.log" + ``` + +- `log_level` - Specifies the verbosity of the Client Agent logs. + + Example: + ```hcl + log_level=DEBUG + ``` + +- `log_to_stdout` - Logs to STDOUT in addition to the `boundary-client-agent.log` file. + + Example: + ```hcl + log_to_stdout=false + ``` + +- `override_upstream_dns_servers` - Lists the DNS servers that should be used for recursing non-Boundary requests, overriding those configured on the system. + + Example: + ```hcl + override_upstream_dns_servers = ["8.8.8.8", "8.8.4.4"] + ``` + +- `state_file` - Specifies where to write the Boundary Client Agent state file to. This is an ephemeral file which is removed on successful shutdown. + + Example: + ```hcl + state_file="/Library/Application\ /Support/HashiCorp/Boundary/boundary-client-agent-state.json" + ``` + +- `v4_prefix` - Specifies an alternate prefix to use for generating IPs. Currently must be between /8 and /16 + + Example: + ```hcl + v4_prefix=1.1.1.1/8 + ``` + +### Change the configuration + +Complete the following steps to change the configuration of the Client Agent: + + + + +1. As a privileged user, open the Boundary Client Agent configuration file in the editor of your choice. +By default, it is located in the following directory: + + `/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.hcl` + +1. Change the configuration settings. +1. Save the file and restart the Client Agent with the following commands: + + ```shell-session + $ sudo launchctl stop com.hashicorp.boundary.boundary-client-agent + $ sudo launchctl start com.hashicorp.boundary.boundary-client-agent + ``` + +You can change some configuration values without restarting the Client Agent. +These values include: + +- `dns_request_timeout` +- `log_file` +- `log_level` +- `state_file` +- `override_upstream_dns_servers` +- `v4_prefix` + +To update the other values, you must reload the configuration. +To reload the configuration, update the configuration file, and then use the following command: + +```shell-session +$ sudo pkill -1 boundary-client-agent +``` + +This command sends a SIGHUP signal to the Client Agent, which causes it to reload the configuration file. + + + + +1. As a privileged user, open the Boundary Client Agent configuration file in the editor of your choice. +By default, it is located in the following directory: + + `C:\Program Files\Hashicorp Boundary\boundary-client-agent.hcl` +1. Change the configuration settings. +1. Save the file and restart the Client Agent with the following commands: + + ```shell-session + net stop BoundaryClientAgent + net start BoundaryClientAgent + ``` + + + + +Note that when you restart the Client Agent, it closes any existing sessions. + +## Manage the Client Agent + +Refer to the following sections for more information about managing the Client Agent. +You can monitor the Client Agent's status and retrieve information about any transparent sessions. +If you want to temporarily defer DNS resolution to any previously configured DNS resolvers, you can pause the Client Agent. +You can also disable the Client Agent, if you no longer want to use it for DNS resolution. + +### Monitor status and sessions + +You can check the status of the Client Agent to ensure it is running. +Use the following command to check the Client Agent's status: + +```shell-session +$ boundary client-agent status +``` + +You can retrieve information about the sessions that the Client Agent is managing. +Use the following command to list any sessions currently being managed by the Client Agent, as well as any brokered credentials for those sessions: + +```shell-session +$ boundary client-agent sessions +``` + +Note that this command does not list sessions that are not managed by the Client Agent. Use `boundary sessions list -recursive` to see all sessions. + +### Pause the Client Agent + +You can temporarily disable the Boundary Client Agent by pausing it with the following command: + +```shell-session +$ boundary client-agent pause +``` + +When the Client Agent is paused, it does not intercept any DNS requests, and you are unable to use transparent sessions. + +To resume the Client Agent, use the following command: + +```shell-session +$ boundary client-agent resume +``` + +### Disable the Client Agent + +If you want to disable the Boundary Client Agent, you can stop it with the following commands: + + + + +```shell-session +$ sudo launchctl stop com.hashicorp.boundary.boundary-client-agent +``` + + + + +```shell-session +net stop BoundaryClientAgent +``` + + + + +## Troubleshooting + +The following sections can help you to troubleshoot the Client Agent's behavior. You should proceed through these steps from top to bottom. + +### Check the status of the Client Agent + +If you experience unexpected behavior, you should first check on the status of the Client Agent. +You can check the status using the Boundary CLI or the Desktop Client. To check the Client Agent status through the Boundary CLI, use the following command: + +```shell-session +$ boundary client-agent status + +Status: + Address: + https://boundary.corp.com + Auth Token Expiration: 167h58m9s + Auth Token Id: at_GBqZUK2ihv + Status: running + Version: 0.0.1-e561e69839cce148ee5045684bce5b7168c65026 +``` + +In the Desktop Client, you can find the status of the Client Agent by navigating to **Settings**, and then scrolling to the **Boundary Client Agent** section. + +The status command includes various information about the Client Agent, including the runtime status. +In this example, the runtime status is "running". +If the status is "paused", the Client Agent is not currently intercepting DNS requests and must be resumed. +Users can pause the Client Agent, and it will also pause itself if it detects a large number of network failures in a short period of time. + +The status also allows you to see whether the current user is authenticated. +If the response looks like the example above, including showing an auth token ID and expiration, your current user is authenticated. +If not, you may need to first authenticate to the Client Agent using the CLI or Desktop Client. + +The status also sometimes contains a list of errors that have been encountered by the Client Agent. +The list is ordered by most recent first. +These errors can help you understand why the Client Agent may not be behaving as expected. +Please see the section below on commonly seen errors to help diagnose specific errors. +Note that this list of errors will not be cleared until the next reboot, so it may not necessarily be a sign of something being wrong. + +If the status command returns an error, the Client Agent may not be running. +You can attempt to start the Client Agent using the following commands: + + + + + ```shell-session + $ sudo launchctl start com.hashicorp.boundary.boundary-client-agent + ``` + + + + + ```shell-session + net start BoundaryClientAgent + ``` + + + +### Resume the Client Agent + +You can resume the Client Agent using either the Boundary CLI or the Desktop Client. In the CLI, run the following command to resume the Client Agent: + +```shell-session +$ boundary client-agent resume +The Client Agent has been successfully resumed. +``` + +In the Desktop Client, you can resume the Client Agent by selecting the **Resume** button in the **Boundary Client Agent** section of the settings. +Once the Client Agent has resumed, test if it has started working as expected again. + +### Inspect the log file + +If you are not able to diagnose the problem by looking at the status or resuming the Client Agent, another step can be to inspect the log file produced by the Client Agent. + + + + +The log file should be located in `/Library/Application Support/HashiCorp/Boundary/boundary-client-agent.log`. + + + + +The log file should be located in `C:\Windows\Logs\boundary-client-agent.log`. + + + + +Once you have found the log file, you can look through it to see if you can understand why the Client Agent is not working as expected. +The list below provides some common errors and explanations. + +It may be necessary to increase the logging verbosity of the Client Agent. +You can increase the verbosity by setting the `log_level` option in the configuration file to `DEBUG`. +See the section on changing the configuration for more information. + +### Establish the behavior of the local DNS configuration + +The Client Agent works by intercepting DNS requests before they are sent to your regular DNS server. +If the DNS requests on your system are not sent to the right place, or they are not being answered appropriately, transparent sessions will not work. + +You can use the `nslookup` command to understand where the DNS requests are being sent. +Start by sending a DNS request for `hashicorp.com`: + +```shell-session +$ nslookup hashicorp.com +;; Truncated, retrying in TCP mode. +Server: 100.88.241.86 +Address: 100.88.241.86#53 + +Non-authoritative answer: +Name: hashicorp.com +Address: 76.76.21.21 +``` + +The important part here is the `Server` field, which contains an IP in the CGNAT range (from `100.64.0.0` to `100.127.255.255`). +This is a good indication that the Client Agent DNS server is being used as expected. + +Next, you can try to make a DNS request to an alias that you expect to work. The following example makes a DNS request to an alias with a value of `mytarget.boundary.dev`: + +```shell-session +$ nslookup mytarget.boundary.dev +;; Truncated, retrying in TCP mode. +Server: fc00:a20a::d7bf:c059 +Address: fc00:a20a::d7bf:c059#53 + +Name: mytarget.boundary.dev +Address: 100.84.164.9 +``` + +You can tell two things from this: +1. The Client Agent is likely able to intercept the DNS request, because the server is a local IPv6 address in the [ULA](https://en.wikipedia.org/wiki/Unique_local_address) range. + Both an IPv4 CGNAT range or IPv6 ULA range IP address are indications of this. +2. The Client Agent is able to identify `mytarget.boundary.dev` as an alias with a target that the requesting user is authorized to connect to, because it responded with a valid DNS response pointing to a local IPv4 address in the CGNAT range. + Similarly to above, the IP address in the response may also be an IPv6 address in the ULA range. + +If you do not see this kind of response, it may be that the alias you are trying to connect to doesn't exist, or your user is not authorized to connect to it. +Double check that you are using the correct alias and that your user is authorized to connect to it. + +### Flush OS DNS cache + +If you still do not see the expected behavior, it can be useful to flush the operating system's DNS cache. +The exact steps depend on the operating system you use: + + + + +```shell-session +$ sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder +``` + + + + +```shell-session +ipconfig /flushdns +``` + + + + +After you flush the DNS cache, try connecting to the alias again, or repeat the steps above. + +If you are still not able to understand what is wrong, submit a support ticket. Include the `boundary client-agent status` output and the log file in the ticket. + +### Commonly seen errors + +Refer to the following commonly seen errors for more information about their possible causes and resolutions. + +#### nodename nor servname provided, or not known / No such host is known + +This is a generic error for a failed DNS resolution. +It can mean a number of different things: +- The alias doesn't exist or is misspelled. +- Your user isn't authenticated or doesn't have permission to connect to the target. +- The Client Agent is not able to intercept DNS requests, it could shut down or paused. +- The OS DNS cache is interfering with the operation of the Client Agent. +- The Client Agent may not yet know about the alias. + It takes around 2 minutes for the Client Agent to learn about new aliases. + +Follow the troubleshooting steps above to resolve the issue. + +#### failed to listen for DNS on either IPv4 or IPv6 + +This error happens when some other application on the local machine occupies the ports used by the Boundary Client Agent. +The Client Agent requires access to port 53 for IPv4 and IPv6, both UDP and TCP. +Diagnosing what causes the error differs per operating system: + + + + +As a privileged user, you can use the `lsof` program to find what applications are occupying a port, for example: + +```shell-session +$ sudo lsof -nP | grep ":53" +``` + +If anything is occupying port 53, you may need to terminate the application before the Client Agent is able to start. + +Applications that make use of the Apple Virtualization Framework are known to sometimes occupy this port under +the name `_mdnsresponder`. If you have any virtualization software, you may need to turn it off before using +the Client Agent. + + + + +As a privileged user, you can open the **Resource Monitor** and inspect the **Network** > **Listening Ports** section to find any applications that use port 53. + + + + +Once you have identified which other software is using the port, you can stop it and try to start the Client Agent again. + +#### failed to refresh alias cache: error="fetching resolvable aliases: error performing client request during List call" + +This usually implies that there is a problem reaching the internet or the Boundary controller. +The error is related to the periodic updating of aliases used by the Client Agent to know whether a DNS request matches an alias or not. + +HashiCorp recommends that you pause the Client Agent and examine the status and logs for further errors: + +```shell-session +$ boundary client-agent pause +``` + +Follow the troubleshooting steps to understand why the Client Agent is not able to reach the controller. + +## Conflicting software + +Some software is known to cause conflicts with the Boundary Client Agent. +The following sections are an incomplete list of potential conflicts and any available workarounds for issues. + +### Docker Desktop (MacOS) + +Docker Desktop sometimes creates a local DNS listener that prevents the Client Agent from running. +If you run Docker Desktop 4.26 or later, you must clear the `Use kernel networking for UDP` option. +Otherwise, the Client Agent refuses to start. + +### Palo Alto Networking Global Protect VPN + +If you are unable to establish a transparent session while using the Palo Alto Networking Global Protect VPN, you may need to explicitly specify a network interface and the upstream DNS server(s) to use. + +By default, the Client Agent reads the primary network interface's DNS server configuration and uses that information to resolve domains that are not configured as aliases in Boundary. +If the VPN configuration includes custom DNS servers, this information may not be available to the Client Agent, so you must explicitly specify the DNS server(s) to use. + +To configure the DNS server(s) to use, use the `override_upstream_dns_servers` configuration option: + +```hcl +# The DNS servers must be specified as an IP, or an IP:Port. +# If no port is provided, port 53 is assumed. +# The order of the entries specifies the priority. +override_upstream_dns_servers = [ + "8.8.8.8", + "8.8.4.4:53", +] +``` + +### Primary network interfaces + +By default, the Client Agent creates IPs on the primary network interface to serve its DNS server. +Refer to the tabs below for possible conflicts for each supported operating system. + + + + +When you run the Client Agent alongside the PAN-GP VPN, the primary network interface will likely be set to a `tun` type interface, which the Client Agent cannot use for its IP addresses. +You may see errors such as the following in the `boundary-client-agent.log` file or the `boundary client-agent status` command response: + +``` +[ERROR] macos.addIP: error adding ipv4 address: ifconfig: ioctl (SIOCAIFADDR): Destination address required +``` + +To work around the default `tun` interface, you must provide an explicit network interface using the `interface_to_use` configuration option. For example: + +```hcl +interface_to_use=en0 +``` + +The `interface_to_use` option allows the Client Agent to create the IPs it needs to serve the DNS server and proxy traffic. +You must restart the Client Agent for it to update its configuration with the new setting. + + + + +On Windows, the Client Agent may be able to create the IPs that it needs on the primary network interface, but it fails to establish any transparent sessions. You may see the following message: + +``` +[INFO] default route change detected, restarting +``` + +You must explicitly specify a network interface to use other than the primary one. You can list available network interfaces using the Powershell command `Get-NetAdapter`, or the older `route print` command. You must find the index of the interface you would normally use to connect to the internet. In this example, the interface index is `11`: + +``` +PS C:\> Get-NetAdapter +Name InterfaceDescription ifIndex Status MacAddress LinkSpeed +---- -------------------- ------- ------ ---------- --------- +Ethernet Parallels VirtIO Ethernet Adapter 11 Up 00-1C-42-B3-F2-75 10 Gbps +Ethernet 2 PANGP Virtual Ethernet Adapter Secure 24 Up 02-50-41-00-00-01 2 Gbps +``` + +Alternatively, if you use `route print`, refer to the following example: + +``` +PS C:\> route print +=========================================================================== +Interface List + 24...02 50 41 00 00 01 ......PANGP Virtual Ethernet Adapter Secure + 11...00 1c 42 b3 f2 75 ......Parallels VirtIO Ethernet Adapter + 1...........................Software Loopback Interface 1 +=========================================================================== +```` + +Your configuration should look like this: + +```hcl +interface_to_use=11 +``` + +You must restart the Client Agent for it to update its configuration with the new setting. + + + + +### Cloudflare WARP client + +The Cloudflare WARP client uses a local DNS server to direct traffic. +It has built-in checks to prevent it from being run alongside other software that uses the same mechanism. +This includes the Boundary Client Agent. +If you try to use the Client Agent with the Cloudflare WARP client, it may work, or you may see an error like this one: + +``` +Status: Unable to Connect +Error reason: DNS Proxy Failure +Error code: CF_DNS_PROXY_FAILURE +Error description: The WARP Agent must be the only process responsible for DNS resolution on the device. One or more processes are already bound to port 53: boundary-client-agent. +Learn more: https://cfl.re/CF_DNS_PROXY_FAILURE +``` + +You can still install both the Cloudflare WARP client and the Boundary Client Agent on the same machine. +As long as you don't run both at the same time, they should work as expected. + +## Uninstall the Client Agent on Mac + +If you used the Mac installer, you can run `/Library/Application Support/HashiCorp/Boundary Uninstaller.app` to uninstall Boundary. +The uninstaller removes any installed components, including the Desktop client, CLI, and the Boundary Client Agent. + +## More information + +Refer to the following topics for more information: + +- [Aliases](/boundary/docs/concepts/aliases) +- [Transparent sessions](/boundary/docs/concepts/transparent-sessions) diff --git a/website/content/docs/concepts/aliases.mdx b/website/content/docs/concepts/aliases.mdx index 71a294f215..0ceddc35fc 100644 --- a/website/content/docs/concepts/aliases.mdx +++ b/website/content/docs/concepts/aliases.mdx @@ -38,7 +38,29 @@ You can configure Boundary to allow a select few users to manage those targets, An alias is a globally unique, DNS-like string that is associated with a destination resource. The alias `value` parameter does not have to be delimited by a suffix, and can be just a hostname. -Examples of valid aliases include `webserver` and `webserver.boundary`. +Examples of valid aliases include `database.boundary` and `webserver.boundary`. + +### Single word aliases and transparent sessions + +HashiCorp recommends that you do not use single-word aliases such as `webserver` as opposed to `webserver.boundary`, because single-word aliases do not work intuitively on Windows. +Windows DNS resolution does not support resolving unqualified single word DNS hostnames. +You can make the hostname fully qualified, but is not intuitive to most users. + +For example the following hostname works: + +``` +ssh mytarget. +``` + +But this hostname does not work: + +``` +ssh mytarget +``` + +For this reason, if you expect any Windows users to use an alias, it contains a dot (`.`) anywhere in the value. + +See the [transparent sessions](/boundary/docs/concepts/transparent-sessions) documentation for more information. ## Scopes @@ -260,4 +282,4 @@ Complete the following steps to add an alias to a target: - `-authorize-session-host-id=` - Optionally indicates the host ID to use when you use the alias to authorize a session. - \ No newline at end of file + diff --git a/website/content/docs/concepts/connection-workflows/index.mdx b/website/content/docs/concepts/connection-workflows/index.mdx index cef6aa4e68..5f935236c8 100644 --- a/website/content/docs/concepts/connection-workflows/index.mdx +++ b/website/content/docs/concepts/connection-workflows/index.mdx @@ -17,6 +17,18 @@ Refer to the [`boundary connect`](/boundary/docs/commands/connect) documentation To practice using the `boundary connect` command in a development environment, refer to the **Connect to your first target** tutorial for either [HCP Boundary](/boundary/tutorials/hcp-getting-started/hcp-getting-started-connect) or the [self-managed versions](/boundary/tutorials/oss-getting-started/oss-getting-started-connect) of Boundary. +## Transparent sessions + +@include 'alerts/enterprise-only.mdx' + +@include 'alerts/beta.mdx' + +Transparent sessions shift Boundary from an active connection model to a passive connection model. +Instead of interacting with the Boundary CLI or Desktop client and having to remember specific IDs or ephemeral ports to connect to targets, Boundary operates in the background. +If a user is authenticated and authorized, Boundary intercepts DNS calls and routes traffic through a session automatically. + +Refer to the [transparent sessions](/boundary/docs/concepts/transparent-sessions) documentation for more information. + ## Connect helpers Boundary features connect helpers that assist with making connections to targets using certain protocols. @@ -52,7 +64,7 @@ Refer to the [SSH ProxyCommand](/boundary/docs/concepts/connection-workflows/wor ## Multi-hop sessions -This feature requires HCP Boundary or Boundary Enterprise +@include 'alerts/enterprise-only.mdx' Most organizations want to provide access to infrastructure without exposing private networks. Many organizations also have complex network topologies requiring inbound traffic to route through multiple network enclaves to reach the target system. diff --git a/website/content/docs/concepts/host-discovery/aws.mdx b/website/content/docs/concepts/host-discovery/aws.mdx index 36d88d65d0..a79c884f9c 100644 --- a/website/content/docs/concepts/host-discovery/aws.mdx +++ b/website/content/docs/concepts/host-discovery/aws.mdx @@ -9,7 +9,7 @@ Boundary uses dynamic host catalogs to automatically discover AWS EC2 instances ## Create a host catalog to connect with AWS Boundary uses plugins to integrate with a variety of providers. To use -a dynamic host catalog to integrate with AWS, you create a host catalog of the `plugin` type +a dynamic host catalog to integrate with AWS, you create a host catalog of the `plugin` type and set the `plugin-name` value to `aws`. You must also provide the specific fields needed for Boundary to authenticate with AWS. @@ -57,6 +57,10 @@ The fields following the `attr` and `secret` flags are specific to AWS and are r - `disable_credential_rotation`: When set to `true`, Boundary will not rotate the credentials with AWS automatically. - `region`: The region to configure the host catalog for. All host sets in this catalog will be configured for this region. +- `role_arn`: The AWS role ARN used for `AssumeRole` authentication. If you provide a `role_arn` value, you must also set `disable_credential_rotation` to `true`. +- `role_external_id`: The external ID that you configured for the `AssumeRole` provider. +- `role_session_name`: The session name that you configured for the `AssumeRole` provider. +- `role_tags`: The key-value pair tags that you configured for the `AssumeRole` provider. - `access_key_id`: The access key ID for the IAM user to use with this host catalog. - `secret_access_key`: The secret access key for the IAM user to use with this diff --git a/website/content/docs/concepts/transparent-sessions.mdx b/website/content/docs/concepts/transparent-sessions.mdx new file mode 100644 index 0000000000..6c356e10a3 --- /dev/null +++ b/website/content/docs/concepts/transparent-sessions.mdx @@ -0,0 +1,97 @@ +--- +layout: docs +page_title: Transparent sessions +description: |- + Learn how transparent sessions enable you to connect to Boundary resources without remembering resource IDs or port numbers. +--- + +# Transparent sessions + +@include 'alerts/enterprise-only.mdx' + +@include 'alerts/beta.mdx' + +Transparent sessions shift Boundary from an active connection model to a passive connection model. +Boundary operates in the background instead of requiring you to remember specific resource IDs or ephemeral ports to connect to targets. +As long as Boundary authenticates a user and the user is authorized to access the target, Boundary intercepts the DNS call and routes traffic through a session automatically. + +Transparent sessions require [aliases](/boundary/docs/concepts/aliases) and the [Boundary Client Agent](/boundary/docs/api-clients/client-agent). + +The Boundary Desktop client facilitates quick target discovery and session establishment using your preferred client. +If you configure aliases for your targets, install the Boundary Client Agent, and ensure you are authenticated to the cluster, connections are transparent to the user. +Boundary provides OS notifications to make it clear when you connect to a target using a transparent session. + +Boundary supports Windows and MacOS for the transparent sessions public beta. + +## Requirements + +Before you configure transparent sessions, you must: + +- Ensure that the Boundary CLI and Boundary Desktop are not installed in the environment in which you want to run the transparent sessions beta. +- Download the appropriate installer for your Windows or MacOS environment from the [downloads](/boundary/install) page. + +## Install clients + +Complete the following steps to install the Boundary Client Agent, CLI, and Desktop client: + +1. Install Boundary using the installer. +Make sure to select the options **Boundary Client Agent**, **CLI**, and **Desktop**. +1. Open the CLI and type the following command to confirm that the version is 0.18.0: + ```shell-session + $ boundary version + ``` +1. In the CLI, run the status command to confirm that the Boundary Client Agent has started: + + ```shell-session + $ boundary client-agent status + ``` + +## Configure targets + +The following section details how to configure targets and test the transparent sessions public beta feature. + +If you use a cluster that was created earlier than release 0.16.0, you must add the grant `list-resolvable-aliases` so that the client agent can populate the local alias cache. +As an example, you could add the grant `type=user;actions=list-resolvable-aliases;ids=*`. + +Complete the following steps to configure targets and test transparent sessions: + +1. Authenticate to Boundary using the CLI or Desktop client. +1. [Create a new target with an alias](/boundary/docs/concepts/aliases#create-an-alias-during-target-creation) or [create an alias for an existing target](/boundary/docs/concepts/aliases#create-an-alias-for-an-existing-target). +Ensure that you have authorization to establish a session to the target. +1. Open the client of your choice and [connect to your target using the alias](/boundary/docs/concepts/aliases#connect-to-a-target-using-an-alias). + + Boundary routes your session using the Boundary Client Agent. + You can validate that Boundary routed the session by looking at the **Sessions** page in the Desktop client, by typing `boundary sessions list -recursive` in the CLI, or by looking at sessions managed by the Client Agent using `boundary client-agent sessions`. + + + + The Client Agent periodically requests an updated list of aliases from the controller, so the alias may not work immediately after you create it. + It should not take longer than 2 minutes for the alias to be updated in the Client Agent. If you still see connection issues after 2 minutes, + follow the troubleshooting steps in [the Client Agent troubleshooting guide](/boundary/docs/api-clients/client-agent#troubleshooting). + + + +When you have validated that transparent sessions work, you can create and establish transparent sessions to other services. +Make a list of the services you use, add these resources to Boundary as targets, and create workers as needed for network partitions. + +## Known issues + +Refer to the following table for known issues that may affect the public beta: + +| Issue | Description | +| ----- | ----------- | +| Connection is reset when trying to reconnect | If you use an SSH transparent session and then cancel the connection, you may have trouble reconnecting until Boundary cleans up the session. | +| SSH connection fails with man-in-the-middle warning | On Ubuntu systems, the initial transparent session may be successful, but any subsequent connections prompt a warning that you may be experiencing a man-in-the-middle attack. | +| Boundary Client Agent authentication does not persist across restarts | When you reboot, you are required to re-authenticate to the Client Agent before you can use transparent sessions. | +| Windows shortcuts are mandatory | The Windows installer always installs Desktop and Start menu shortcuts. This is a known issue. Shortcuts will be optional in a future version of the installer. | +| Windows installer prompts for restart | When you install Boundary, the Windows installer occasionally prompts you to restart your computer, however it is not necessary. | +| Boundary Client Agent resumes on reboot | If the Client Agent is paused and the machine is rebooted, the Client Agent will be resumed after the reboot. | +| Single-word aliases do not work on Windows | If you create an alias consisting of a single word without a dot (`.`), the alias will not work on Windows. | +| Windows installer does not support partial installations | The Windows installer fails to start the Client Agent if the Desktop client is not installed at the same time. | + +## More information + +Refer to the following topics for more information: + +- [Aliases](/boundary/docs/concepts/aliases) +- [Boundary Client Agent](/boundary/docs/api-clients/client-agent) diff --git a/website/content/docs/configuration/session-recording/storage-providers/configure-minio.mdx b/website/content/docs/configuration/session-recording/storage-providers/configure-minio.mdx index 781139d3c5..988dd8cce0 100644 --- a/website/content/docs/configuration/session-recording/storage-providers/configure-minio.mdx +++ b/website/content/docs/configuration/session-recording/storage-providers/configure-minio.mdx @@ -30,6 +30,9 @@ When you determine storage requirements for the external bucket, you should cons You must associate the Boundary storage bucket with a MinIO storage bucket. A Boundary MinIO storage bucket contains the bucket name, endpoint URL, optional region, optional prefix, and the service account credentials needed to access the bucket. To enable credential rotation, you cannot add a Boundary storage bucket without a MinIO service account. You can disable credential rotation when you create the Boundary storage bucket. + At the time of the 0.18.0 release, the latest tested and supported MinIO version is `RELEASE.2024-10-02T17-50-4Z`. + Newer versions may work as well, but they have not been tested. + At this time, the NetBSD operating system is not supported for the MinIO storage bucket. diff --git a/website/content/docs/configuration/session-recording/storage-providers/configure-s3-compliant.mdx b/website/content/docs/configuration/session-recording/storage-providers/configure-s3-compliant.mdx index a7f4b39958..9e6d2c1d6d 100644 --- a/website/content/docs/configuration/session-recording/storage-providers/configure-s3-compliant.mdx +++ b/website/content/docs/configuration/session-recording/storage-providers/configure-s3-compliant.mdx @@ -11,13 +11,22 @@ description: |- The [MinIO plugin](https://github.com/hashicorp/boundary-plugin-minio/) lets you configure S3-compliant storage providers for session recording. + HashiCorp has tested and confirmed that you can configure the following S3-compliant storage products for session recording using the MinIO plugin: -- [Hitachi Content Platform](#hitachi-content-platform-configuration) +- [Hitachi Content Platform](https://trycontent.hitachivantara.com) + + At the time of the 0.18.0 release, the latest tested and supported Hitachi Content Platform version is `2.6.0.0`. + Newer versions may work as well, but they have not been tested. + +- [Backblaze B2](https://www.backblaze.com/cloud-storage) You can also configure other providers' S3-compliant storage products for session recording storage. We will update the list of providers as we test them. +The process for [configuring the Hitachi Content Platform](#hitachi-content-platform-configuration) is included below as an example. +Configuring other S3-compliant storage products for use with session recording should be a similar process. + ## Requirements Before you can create a storage bucket in Boundary, you must ensure that your environment meets certain requirements. @@ -40,11 +49,10 @@ When you determine storage requirements for the external bucket, you should cons - A service account and access keys for the storage provider You must provide service account access keys when you configure a Boundary storage bucket later on. - Refer to your storage provider's documentation to learn how to set up a service account. - The storage bucket must be configured with R/W access. If you use a - restricted IAM user policy, the following policy actions must be allowed at a minimum. + restricted IAM user policy, you must allow the following policy actions at a minimum. ```json { @@ -73,7 +81,7 @@ When you determine storage requirements for the external bucket, you should cons HashiCorp has tested and confirmed that you can configure the Hitachi Content Platform for external session recording storage using the MinIO plugin. It is included as an example in this topic. -You should be able to configure other S3-compliant storage providers to work for session recording storage as well, but we have not tested other providers. +You should be able to configure other S3-compliant storage providers to work for session recording storage as well, but we have only tested a [limited number of providers](#providers). You must have an account with Hitachi Content Platform to create storage buckets. You can sign up for an account at the following URL: diff --git a/website/content/docs/enterprise/supported-versions.mdx b/website/content/docs/enterprise/supported-versions.mdx index 9b75612642..7b0d421953 100644 --- a/website/content/docs/enterprise/supported-versions.mdx +++ b/website/content/docs/enterprise/supported-versions.mdx @@ -31,13 +31,29 @@ Customers are recommended to run the latest versions of Boundary in order to lev ## Control plane and client/cli compatibility -The supported version compatibility between Boundary's control plane and Boundary clients/cli is the same as control plane and worker compatibility. Within a Boundary Enterprise deployment API backwards compatibility is only supported between the control plane and clients from the prior “major release”. Using clients on newer versions than the control plane they are registered with is not supported. +The supported version compatibility between Boundary's control plane and Boundary clients/CLI is the same as control plane and worker compatibility. Within a Boundary Enterprise deployment API backwards compatibility is only supported between the control plane and clients from the prior “major release”. Using clients on newer versions than the control plane they are registered with is not supported. For example, Boundary clients version 0.14.0 are compatible with Boundary control plane running Boundary 0.15.0. However, they will not have compatibility once the control plane is updated to version 0.16.0 or above. Boundary clients version 0.16.0 are not compatible with Boundary control plane running Boundary 0.15.0 or lower. Customers are recommended to run the latest versions of Boundary in order to leverage the newest features and bug fixes. +The Desktop client uses a different numbering scheme than the CLI and control plane. +Refer to the table for the Desktop version that corresponds to the control plane version. + +| Desktop version | Control plane version | +| --------------- | ----------- | +| 2.1.0 | 0.17.0 | +| 2.0.3 | 0.16.0 | +| 2.0.2 | 0.15.3 | +| 2.0.1 | 0.15.1 | +| 2.0.0 | 0.15.0 | + +For example, the Desktop version 2.0.3 is compatible with version 0.17.0 of the control plane. +But when the control plane is upgraded to 0.18.0, version 2.0.3 will no longer be officially supported. + +To view the Desktop version along with the corresponding CLI and control plane version, click **Boundary**, and then click **About Boundary** in the Desktop client. + ## PostgreSQL support policy Boundary Enterprise will only support PostgreSQL version 13 and above at launch. diff --git a/website/content/docs/release-notes/v0_18_0.mdx b/website/content/docs/release-notes/v0_18_0.mdx new file mode 100644 index 0000000000..2aa389c90a --- /dev/null +++ b/website/content/docs/release-notes/v0_18_0.mdx @@ -0,0 +1,172 @@ +--- +layout: docs +page_title: v0.18.0 +description: |- + Boundary release notes for v0.18.0 +--- + +# Boundary 0.18.0 release notes + +**GA date:** October 15, 2024 + +@include 'release-notes/intro.mdx' + +## Important changes + + + + + + + + + + + + + + + + + + + + +
ChangeDescription
+ Role creation + + In a future version Boundary will no longer automatically create roles when new scopes are created. This was implemented prior to multi-scope grants to ensure administrators and users had default permissions in new scopes. Since Boundary 0.15, initial roles created for new clusters provide these permissions by default to all scopes using multi-scope grants. +
+ Docker image no longer contains curl + + As of version 0.17.1 and later, the curl binary is no longer included in the published Docker container image for Boundary. The image now includes wget, which you can alternatively use to check the health endpoint for a worker. If your workflow depends on having curl in the image, you can dynamically install it using apk. +

+ Learn more:  Known issues and breaking changes +
+ +## New features + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureUpdateDescription
+ Transparent sessions + + BETA + + Transparent sessions allows users to eliminate steps in their current workflows using Boundary’s Client Agent, a component that operates in the background to intercept network traffic and automatically route this traffic through a session if the user is authenticated and authorized. +

+ Platform teams and access management teams that administer Boundary can now build much faster, simpler secure remote access workflows that feel more intuitive and invisible to their developer customers. +

+ Learn more: Transparent sessions and Client Agent. +
+ Backblaze B2 support for storage buckets + + GA + + Backblaze B2 is now supported as a storage provider for session recording storage buckets. +

+ Learn more: Configure an S3-compliant storage provider. +
+ AssumeRole support for AWS dynamic host catalogs + + GA + + AWS host plugins now support AssumeRole. AssumeRole returns a set of temporary security credentials that you can use to access AWS resources. +

+ Learn more: AWS dynamic host catalogs. +
+ +## Known issues and breaking changes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VersionIssueDescription
+ 0.13.0+ + + Rotation of AWS access and secret keys during a session results in stale recordings + + In Boundary version 0.13.0+, when you rotate a storage bucket's secrets, any new sessions use the new credentials. However, previously established sessions continue to use the old credentials. +

+ As a best practice, administrators should rotate credentials in a phased manner, ensuring that all previously established sessions are completed before revoking the stale credentials. + Otherwise, you may end up with recordings that aren't stored in the remote storage bucket, and are unable to be played back. +
+ 0.13.0+ + + Unsupported recovery workflow during worker failure + + If a worker fails during a recording, there is no way to recover the recording. This could happen due to a network connectivity issue or because a worker is scaled down, for example. +

+ Learn more:  + Unsupported recovery workflow +
+ 0.17.1+ + + Docker image no longer contains curl + + As of version 0.17.1 and later, the curl binary is no longer included in the published Docker container image for Boundary. +

+ The image now includes wget. You can use wget to check the health endpoint for workers. +

+ Learn more:  Check the health endpoint using wget +

+ If your workflow depends on having curl in the image, you can dynamically install it using apk. Refer to the following commands for examples of using apk to install curl: +

+ <CONTAINER-ID> apk add curl +

+ or +

+ kubectl exec -ti <NAME> -- apk add curl +
\ No newline at end of file diff --git a/website/content/partials/alerts/beta.mdx b/website/content/partials/alerts/beta.mdx new file mode 100644 index 0000000000..5cbafd7ac5 --- /dev/null +++ b/website/content/partials/alerts/beta.mdx @@ -0,0 +1,6 @@ + + +Beta functionality is stable, but possibly incomplete and subject to change. +**We strongly discourage using beta features in production deployments of Boundary.** + + \ No newline at end of file diff --git a/website/content/partials/alerts/enterprise-only.mdx b/website/content/partials/alerts/enterprise-only.mdx new file mode 100644 index 0000000000..50d3cd2a39 --- /dev/null +++ b/website/content/partials/alerts/enterprise-only.mdx @@ -0,0 +1 @@ +This feature requires HCP Boundary or Boundary Enterprise \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index ef843117c2..b83e7caa1b 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -195,6 +195,15 @@ "title": "Aliases", "path": "concepts/aliases" }, + { + "title": "Transparent sessions", + "badge": { + "text": "HCP/ENT BETA", + "type": "outlined", + "color": "neutral" + }, + "path": "concepts/transparent-sessions" + }, { "title": "Auditing", "path": "concepts/auditing" @@ -1643,6 +1652,15 @@ } ] }, + { + "title": "Client Agent", + "badge": { + "text": "HCP/ENT BETA", + "type": "outlined", + "color": "neutral" + }, + "path": "api-clients/client-agent" + }, { "title": "Go SDK", "path": "api-clients/go-sdk" @@ -1765,6 +1783,10 @@ "title": "Overview", "path": "release-notes" }, + { + "title": "v0.18.0", + "path": "release-notes/v0_18_0" + }, { "title": "v0.17.0", "path": "release-notes/v0_17_0"