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.
Topics
- Install the Session Manager plugin on Windows
- Install and uninstall the Session Manager plugin on macOS
- Install the Session Manager plugin on macOS with the signed installer
- Install Session Manager plugin on Linux
- Install the Session Manager plugin on Ubuntu
- Verify the Session Manager plugin installation
- Session Manager plugin on GitHub
- (Optional) Turn on Session Manager plugin logging
- Session Manager plugin latest version and release history
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
-
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
-
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\
-
-
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)
-
Download the bundled installer.
-
Unzip the package.
unzip sessionmanager-bundle.zip
-
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 symlinksession-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
-
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)
-
Download the signed installer.
-
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
-
Verify that the installation was successful. For information, see Verify the Session Manager plugin installation.
Install Session Manager plugin on Linux
-
Download and install the Session Manager plugin RPM package.
-
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
-
Download the Session Manager plugin deb package.
-
Run the install command.
sudo dpkg -i session-manager-plugin.deb
-
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
(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)
-
Locate the
seelog.xml.template
file for the plugin.The default location is
C:\Program Files\Amazon\SessionManagerPlugin\seelog.xml.template
. -
Change the name of the file to
seelog.xml
. -
Open the file and change
minlevel="off"
tominlevel="info"
orminlevel="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.
-
Change other configuration options you want to modify. Options you can change include:
-
Debug level: You can change the debug level from
formatid="fmtinfo"
toformatid="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"/>
-
-
Save the file.
Enable logging for the Session Manager plugin (Linux and macOS)
-
Locate the
seelog.xml.template
file for the plugin.The default location is
/usr/local/sessionmanagerplugin/seelog.xml.template
. -
Change the name of the file to
seelog.xml
. -
Open the file and change
minlevel="off"
tominlevel="info"
orminlevel="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.
-
Change other configuration options you want to modify. Options you can change include:
-
Debug level: You can change the debug level from
formatid="fmtinfo"
tooutputs 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.
-
-
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
|
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. |