AWS amazonq medium security documentation change
Summary
Restructured installation documentation with added sections for WSL support, ZIP setup with PGP verification, musl builds, and glibc troubleshooting. Expanded macOS installation options and moved AppImage instructions.
Security assessment
Added detailed PGP signature verification steps for ZIP downloads, which is a security measure to ensure package integrity and authenticity. This constitutes explicit security documentation.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/command-line-installing.md b/amazonq/latest/qdeveloper-ug/command-line-installing.md index 7371ef0c6..cf5d2c61e 100644 --- a/amazonq/latest/qdeveloper-ug/command-line-installing.md +++ b/amazonq/latest/qdeveloper-ug/command-line-installing.md @@ -5 +5 @@ -macOSAppImage (Linux)Ubuntu/Debian (Linux) +macOSWindows Subsystem for Linux (WSL)ZIP setup for autocomplete supportUbuntu/Debian (Linux)AppImage (Linux)Alternative Linux builds (musl libc/compatibility build)Handling glibc version issues @@ -9 +9,3 @@ macOSAppImage (Linux)Ubuntu/Debian (Linux) -You can install Amazon Q for command line for macOS by initiating a file download for the Amazon Q application. For more information, see [Supported command line environments](./command-line-supported-envs.html). +You can install Amazon Q for command line for macOS by initiating a file download for the Amazon Q application. For more information, see [Supported command line environments for autocomplete](./command-line-supported-envs.html). + +There are two modalities to consider when installing Amazon Q for command line. Minimal installation only distributes the binaries needed on Linux for Amazon Q chat and for the autocomplete feature to function over SSH (`q` and `qterm`). Full distribution contains the desktop application and requires the autocomplete feature to be used. If you want to only use the Amazon Q chat, consider that the minimal distribution also ships and installs `qterm` to your shell. You can use `qterm` for ZShell to support inline completions and a full version isn't required. For more information, see ZIP setup for autocomplete support. @@ -12,0 +15,4 @@ You can install Amazon Q for command line for macOS by initiating a file downloa +You can install Amazon Q for command line for macOS by downloading the application or by using Homebrew. + +After installing Amazon Q for command line for macOS, you can enable SSH integration to be able to use autocomplete for over 500 command line tools. For more information, see [Local macOS Integration](./command-line-autocomplete-ssh.html#command-line-autocomplete-ssh-setup-local-mac). + @@ -28 +34 @@ You can install Amazon Q for command line for macOS by initiating a file downloa -## AppImage (Linux) +**To install Amazon Q for command line for macOS with Homebrew** @@ -30 +36 @@ You can install Amazon Q for command line for macOS by initiating a file downloa -Amazon Q for command line is available as an [AppImage](https://appimage.org/), a single file with all dependencies included. It executes on a wide variety of Linux environments. You can set the file executable and you can begin using it. + 1. If you don't already have Homebrew installed, install the package manager from [brew.sh](https://brew.sh/). @@ -32 +38 @@ Amazon Q for command line is available as an [AppImage](https://appimage.org/), -**To install Amazon Q for command line for Linux with AppImage** + 2. In a working terminal, install Amazon Q for command line using the following command: @@ -34 +40 @@ Amazon Q for command line is available as an [AppImage](https://appimage.org/), - 1. Download Amazon Q for command line for AppImage. Install the latest version using the following command: + brew install amazon-q @@ -36 +42 @@ Amazon Q for command line is available as an [AppImage](https://appimage.org/), - curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.appimage -o amazon-q.appimage + 3. Verify the installation by using the following command: @@ -38 +44 @@ Amazon Q for command line is available as an [AppImage](https://appimage.org/), -For a specific version of Amazon Q for command line, you can replace `... /latest/ ...` in the URL with the version number. + q --version @@ -40 +45,0 @@ For a specific version of Amazon Q for command line, you can replace `... /lates -###### Note @@ -42 +46,0 @@ For a specific version of Amazon Q for command line, you can replace `... /lates -Amazon Q for command line follows semantic versioning. @@ -44 +47,0 @@ Amazon Q for command line follows semantic versioning. - 2. (Optional) Verify the download of Amazon Q for command line for AppImage. For more information, see [Verifying your download](./command-line-verify.html). @@ -46 +49 @@ Amazon Q for command line follows semantic versioning. - 3. Make the downloaded AppImage executable using the following command: +## Windows Subsystem for Linux (WSL) @@ -48 +51 @@ Amazon Q for command line follows semantic versioning. - chmod +x amazon-q.appimage +While Amazon Q CLI doesn't have a native Windows version, you can use it on Windows through the Windows Subsystem for Linux (WSL). This provides a Linux environment running on Windows where you can install and use the Amazon Q CLI. @@ -50 +53 @@ Amazon Q for command line follows semantic versioning. - 4. (Optional) Move the downloaded AppImage to a location on your `PATH`. +**To install Amazon Q for command line for Windows with WSL** @@ -52 +55 @@ Amazon Q for command line follows semantic versioning. - 5. Execute the AppImage and follow the onboarding steps. + 1. Install the WSL on your Windows machine by following the [Microsoft WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install). @@ -54 +57,5 @@ Amazon Q for command line follows semantic versioning. -The AppImage bundles an XDG Desktop Entry file that can be installed and managed locally for you if you prefer. If your system supports the XDG Autostart specification, this will enable autostart capabilities, ensuring that the application is run on startup. + 2. Install a Linux distribution such as Ubunu from the Micosoft Store. + + 3. Launch your WSL Linux distribution. + + 4. Download the appropriate zip file installer version of the Linux package for your WSL distribution. To learn about the different zip files, see ZIP setup for autocomplete support. @@ -58 +65,7 @@ The AppImage bundles an XDG Desktop Entry file that can be installed and managed -Your system must have FUSE version 2 installed to run AppImages. For Ubuntu 22 and above, you can install FUSE 2 by using the following command: +This is a minimal Linux installation. Desktop Linux users have GUI components available that are not included in the zip installer for remote SSH and Windows WSL systems. + + 5. Configure your AWS credentials within the WSL environment using the following command: + + q login + + @@ -60 +72,0 @@ Your system must have FUSE version 2 installed to run AppImages. For Ubuntu 22 a - sudo apt install libfuse2 @@ -64 +76 @@ Your system must have FUSE version 2 installed to run AppImages. For Ubuntu 22 a -If the desktop application doesn't open, try running `amazon-q.appimage` directly in your terminal to view any output error logs. You can open a support issue in the [Amazon Q for command line discussions GitHub repository](https://github.com/aws/q-command-line-discussions/discussions). +When using Amazon Q CLI in WSL, it has access to files within the WSL filesystem. To work with files on your Windows drives, access them through the `/mnt/c/`path for C: drive`` within WSL. @@ -66 +78 @@ If the desktop application doesn't open, try running `amazon-q.appimage` directl - 6. Authenticate with [ Builder ID](https://docs.aws.amazon.com/general/latest/gr/aws_builder_id.html), or with [IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) using the start URL provided by your account administrator. +### Example @@ -68 +80 @@ If the desktop application doesn't open, try running `amazon-q.appimage` directl - 7. In a new terminal, use the following command: +The following procedure steps show how WSL can be installed: @@ -70 +82 @@ If the desktop application doesn't open, try running `amazon-q.appimage` directl - q doctor + 1. In a working command prompt, install WSL on your windows machine using the following command: @@ -72 +84,129 @@ If the desktop application doesn't open, try running `amazon-q.appimage` directl -Follow any remediation instructions until you see the output: **✓ Everything looks good!** + wsl —install + + 2. Run a specific distribution. For Ubuntu, use the following command: + + wsl -d Ubuntu + + 3. Create a default account with a password for your newly installed Linux distribution. For more information, see [Set up and best practices](https://learn.microsoft.com/en-us/windows/wsl/install). + + 4. Install the unzip utility for Ubuntu using the following the command: + + sudo apt install unzip + + 5. Download the installation file using the following command: + + curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip -o q.zip + + 6. Unzip the installation file using the following command: + + unzip q.zip + + 7. Execute the install using the following command: + + ./q/install.sh + + 8. Address the following: + + 1. `Do you want q to modify your shell config (you will have to manually do this otherwise)?` + + 2. `Select login method` + + 3. `Enter Start URL` + + 4. `Enter Region` + + 5. Manually open browser URL. + + 6. Complete the login. + + 9. Restart the Z Shell to refresh session information and apply changes. + + + + +## ZIP setup for autocomplete support + +The SSH setup for remote Linux integration requires installing the file, verifying the file, and installing the program. + +### Install and update requirements + + * You must be able to extract or "unzip" the downloaded package. If your operating system doesn't have the built-in unzip command, use an equivalent. + + * Amazon Q for command line uses glibc 2.34 or newer. It's included by default in most major distributions of Linux released since 2021. For older distributions, a version is statically linked with the musl library (`-musl.zip`). + + * Amazon Q for command line is supported on 64-bit x86_64 and ARM aarch64 versions of recent distributions of Fedora, Ubuntu, and Amazon Linux 2023. + + * AWS doesn't maintain third-party repositories, so it's not a guarantee that they contain the latest version of the Amazon Q command line. + + + + +**To download the zip file and verify** + + 1. Download the installation file in one of the following ways: + +Linux x86-64 + + curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip" + +Linux ARM (aarch64) + + curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip" -o "q.zip" + + 2. (Optional) Verifying the integrity of your downloaded zip file. + +If you chose to manually download the Amazon Q command line installer package .zip in the above steps, you can use the following steps to verify the signatures by using the GnuPG tool. + +The Amazon Q command line installer package .zip files are cryptographically signed using PGP signatures. If there's any damage or alteration of the files, this verification fails and you should not proceed with installation. + + 1. Download and install the gpg command using your package manager. For more information about GnuPG, see the [GnuPG documentation](https://gnupg.org/documentation/index.html). + + 2. To create the public key file, create a text file, and then paste in the following text. + + -----BEGIN PGP PUBLIC KEY BLOCK----- + + mDMEZig60RYJKwYBBAHaRw8BAQdAy/+G05U5/EOA72WlcD4WkYn5SInri8pc4Z6D + BKNNGOm0JEFtYXpvbiBRIENMSSBUZWFtIDxxLWNsaUBhbWF6b24uY29tPoiZBBMW + CgBBFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcFAmYoOtECGwMFCQPCZwAFCwkIBwIC + IgIGFQoJCAsCBBYCAwECHgcCF4AACgkQUNx6jcJMVmef5QD/QWWEGG/cOnbDnp68 + SJXuFkwiNwlH2rPw9ZRIQMnfAS0A/0V6ZsGB4kOylBfc7CNfzRFGtovdBBgHqA6P + zQ/PNscGuDgEZig60RIKKwYBBAGXVQEFAQEHQC4qleONMBCq3+wJwbZSr0vbuRba + D1xr4wUPn4Avn4AnAwEIB4h+BBgWCgAmFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcF + AmYoOtECGwwFCQPCZwAACgkQUNx6jcJMVmchMgEA6l3RveCM0YHAGQaSFMkguoAo + vK6FgOkDawgP0NPIP2oA/jIAO4gsAntuQgMOsPunEdDeji2t+AhV02+DQIsXZpoB + =f8yY + -----END PGP PUBLIC KEY BLOCK----- + + 3. Import the Amazon Q command line public key with the following command, substituting `public-key-file-name` with the file name of the public key you created. + + gpg --import public-key-file-name + gpg: directory '/home/username/.gnupg' created + gpg: keybox '/home/username/.gnupg/pubring.kbx' created + gpg: /home/username/.gnupg/trustdb.gpg: trustdb created + gpg: key 50DC7A8DC24C5667: public key "Amazon Q command line Team <q-command [email protected]>" imported + gpg: Total number processed: 1 + gpg: imported: 1 + + 4. Download the Amazon Q command line signature file for the package you downloaded. It has the same path and name as the .zip file it corresponds to, but has the extension .sig. In the following examples, we save it to the current directory as a file named q.zip.sig. + +Linux x86-64 + +For the latest version of the Amazon Q command line, use the following command: + + curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip.sig" -o "q.zip.sig" + +For a specific version of the Amazon Q command line, replace the latest with the version number. For this example the path for version 1.1.0 would be `/1.1.0/q-linux-x86_64.zip.sig`, resulting in the following command: