(Optional) Install the Session Manager plugin for the AWS CLI

If you want to use the AWS Command Line Interface (AWS CLI) to start and end sessions that connect you to your managed nodes, you must first install the Session Manager plugin on your local machine. The plugin can be installed on supported versions of Microsoft Windows, macOS, Linux, and Ubuntu.

Use the latest version of the Session Manager plugin

The Session Manager plugin is updated occasionally with enhanced functionality. We recommend that you regularly ensure you're using the latest version of the plugin. For more information, see Session Manager plugin latest version and release history.

Installation prerequisite

AWS CLI version 1.16.12 or later must be installed on your local machine in order to use the Session Manager plugin.

Install the Session Manager plugin on Windows

You can install the Session Manager plugin on Microsoft Windows Vista or later using the standalone installer.

When updates are released, you must repeat the installation process to get the latest version of the Session Manager plugin.

Note

For best results, we recommend that you start sessions on Windows clients using Windows PowerShell, version 5 or later. Alternatively, you can use the Command shell in Microsoft Windows 10. The Session Manager plugin only supports PowerShell and the Command shell. Third-party command line tools might not be compatible with the plugin.

To install the Session Manager plugin using the EXE installer

1. Download the installer using the following URL.

   https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe

   Alternatively, you can download a zipped version of the installer using the following URL.

   https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPlugin.zip

2. Run the downloaded installer, and follow the on-screen instructions. If you downloaded the zipped version of the installer, you must unzip the installer first.

   Leave the install location box blank to install the plugin to the default directory.

   • %PROGRAMFILES%\Amazon\SessionManagerPlugin\bin\

3. Verify that the installation was successful. For information, see Verify the Session Manager plugin installation.

   Note

   If Windows is unable to find the executable, you might need to re-open the command prompt or add the installation directory to your PATH environment variable manually. For information, see the troubleshooting topic Session Manager plugin not automatically added to command line path (Windows).

Install and uninstall the Session Manager plugin on macOS

You can install the Session Manager plugin on macOS using the bundled installer.

Important

The bundled installer doesn't support installing to paths that contain spaces.

To install the Session Manager plugin using the bundled installer (macOS)

1. Download the bundled installer.

   • x86_64

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"

   • ARM64 (M1)

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac_arm64/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"

2. Unzip the package.

   unzip sessionmanager-bundle.zip

3. Run the install command.

   sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

   Note

   The plugin requires either Python 2.6.5 or later, or Python 3.3 or later. By default, the install script runs under the system default version of Python. If you have installed an alternative version of Python and want to use that to install the Session Manager plugin, run the install script with that version by absolute path to the Python executable. The following is an example.

   sudo /usr/local/bin/python3.6 sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

   The installer installs the Session Manager plugin at /usr/local/sessionmanagerplugin and creates the symlink session-manager-plugin in the /usr/local/bin directory. This eliminates the need to specify the install directory in the user's $PATH variable.

   To see an explanation of the -i and -b options, use the -h option.

   ./sessionmanager-bundle/install -h

4. Verify that the installation was successful. For information, see Verify the Session Manager plugin installation.

Note

If you ever want to uninstall the plugin, run the following two commands in the order shown.

sudo rm -rf /usr/local/sessionmanagerplugin

sudo rm /usr/local/bin/session-manager-plugin

Install the Session Manager plugin on macOS with the signed installer

You can install the Session Manager plugin on macOS using the signed installer.

To install the Session Manager plugin using the signed installer (macOS)

1. Download the signed installer.

   • x86_64

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/session-manager-plugin.pkg" -o "session-manager-plugin.pkg"

   • ARM64 (M1)

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac_arm64/session-manager-plugin.pkg" -o "session-manager-plugin.pkg"

2. Run the install command.

   sudo installer -pkg session-manager-plugin.pkg -target /
   sudo ln -s /usr/local/sessionmanagerplugin/bin/session-manager-plugin /usr/local/bin/session-manager-plugin

3. Verify that the installation was successful. For information, see Verify the Session Manager plugin installation.

Install Session Manager plugin on Linux

