This plugin helps you to use the AWS Command Line Interface (AWS CLI) to start and end sessions to your managed instances

Overview

Session Manager Plugin

This plugin helps you to use the AWS Command Line Interface (AWS CLI) to start and end sessions to your managed instances. Session Manager is a capability of AWS Systems Manager.

Overview

Session Manager is a fully managed AWS Systems Manager capability that lets you manage your Amazon Elastic Compute Cloud (Amazon EC2) instances, on-premises instances and virtual machines. Session Manager provides secure and auditable instance management without the need to open inbound ports. When you use the Session Manager plugin with the AWS CLI to start a session, the plugin builds the websocket connection to your managed instances.

Prerequisites

Before using Session Manager, make sure your environment meets the following requirements. Complete Session Manager prerequisites.

Starting a session

For information about starting a session using the AWS CLI, see Starting a session (AWS CLI).

Troubleshooting

For information about troubleshooting, see Troubleshooting Session Manager.

Working with Docker

To build the Session Manager plugin in a Docker container, complete the following steps:

  1. Install docker

  2. Build the docker image

docker build -t session-manager-plugin-image .
  1. Build the plugin
docker run -it --rm --name session-manager-plugin -v `pwd`:/session-manager-plugin session-manager-plugin-image make release

Working with Linux

To build the binaries required to install the Session Manager plugin, complete the following steps.

  1. Install golang

  2. Install rpm-build and rpmdevtools

  3. Install gcc 8.3+ and glibc 2.27+

  4. Run make release to build the plugin for Linux, Debian, macOS and Windows.

  5. Change to the directory of your local machine's operating system architecture and open the session-manager-plugin directory. Then follow the installation procedure that applies to your local machine. For more information, see Install the Session Manager plugin for the AWS CLI. If the machine you're building the plugin on differs from the machine you plan to install the plugin on you will need to copy the session-manager-plugin binary to the appropriate directory for that operating system.

Linux - /usr/local/sessionmanagerplugin/bin/session-manager-plugin

macOS - /usr/local/sessionmanagerplugin/bin/session-manager-plugin

Windows - C:\Program Files\Amazon\SessionManagerPlugin\bin\session-manager-plugin.exe

The ssmcli binary is available for some operating systems for testing purposes only. The following is an example command using this binary.

./ssmcli start-session --instance-id i-1234567890abcdef0 --region us-east-2

Directory structure

Source code

  • sessionmanagerplugin/session contains the source code for core functionalities
  • communicator/ contains the source code for websocket related operations
  • vendor/src contains the vendor package source code
  • packaging/ contains rpm and dpkg artifacts
  • Tools/src contains build scripts

Feedback

Thank you for helping us to improve the Session Manager plugin. Please send your questions or comments to the Systems Manager Forum

License

The session-manager-plugin is licensed under the Apache 2.0 License.

