Install the Session Manager plugin for the AWS CLI - AWS Systems Manager
Install the Session Manager plugin on WindowsInstall and uninstall the Session Manager plugin on macOSInstall the Session Manager plugin on macOS with the signed installerInstall Session Manager plugin on LinuxInstall the Session Manager plugin on UbuntuVerify the Session Manager plugin installationSession Manager plugin on GitHub(Optional) Turn on Session Manager plugin loggingSession Manager plugin latest version and release history

Install the Session Manager plugin for the AWS CLI

To use the AWS Command Line Interface (AWS CLI) to initiate sessions with your managed nodes, you must first install the Session Manager plugin on your local machine. You can install the plugin on supported versions of Microsoft Windows, macOS, Linux, and Ubuntu.

Always use the latest Session Manager plugin version

We occassionally update the Session Manager plugin with new or enhanced functionality. Therefore we recommend that you always install the most recent version. For more information, see Session Manager plugin latest version and release history.

Install the required AWS CLI version

To use the Session Manager plugin, you must have AWS CLI version 1.16.12 or later installed on your local machine.

Install the Session Manager plugin on Windows

You can install the Session Manager plugin on 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 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

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 commands.

    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 and install the Session Manager plugin RPM package.

    x86_64
    sudo yum install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm
    x86
    sudo yum install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_32bit/session-manager-plugin.rpm
    ARM64
    sudo yum install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.rpm

  2. 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.

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 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.