1. Download the Session Manager plugin RPM package.

   • x86_64

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm" -o "session-manager-plugin.rpm"

   • x86

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_32bit/session-manager-plugin.rpm" -o "session-manager-plugin.rpm"

   • ARM64

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.rpm" -o "session-manager-plugin.rpm"

2. Run the install command.

   sudo yum install -y session-manager-plugin.rpm

3. Verify that the installation was successful. For information, see Verify the Session Manager plugin installation.

Note

If you ever want to uninstall the plugin, run sudo yum erase session-manager-plugin -y

Install the Session Manager plugin on Ubuntu

1. Download the Session Manager plugin deb package.

   • x86_64

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"

   • x86

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_32bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"

   • ARM64

     curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_arm64/session-manager-plugin.deb" -o "session-manager-plugin.deb"

2. Run the install command.

   sudo dpkg -i session-manager-plugin.deb

3. Verify that the installation was successful. For information, see Verify the Session Manager plugin installation.

Note

If you ever want to uninstall the plugin, run sudo dpkg -r session-manager-plugin

Verify the Session Manager plugin installation

Run the following commands to verify that the Session Manager plugin installed successfully.

session-manager-plugin

If the installation was successful, the following message is returned.

The Session Manager plugin is installed successfully. Use the AWS CLI to start a session.

You can also test the installation by running the following command in the AWS CLI. In the following command, replace instance-id with your own information.

aws ssm start-session --target instance-id

This command will work only if your Session Manager administrator has granted you the necessary IAM permissions to access the target managed node using Session Manager.

Session Manager plugin on GitHub

The source code for Session Manager plugin is available on GitHub so that you can adapt the plugin to meet your needs. We encourage you to submit pull requests for changes that you would like to have included. However, Amazon Web Services doesn't provide support for running modified copies of this software.

(Optional) Turn on Session Manager plugin logging

The Session Manager plugin includes an option to allow logging for sessions that you run. By default, logging is turned off.

If you allow logging, the Session Manager plugin creates log files for both application activity (session-manager-plugin.log) and errors (errors.log) on your local machine.

Topics

• Turn on logging for the Session Manager plugin (Windows)
• Enable logging for the Session Manager plugin (Linux and macOS)

Turn on logging for the Session Manager plugin (Windows)

1. Locate the seelog.xml.template file for the plugin.

   The default location is C:\Program Files\Amazon\SessionManagerPlugin\seelog.xml.template.

2. Change the name of the file to seelog.xml.

3. Open the file and change minlevel="off" to minlevel="info" or minlevel="debug".

   Note

   By default, log entries about opening a data channel and reconnecting sessions are recorded at the INFO level. Data flow (packets and acknowledgement) entries are recorded at the DEBUG level.

4. Change other configuration options you want to modify. Options you can change include:

   • Debug level: You can change the debug level from formatid="fmtinfo" to outputs formatid="fmtdebug".

   • Log file options: You can make changes to the log file options, including where the logs are stored, with the exception of the log file names.

     Important

     Don't change the file names or logging won't work correctly.

     <rollingfile type="size" filename="C:\Program Files\Amazon\SessionManagerPlugin\Logs\session-manager-plugin.log" maxsize="30000000" maxrolls="5"/>
     <filter levels="error,critical" formatid="fmterror">
     <rollingfile type="size" filename="C:\Program Files\Amazon\SessionManagerPlugin\Logs\errors.log" maxsize="10000000" maxrolls="5"/>

5. Save the file.

Enable logging for the Session Manager plugin (Linux and macOS)

1. Locate the seelog.xml.template file for the plugin.

   The default location is /usr/local/sessionmanagerplugin/seelog.xml.template.

2. Change the name of the file to seelog.xml.

3. Open the file and change minlevel="off" to minlevel="info" or minlevel="debug".

   Note

   By default, log entries about opening data channels and reconnecting sessions are recorded at the INFO level. Data flow (packets and acknowledgement) entries are recorded at the DEBUG level.