Issues
  • Does not properly handle 'pause_publication'

    Does not properly handle 'pause_publication'

    The plugin does not properly handle the pause_publication message.

    If connected to an ECS task that is killed while still being connected, the logs show:

    2021-11-05 03:57:33 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:33 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:33 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:33 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:33 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    2021-11-05 03:57:34 WARN [OutputMessageHandler @ streaming.go.411] Invalid message type received: %spause_publication
    2021-11-05 03:57:34 DEBUG [func1 @ streaming.go.339] Resend stream data message: 241
    ...
    

    (This is an infinite loop and will just fill up the log file).

    Ideally, the server should have closed the connection (and sent the channel_closed message).

    Since that doesn't appear to be happening, it would be nice if the client could at least handle the pause_publication message.

    In my use case, it would be best if this would exit the plugin.

    Steps to recreate:

    • Enable debug logging (not sure if this is required, but obviously I have it enabled)
    • Start an ECS task where the command is sleep 86400 (you can probably set something lower)
    • run an ExecuteCommand against that task with /bin/bash in interactive mode
    • Wait for the sleep timer to expire
    • plugin will remain running, but does not respond to input.
    • log files will accumulate until you forcibly terminate the plugin.
    opened by webdestroya 7
  • BUG: CTRL-D in an SSM session exits the session abruptly

    BUG: CTRL-D in an SSM session exits the session abruptly

    I don't know if this is a feature or a bug... but I regularly use the joe text editor and CTRL-D is one of the standard shortcuts which when used in an SSM SSH session it instantly disconnects with an error...

    Cannot perform start session: read /dev/stdin: resource temporarily unavailable
    

    On a fresh SSH connection, when I CTRL-D it exits...

    Starting session with SessionId: username-0ed94becce0968820
    $    <-  HERE I HIT CTRL-D
    
    Exiting session with sessionId: username-0ed94becce0968820.
    

    I assume/hope this is not a feature or some internal SSM hook to disconnect or something, but incase it is, is there a way to rebind it perhaps to another keystroke? I assume I'm not the only person to hit this issue, as more people transition off of using SSH and onto SSM, imho having an fully-compatible ssh-like tunnel is critical. And having special key combinations that are "caught" by the ssm engine feels like a potential incompatibility with software run in the remote console that may use this hook.

    opened by AndrewFarley 4
  • An error occurred (TargetNotConnected) when calling the StartSession operation

    An error occurred (TargetNotConnected) when calling the StartSession operation

    I can connect to instance i-123456 in the Console.

    $ cat /etc/lsb-release
    DISTRIB_ID=Ubuntu
    DISTRIB_RELEASE=20.04
    DISTRIB_CODENAME=focal
    DISTRIB_DESCRIPTION="Ubuntu 20.04.2 LTS"
    $ aws --version
    aws-cli/2.2.17 Python/3.8.8 Linux/4.4.0-18362-Microsoft exe/x86_64.ubuntu.20 prompt/off
    $ session-manager-plugin --version
    1.2.205.0
    $ aws ssm start-session --target i-123456
    An error occurred (TargetNotConnected) when calling the StartSession operation: i-123456 is not connected.
    $ curl https://ssm.us-east-1.amazonaws.com/
    <UnknownOperationException/>
    

    Any pointers on what might be causing this?

    opened by gliptak 4
  • AWS SSO temporary credentials support (Update AWS Go SDK version)

    AWS SSO temporary credentials support (Update AWS Go SDK version)

    We ran into an issue where running the session manager plugin while using temporary credentials obtained through calling:

    aws sso login

    We were getting this error, which appeared at first to be an issue with the plugin being unable to reach the AWS KMS endpoint:

    Encountered error while initiating handshake. Handshake timed out. Please ensure that you have the latest version of the session manager plugin.

    I verified that I was running the latest version of the plugin, and yet still it wasn't working. I turned on logging for the plugin and found this error:

    2021-06-23 15:26:29 ERROR [generateEncryptionKey @ encrypter.go.60] Error generating data key from KMS: Error calling KMS GenerateDataKey API: NoCredentialProviders: no valid providers in chain. Deprecated. For verbose messaging see aws.Config.CredentialsChainVerboseErrors,

    Based on some searching, it appears to be a result of the AWS Go API not properly supporting the AWS SSO temporary credentials. I verified this by switching over to hardcoded keys copied from the AWS SSO applications page.

    I looked in the repo, and it appears that this project is using a very old version of the AWS Go SDK from early last year. Could we get the Go SDK version updated so get some of the fixes that have occurred in the last 1.5 years? Thank you!

    opened by jetheredge 4
  • Restructure Repo w/ Go Modules and Add Darwin arm64 support

    Restructure Repo w/ Go Modules and Add Darwin arm64 support

    Issue #, if available: https://github.com/aws/session-manager-plugin/issues/1 https://github.com/aws/session-manager-plugin/issues/9

    Description of changes:

    • Move go src and repo structure to a more conventional and modern go structure
      • Move any main packages to the top-level cmd dir
      • Upgrade go build version to 1.16
      • Use go modules (using the repo as the module name) and remove all checked-in vendor deps
      • Remove unmaintained uuid lib and replace w/ google/uuid
    • Support Darwin arm64 builds and packaging
    • Make bash packaging scripts safer by exiting if an error occurs w/ set -euo pipefail
    • Add proper github PR template w/ correct license
    • Add github actions workflow w/ checkstyle and quick-test targets to check PRs automatically

    Testing:

    • make checkstyle quick-test PASSED
    • make build-darwin-arm64 package-darwin-arm64 PASSED
    • Built binary and tested connecting an ec2-instance. PASSED

    By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

    opened by bwagner5 3
  • Improve: Change state name and error wording when LegacyArgumentLength

    Improve: Change state name and error wording when LegacyArgumentLength

    In session-manager-plugin, it is in the state of IsAwsCliUpgradeNeeded with 4 arguments as LegacyArgumentLength. https://github.com/aws/session-manager-plugin/blob/e4ad4017df969b298c3e263f0c8ce9881c0b0a79/src/sessionmanagerplugin/session/session.go#L136

    At this time, ProcessKMSEncryptionHandshakeAction will display an error, but please consider changing the error wording and state name at this time. https://github.com/aws/session-manager-plugin/blob/65933d1adf368d1efde7380380a19a7a691340c1/src/datachannel/streaming.go#L832

    This is because session-manager-plugin is used in addition to awscli such as copilot-cli and ecspresso, and the error wording "Please upgrade to latest version of AWS CLI" can be misleading. https://github.com/aws/copilot-cli/blob/ada23de30b1dab0b0d0659a66d45bdfc6646954e/internal/pkg/exec/ssm_plugin.go#L56 https://github.com/kayac/ecspresso/blob/v1/exec.go#L93

    Thank you for your consideration.

    opened by somen440 2
  • Usage of AWS SDK for Go v2

    Usage of AWS SDK for Go v2

    Current situation

    Currently, this project uses the first version of AWS SDK for Go.

    Proposal

    My proposal is to upgrade to the latest SDK for Go made by AWS (v2): https://github.com/aws/aws-sdk-go-v2

    opened by cguertin14 2
  • Add native support for darwin-arm64

    Add native support for darwin-arm64

    This updates the makefile and darwin build script to natively support arm64.

    By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

    opened by DennoVonDiesel 0
  • Pull latest upstream and add darwin-arm64 support

    Pull latest upstream and add darwin-arm64 support

    https://app.asana.com/0/1202052627147940/1202352747963756/f

    Description of changes: Pulled latest version from upstream and added native darwin-arm64 support.

    By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

    opened by DennoVonDiesel 0
  • Port forwarding opens a local port only on the IPv6 interface

    Port forwarding opens a local port only on the IPv6 interface

    Description

    When trying to forward a port to a remote host using the new feature, I'm able to open the tunnel and even connect to the remote host through it, but the port is only opened, locally, on an IPv6 interface.

    While it's not a problem when running a client directly on my host, it is a problem when trying to run the client inside docker containers, because the docker engine only binds to IPv4 interfaces, so the local port is not available.

    Expected

    The port is available on both IPv6 and IPv4, and it's possible to connect to the port from a docker container running on the local host.

    Actual

    The port is only available on IPv6 and not accessible from a docker container.

    Versions

    I'm on MacOS 11.6.7 (Big sur), with Docker desktop 4.8.2 (I don't think that matters), aws cli 2.7.10 and session-manager-plugin 1.2.339.0.

    Steps to reproduce

    Here's what I do:

    aws --profile experiment ssm start-session \
         --target i-XXXXXXX \
         --document-name AWS-StartPortForwardingSessionToRemoteHost \
         --parameters '{"host":["YYYYYYYYY"],"portNumber":["3306"], "localPortNumber":["3316"]}'
    

    When the tunnel is opened, I run lsof -i -P | grep -i "listen" and get only the following (relevant) line:

    session-m 52168 xxxxx   22u  IPv6 0x64bf25a801ab42ab      0t0  TCP localhost:3316 (LISTEN)
    

    No IPv4 equivalent.

    Using the mysql client from my host on port 3316 connects without issues, but doing the same thing from a docker container (using -h host.docker.internal) does not.

    $> mysql -h ::0 -P 3316 -u admin -p 
    Enter password: 
    Welcome to the MySQL monitor.  Commands end with ; or \g.
    [...]
    
    $> mysql -h 127.0.0.1 -P 3316 -u admin -p
    Enter password: 
    ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:3316' (61)
    
    $> docker run -ti --rm mysql:8.0 mysql -h host.docker.internal -P 3316 -u admin -p
    Enter password: 
    ERROR 2003 (HY000): Can't connect to MySQL server on 'host.docker.internal:3316' (111)
    
    opened by patatepartie 0
  • Problems with tunnels to RDS

    Problems with tunnels to RDS

    As of some recent version the tunneling experience is really terrible and every query times out with:

    SSL SYSCALL error: EOF detected

    In another repo for TablePlus someone commented that they found an issue with a Google SDK, so I suspect this is the same underlying Python package in session-manager-plugin that is causing these issues.

    This did not happen even a few months ago.

    opened by moltar 5
  • added darwin arm64

    added darwin arm64

    Issue #, if available: https://github.com/aws/session-manager-plugin/issues/26

    Description of changes: Added Tools/src/create_darwin_arm64_bundle_plugin.sh as a carbon copy of Tools/src/create_darwin_bundle_plugin.sh, except all instances of amd64 are replaced with arm64. Moved the above script to Tools/src/create_darwin_amd64_bundle_plugin.sh to help differentiate between the two bundlers.

    Added targets for the arm64 architecture to the makefile above every instance of the amd64 build steps for darwin.

    Renamed the bundler script in the makefile to use the new bundler script for amd64 architecture

    By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

    opened by bleepbloopsify 2
  • Tools that use session-manager-plugin

    Tools that use session-manager-plugin

    Hi,

    It would be great if there was a markdown file that had different tools that used session-manager-plugin. There is some older tools I only found out about recently that really helped with work I was doing. Would be great to highlight these non official tools as such but also let people find them.

    Cheers, Andrew

    opened by andymac4182 3
  • Upgrade to go 1.16 and add darwin-arm64 support.

    Upgrade to go 1.16 and add darwin-arm64 support.

    go 1.16 is required for darwin-arm64 support. I've added this to the build process.

    By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

    opened by DennoVonDiesel 5
  • 1.2.323.0 does not respect session timeout when using an older version of the ssm-agent

    1.2.323.0 does not respect session timeout when using an older version of the ssm-agent

    It appears that the change to remove the idle timeout in smux does not respect the regional SSM session timeout if you're using an older version of the agent with some types of SSM documents. Specifically, if you start a StartPortForwardingSession and leave it idle it will close after ~30s, which is far shorter than the default SSM session timeout.

    I'm currently running 3.1.1374 of the ssm-agent since that is the latest version that is available for Debian in the public S3 bucket.

    opened by protochron 4
