Sign In to the Console
AWS Systems Manager
User Guide

AWS Documentation » AWS Systems Manager » User Guide » AWS Systems Manager Instances & Nodes » AWS Systems Manager Session Manager » Working with Session Manager » Start a Session

Start a Session

You can use the AWS Systems Manager console, the AWS CLI, or SSH to start a session.

Starting a Session (Console)

You can use the AWS Systems Manager console to start a session with an instance in your account.

To start a session (console)

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

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

  3. Choose Start session.

  4. For Target instances, choose the option button to the left of the instance you want to connect to.

    If an instance you want to connect to is not in the list, or is listed but an error message reports, "The instance you selected is not configured to use Session Manager," see Instance Not Available or Not Configured for Session Manager for troubleshooting steps.

  5. Choose Start session.

After the connection is made, you can run bash commands (Linux) or PowerShell commands (Windows) as you would through any other connection type.

Starting a Session (AWS CLI)

To start a session using the AWS CLI, run the following command:

Note

To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine. For information, see (Optional) Install the Session Manager Plugin for the AWS CLI. 

aws ssm start-session --target instance-id

instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its Session Manager capability, such as i-02573cafcfEXAMPLE.

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 using SSH, run the following command:

Note

To start a session using SSH, your target instance must be configured to support SSH connections. For more information, see (Optional) Enable SSH Connections Through Session Manager. 

ssh -i /path/my-key-pair.pem username@instance-id

/path/my-key-pair.pem represents the path to the Privacy Enhanced Mail (PEM) certificate that is associated with the instance. For example, for an Amazon EC2 instance, the key-pair file you created or selected when you created the instance.

username@instance-id represents the user name you use to connect to the instance, and the instance ID, such as JaneDoe@i-02573cafcfEXAMPLE.

Tip

When you start a session using SSH, you can copy local files to the target instance using the following command format. 

scp -i /path/my-key-pair.pem /path/SampleFile.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 port forwarding session, run the following command from the CLI:

Note

To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine. For information, see (Optional) Install the Session Manager Plugin for the AWS CLI. 

aws ssm start-session --target instance-id --document-name AWS-StartPortForwardingSession --parameters '{"portNumber":["80"], "localPortNumber":["56789"]}'

instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its Session Manager capability, such as i-02573cafcfEXAMPLE.

portNumber represents the remote port on the instance where traffic should be redirected to, such as 3389. If this parameter is not specified, Session Manager assumes 80 as the default remote port.

localPortNumber represents the local port on the client where traffic should be redirected to, such as 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 Commands)

To start an Interactive Command session, run the following command:

Note

To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine. For information, see (Optional) Install the Session Manager Plugin for the AWS CLI. 

aws ssm start-session --target instance-id --document-name CustomCommandSessionDocument --parameters '{"logpath":["/var/log/amazon/ssm/amazon-ssm-agent.log"]}'

instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its Session Manager capability, such as i-02573cafcfEXAMPLE.

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.

Related Content

Port Forwarding Using AWS Systems Manager Session Manager on the AWS News Blog.