4. Change other configuration options you want to modify. Options you can change include:

   • Debug level: You can change the debug level from formatid="fmtinfo" to outputs formatid="fmtdebug"

   • Log file options: You can make changes to the log file options, including where the logs are stored, with the exception of the log file names.

     Important

     Don't change the file names or logging won't work correctly.

     <rollingfile type="size" filename="/usr/local/sessionmanagerplugin/logs/session-manager-plugin.log" maxsize="30000000" maxrolls="5"/>
     <filter levels="error,critical" formatid="fmterror">
     <rollingfile type="size" filename="/usr/local/sessionmanagerplugin/logs/errors.log" maxsize="10000000" maxrolls="5"/>

     Important

     If you use the specified default directory for storing logs, you must either run session commands using sudo or give the directory where the plugin is installed full read and write permissions. To bypass these restrictions, change the location where logs are stored.

5. Save the file.

Session Manager plugin latest version and release history

Your local machine must be running a supported version of the Session Manager plugin. The current minimum supported version is 1.1.17.0. If you're running an earlier version, your Session Manager operations might not succeed.

To see if you have the latest version, run the following command in the AWS CLI.

Note

The command returns results only if the plugin is located in the default installation directory for your operating system type. You can also check the version in the contents of the VERSION file in the directory where you have installed the plugin.

session-manager-plugin --version

The following table lists all releases of the Session Manager plugin and the features and enhancements included with each version.

Version	Release date	Details
1.2.463.0	March 15, 2023	Enhancement: Added ARM64 support for Apple Mac (M1) in macOS bundle installer and signed installer.
1.2.398.0	October 14, 2022	Enhancement: Support golang version 1.17. Update default session-manager-plugin runner for macOS to use python3. Update import path from SSMCLI to session-manager-plugin.
1.2.339.0	June 16, 2022	Bug fix: Fix idle session timeout for port sessions.
1.2.331.0	May 27, 2022	Bug fix: Fix port sessions closing prematurely when the local server doesn't connect before timeout.
1.2.323.0	May 19, 2022	Bug fix: Disable smux keep alive to use idle session timeout feature.
1.2.312.0	March 31, 2022	Enhancement: Supports more output message payload types.
1.2.295.0	January 12, 2022	Bug fix: Hung sessions caused by client resending stream data when agent becomes inactive, and incorrect logs for start_publication and pause_publication messages.
1.2.279.0	October 27, 2021	Enhancement: Zip packaging for Windows platform.
1.2.245.0	August 19, 2021	Enhancement: Upgrade aws-sdk-go to latest version (v1.40.17) to support AWS IAM Identity Center (successor to AWS Single Sign-On).
1.2.234.0	July 26, 2021	Bug fix: Handle session abruptly terminated scenario in interactive session type.
1.2.205.0	June 10, 2021	Enhancement: Added support for signed macOS installer.
1.2.54.0	January 29, 2021	Enhancement: Added support for running sessions in NonInteractiveCommands execution mode.
1.2.30.0	November 24, 2020	Enhancement: (Port forwarding sessions only) Improved overall performance.
1.2.7.0	October 15, 2020	Enhancement: (Port forwarding sessions only) Reduced latency and improved overall performance.
1.1.61.0	April 17, 2020	Enhancement: Added ARM support for Linux and Ubuntu.
1.1.54.0	January 6, 2020	Bug fix: Handle race condition scenario of packets being dropped when the Session Manager plugin isn't ready.
1.1.50.0	November 19, 2019	Enhancement: Added support for forwarding a port to a local unix socket.
1.1.35.0	November 7, 2019	Enhancement: (Port forwarding sessions only) Send a TerminateSession command to SSM Agent when the local user presses Ctrl+C.
1.1.33.0	September 26, 2019	Enhancement: (Port forwarding sessions only) Send a disconnect signal to the server when the client drops the TCP connection.
1.1.31.0	September 6, 2019	Enhancement: Update to keep port forwarding session open until remote server closes the connection.
1.1.26.0	July 30, 2019	Enhancement: Update to limit the rate of data transfer during a session.
1.1.23.0	July 9, 2019	Enhancement: Added support for running SSH sessions using Session Manager.
1.1.17.0	April 4, 2019	Enhancement: Added support for further encryption of session data using AWS Key Management Service (AWS KMS).
1.0.37.0	September 20, 2018	Enhancement: Bug fix for Windows version.
1.0.0.0	September 11, 2018	Initial release of the Session Manager plugin.