Releases(1.2.339.0)
Owner
Amazon Web Services
Amazon Web Services
Igo Agent is the agent of Igo, a command-line tool, through which you can quickly start Igo

igo agent θ‹±ζ–‡ | δΈ­ζ–‡ Igo Agent is the agent of Igo, a command-line tool, through which you can quickly start Igo, and other capabilities may be added lat

null 1 Dec 22, 2021
K6 extension that adds support for browser automation and end-to-end web testing using playwright-go

k6 extension that adds support for browser automation and end-to-end web testing using playwright-go

We Open Source Performance 9 Jun 16, 2022
go-awssh is a developer tool to make your SSH to AWS EC2 instances easy.

Describing Instances/VPCs data, select one or multiple instances, and make connection(s) to selected instances. Caching the response of API calls for 1day using Tmpfs.

kenju 5 Oct 11, 2021
A Grafana backend plugin for automatic synchronization of dashboard between multiple Grafana instances.

Grafana Dashboard Synchronization Backend Plugin A Grafana backend plugin for automatic synchronization of dashboard between multiple Grafana instance

Novatec Consulting GmbH 6 Apr 8, 2022
Quick start repository for creating a Terraform provider using terraform-plugin-framework

Terraform Provider Scaffolding (Terraform Plugin Framework) This template repository is built on the Terraform Plugin Framework. The template reposito

