AWS codebuild: Add SSH troubleshooting for percent_expand and ControlPath errors
Summary
Adds two troubleshooting sections for CodeBuild sandbox SSH failures: 'percent_expand: unknown key %n' (OpenSSH older than 8.1) and 'ControlPath too long' (hostname token %h in ControlPath), including guidance to set ControlPath to ~/.ssh/codebuild-sandbox-%C and to order the Host entry before Host *.
Security assessment
The change documents SSH client configuration for connecting to CodeBuild sandbox environments, including a ControlPath using the %C hash token instead of the full sandbox ARN hostname. This is security-adjacent local SSH config guidance (connection multiplexing socket paths) rather than a fix for a specific vulnerability, so medium severity.
Evidence
+ ControlPath ~/.ssh/codebuild-sandbox-%C
Diff
diff --git a/codebuild/latest/userguide/sandbox-troubleshooting.md b/codebuild/latest/userguide/sandbox-troubleshooting.md index 3e4c915..b7d84ac 100644 --- a//codebuild/latest/userguide/sandbox-troubleshooting.md +++ b//codebuild/latest/userguide/sandbox-troubleshooting.md @@ -7 +7 @@ -StartSandboxConnection InvalidInputException error when SSH into CodeBuild sandbox environmentError: "Unable to locate credentials" when SSH into CodeBuild sandbox environmentStartSandboxConnection AccessDeniedException error when SSH into CodeBuild sandbox environmentError: "ssh: Could not resolve hostname" when SSH into CodeBuild sandbox environment +StartSandboxConnection InvalidInputException error when SSH into CodeBuild sandbox environmentError: "Unable to locate credentials" when SSH into CodeBuild sandbox environmentStartSandboxConnection AccessDeniedException error when SSH into CodeBuild sandbox environmentError: "ssh: Could not resolve hostname" when SSH into CodeBuild sandbox environmentError: "percent_expand: unknown key %n" when SSH into CodeBuild sandbox environmentError: "ControlPath too long" when SSH into CodeBuild sandbox environment @@ -22,0 +23,4 @@ Use the information in this topic to help you identify, diagnose, and address Co + * Error: "percent_expand: unknown key %n" when SSH into CodeBuild sandbox environment + + * Error: "ControlPath too long" when SSH into CodeBuild sandbox environment + @@ -140,0 +145,59 @@ Use the information in this topic to help you identify, diagnose, and address Co +## Error: "percent_expand: unknown key %n" when SSH into CodeBuild sandbox environment + +**Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`<sandbox-arn>``, the command exits immediately, before any connection attempt, with the following error: + + + percent_expand: unknown key %n + +**Possible cause:** The OpenSSH client on your local machine is older than version 8.1. The SSH configuration that the CodeBuild sandbox connection script adds to `~/.ssh/config` uses the `%n` token in `ProxyCommand`. OpenSSH added support for this token in version 8.1. + +**Recommended solution:** + + 1. Run `ssh -V` to check the installed OpenSSH client version. + + 2. Upgrade the OpenSSH client to version 8.1 or later. On Amazon Linux 2, use an Amazon Linux 2023 host or install a newer OpenSSH client. If the setup script stopped with an OpenSSH version error, run the setup script again after the upgrade. A run that stopped at the version check did not change your configuration. If the setup script completed earlier, you do not need to run it again. + + 3. Retry your SSH connection to the sandbox environment. + + + + +## Error: "ControlPath too long" when SSH into CodeBuild sandbox environment + +**Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`<sandbox-arn>``, the command prints the following error and exits, where `<limit>` is 104 on macOS and 108 on Linux: + + + ControlPath too long ('<path>' >= <limit> bytes) + +**Possible cause:** Your `~/.ssh/config` sets a `ControlPath` for all hosts that includes the hostname token `%h`. The hostname of a CodeBuild sandbox is the full sandbox ARN, so the resulting socket path exceeds the operating system limit for Unix socket paths (104 bytes on macOS, 108 bytes on Linux). + +**Recommended solution:** The current CodeBuild sandbox SSH setup script adds a `ControlPath` that does not include the hostname to the `Host codebuild-sandbox-ssh*` entry. The script also places that entry before the other `Host` entries, because OpenSSH uses the first value it finds for each option. When you run the script again, it updates the existing entry and prompts you before it changes `~/.ssh/config`. + + 1. Download and run the CodeBuild sandbox SSH setup script again, as described in [Step 2: Modify local SSH configuration](./sandbox-ssh-tutorial.html#sandbox-ssh-tutorial.modify-ssh). Accept the change when prompted. + + 2. Retry your SSH connection to the sandbox environment. + + + + +If you cannot run the setup script again, edit `~/.ssh/config` manually. + + 1. Open `~/.ssh/config` in a text editor. + + 2. Add a `ControlPath` line to the existing `Host codebuild-sandbox-ssh*` entry, as shown in the following example. + + Host codebuild-sandbox-ssh* + ControlPath ~/.ssh/codebuild-sandbox-%C + +`%C` is an OpenSSH token that expands to a short hash of the connection parameters. + + 3. Move the `Host codebuild-sandbox-ssh*` entry so that it comes before any `Host *` entry. + + + + +To connect once without changing `~/.ssh/config`, pass the option on the command line: + + + ssh -o ControlPath=~/.ssh/codebuild-sandbox-%C codebuild-sandbox-ssh=<sandbox-arn> +