Start a session
You can use the AWS Systems Manager console, the Amazon Elastic Compute Cloud (Amazon EC2) console, the AWS Command Line Interface (AWS CLI), or SSH to start a session.
Topics
Starting a session (Systems Manager console)
You can use the AWS Systems Manager console to start a session with a managed node in your account.
Note
Before you start a session, make sure that you have completed the setup steps for Session Manager. For information, see Setting up Session Manager.
To start a session (Systems Manager console)
Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/
. In the navigation pane, choose Session Manager.
-or-
If the AWS Systems Manager home page opens first, choose the menu icon (
) to open the navigation pane, and then choose Session Manager in the navigation pane.
-
Choose Start session.
-
(Optional) Enter a session description in the Reason for session field.
-
For Target instances, choose the option button to the left of the managed node that you want to connect to.
If the node that you want isn't in the list, or if you select a node and receive a configuration error, see Managed node not available or not configured for Session Manager for troubleshooting steps.
-
Choose Start session to launch the session immediately.
-or-
Choose Next for session options.
-
(Optional) For Session document, select the document that you want to run when the session starts. If your document supports runtime parameters, you can enter one or more comma-separated values in each parameter field.
-
Choose Next.
-
Choose Start session.
After the connection is made, you can run bash commands (Linux and macOS) or PowerShell commands (Windows) as you would through any other connection type.
Important
If you want to allow users to specify a document when starting sessions in the Session Manager console, note the following:
-
You must grant users the
ssm:GetDocument
andssm:ListDocuments
permissions in their IAM policy. For more information, see Grant access to custom Session documents in the console. -
The console only supports Session documents that have the
sessionType
defined asStandard_Stream
. For more information, see Session document schema.
Starting a session (Amazon EC2 console)
You can use the Amazon Elastic Compute Cloud (Amazon EC2) console to start a session with an instance in your account.
Note
If you receive an error that you aren't authorized to perform one or more
Systems Manager actions (ssm:
,
then you must contact your administrator for assistance. Your administrator
is the person that provided you with your sign-in credentials. Ask that
person to update your policies to allow you to start sessions from the Amazon EC2
console. If you're an administrator, see Sample IAM
policies for Session Manager for more
information.command-name
To start a session (Amazon EC2 console)
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/
. -
In the navigation pane, choose Instances.
-
Select the instance and choose Connect.
-
For Connection method, choose Session Manager.
-
Choose Connect.
After the connection is made, you can run bash commands (Linux and macOS) or PowerShell commands (Windows) as you would through any other connection type.
Starting a session (AWS CLI)
Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see Installing or updating the latest version of the AWS CLI.
Before you start a session, make sure that you have completed the setup steps for Session Manager. For information, see Setting up Session Manager.
To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine. For information, see Install the Session Manager plugin for the AWS CLI.
To start a session using the AWS CLI, run the following command replacing
instance-id
with your own information.
aws ssm start-session \
--target instance-id
For information about other options you can use with the start-session command, see start-session in the AWS Systems Manager section of the AWS CLI Command Reference.
Starting a session (SSH)
To start a Session Manager SSH session, version 2.3.672.0 or later of SSM Agent must be installed on the managed node.
SSH connection requirements
Take note of the following requirements and limitations for session connections using SSH:
-
Your target managed node must be configured to support SSH connections. For more information, see (Optional) Enable and control permissions for SSH connections through Session Manager.
-
You must connect using the managed node account associated with the Privacy Enhanced Mail (PEM) certificate, not the
ssm-user
account that is used for other types of session connections. For example, on EC2 instances for Linux and macOS, the default user isec2-user
. For information about identifying the default user for each instance type, see Get Information About Your Instance in the Amazon EC2 User Guide for Linux Instances. Logging isn't available for Session Manager sessions that connect through port forwarding or SSH. This is because SSH encrypts all session data, and Session Manager only serves as a tunnel for SSH connections.
Note
Before you start a session, make sure that you have completed the setup steps for Session Manager. For information, see Setting up Session Manager.
To start a session using SSH, run the following command. Replace each
example resource placeholder
with your own
information.
ssh -i
/path/my-key-pair.pem
username@instance-id
Tip
When you start a session using SSH, you can copy local files to the target managed node using the following command format.
scp -i
/path/my-key-pair.pem /path/ExampleFile.txt username@instance-id:~
For information about other options you can use with the start-session command, see start-session in the AWS Systems Manager section of the AWS CLI Command Reference.
Starting a session (port forwarding)
To start a Session Manager port forwarding session, version 2.3.672.0 or later of SSM Agent must be installed on the managed node.
Note
Before you start a session, make sure that you have completed the setup steps for Session Manager. For information, see Setting up Session Manager.
To use the AWS CLI to run session commands, you must install the Session Manager plugin on your local machine. For information, see Install the Session Manager plugin for the AWS CLI.
Depending on your operating system and command line tool, the placement of quotation marks can differ and escape characters might be required.
To start a port forwarding session, run the following command from the CLI.
Replace each example resource placeholder
with your
own information.
The portNumber
value represents the remote port on the managed
node where you want the session traffic to be redirected. For example, you might
specify port 3389
for connecting to a Windows node
using the Remote Desktop Protocol (RDP). If you don't specify the
portNumber
parameter, Session Manager uses 80
as the
default value.
The value you specify for localPortNumber
represents the local
port on the client where traffic should be redirected to, such as
56789
. This value is what you enter when connecting to a
managed node using a client. For example,
localhost:56789
.
For information about other options you can use with the start-session command, see start-session in the AWS Systems Manager section of the AWS CLI Command Reference.
For more information about port forwarding sessions, see Port Forwarding Using AWS Systems ManagerSession Manager
Starting a session (port forwarding to remote host)
To start a Session Manager port forwarding session to a remote host, version 3.1.1374.0 or later of SSM Agent must be installed on the managed node. The remote host isn't required to be managed by Systems Manager.
Note
Before you start a session, make sure that you have completed the setup steps for Session Manager. For information, see Setting up Session Manager.
To use the AWS CLI to run session commands, you must install the Session Manager plugin on your local machine. For information, see Install the Session Manager plugin for the AWS CLI.
Depending on your operating system and command line tool, the placement of quotation marks can differ and escape characters might be required.
To start a port forwarding session, run the following command from the CLI.
Replace each example resource placeholder
with your
own information.
The host
value represents the hostname or IP address of the
remote host that you want to connect to. General connectivity and name
resolution requirements between the managed node and the remote host still
apply.
The portNumber
value represents the port on the remote host where
you want the session traffic to be redirected. For example, you might specify
port 3306
for connecting to a MySQL database. If you don't specify
the portNumber
parameter, Session Manager uses 80
as the
default value.
The value you specify for localPortNumber
represents the local
port on the client where traffic should be redirected to, such as
56789
. This value is what you enter when connecting to a
managed node using a client. For example,
localhost:56789
.
For information about other options you can use with the start-session command, see start-session in the AWS Systems Manager section of the AWS CLI Command Reference.
Starting a session (interactive and noninteractive commands)
Before you start a session, make sure that you have completed the setup steps for Session Manager. For information, see Setting up Session Manager.
To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine. For information, see Install the Session Manager plugin for the AWS CLI.
To start an interactive command session, run the following command. Replace
each example resource placeholder
with your own
information.
For information about other options you can use with the start-session command, see start-session in the AWS Systems Manager section of the AWS CLI Command Reference.
- More info
-
-
Port Forwarding Using AWS Systems ManagerSession Manager
on the AWS News Blog.
-