HashiCorp 38 Jun 27, 2022
The Container Storage Interface (CSI) Driver for Fortress Block Storage This driver allows you to use Fortress Block Storage with your container orchestrator

fortress-csi The Container Storage Interface (CSI) Driver for Fortress Block Storage This driver allows you to use Fortress Block Storage with your co

Fortress 0 Jan 23, 2022
An exporter for bsport.io to track workouts sessions πŸ’ͺ

bsport-exporter An exporter for bsport. It is currently very basic and is supposed to be use to track how many bookings have been made in total: ➜ ~

Stanislas 2 Feb 22, 2022
Create AWS Auto Scaling groups from running instances or AMIs automatically.

AWS Auto Scaling Groups Builder AWS Auto Scaling group is a great way of managing Amazon EC2 instances. AWS Auto Scaling group watches the correspondi

Alexey Shagraev 1 Jan 7, 2022
The Coherence command line interface (CLI) is a lightweight tool, in the tradition of tools such as kubectl

Coherence Command Line Interface (CLI) Contents Overview Why use the Coherence C

Oracle 10 Mar 17, 2022
🏯 Monitor your (gitlab/github) CI/CD pipelines via command line interface with fortress

__ _ / _| | | | |_ ___ _ __| |_ _ __ ___ ___ ___ | _/ _ \| '__| __| '__/ _ \/ __/ _

MrJosh 6 Mar 31, 2022
Addon Operator coordinates the lifecycle of Add-ons in managed OpenShift

Addon Operator Addon Operator coordinates the lifecycle of Addons in managed OpenShift. dev tools setup pre-commit hooks: make pre-commit-install glob

OpenShift 12 Mar 23, 2022
Helm Operator is designed to managed the full lifecycle of Helm charts with Kubernetes CRD resource.

Helm Operator Helm Operator is designed to install and manage Helm charts with Kubernetes CRD resource. Helm Operator does not create the Helm release

Chen Zhiwei 5 Nov 24, 2021
Simple docker tui to list, start and stop your containers

docker-tui Simple docker tui that lets you list, start and stop your containers. Current status Rough, initial prototype. Build with This tool relies

Olek 5 Apr 2, 2022
preflight helps you verify scripts and executables to mitigate chain of supply attacks such as the recent Codecov hack.

?? Mitigate chain of supply attacks ?? Verify your curl scripts and executables ?? What is it? preflight helps you verify scripts and executables to m

null 130 Jun 15, 2022
Command Line Interface for Scaleway

Scaleway CLI (v2) Scaleway CLI is a tool to help you pilot your Scaleway infrastructure directly from your terminal. Installation With a Package Manag

Scaleway 755 Jun 27, 2022
Kubegres is a Kubernetes operator allowing to create a cluster of PostgreSql instances and manage databases replication, failover and backup.

Kubegres is a Kubernetes operator allowing to deploy a cluster of PostgreSql pods with data replication enabled out-of-the box. It brings simplicity w

Reactive Tech Ltd 1k Jun 30, 2022
Mattermost outline plugin allows you to search your teams documents.

mattermost-plugin-outline Mattermost Outline plugin allows you to search your teams documents. Installation In Mattermost 5.16 and later, this plugin

Lujeni 7 Nov 10, 2021
crud is a cobra based CLI utility which helps in scaffolding a simple go based micro-service along with build scripts, api documentation, micro-service documentation and k8s deployment manifests

crud crud is a CLI utility which helps in scaffolding a simple go based micro-service along with build scripts, api documentation, micro-service docum

Piyush Jajoo 0 Nov 29, 2021
Cloud-Z gathers information and perform benchmarks on cloud instances in multiple cloud providers.

Cloud-Z Cloud-Z gathers information and perform benchmarks on cloud instances in multiple cloud providers. Cloud type, instance id, and type CPU infor

CloudSnorkel 16 Jun 8, 2022