# Debug builds with Session Manager
In AWS CodeBuild, you can pause a running build and then use AWS Systems Manager Session Manager to connect to the build container and view the state of the container.
**Note**
This feature is not available in Windows environments.
**Topics**
+ [Prerequisites](#ssm.prerequisites)
+ [Pause the build](#ssm-pause-build)
+ [Start the build](#ssm-start-build)
+ [Connect to the build container](#ssm-connect)
+ [Resume the build](#ssm-resume-build)
## Prerequisites
To allow Session Manager to be used with the build session, you must enable session connection for the build. There are two prerequisites:
+ CodeBuild Linux standard curated images already have the SSM agent installed and the SSM agent ContainerMode enabled.
If you are using a custom image for your build, do the following:
1. Install the SSM Agent. For more information, see [Manually install SSM Agent on EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html) in the AWS Systems Manager User Guide. The SSM Agent version must be 3.0.1295.0 or later.
1. Copy the file [https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json) to the `/etc/amazon/ssm/` directory in your image. This enables Container Mode in the SSM agent.
**Note**
Custom images would require most updated SSM agent for this feature to work as expected.
+ The CodeBuild service role must have the following SSM policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
}
]
}
```
------
You can have the CodeBuild console automatically attach this policy to your service role when you start the build. Alternatively, you can attach this policy to your service role manually.
+ If you have **Auditing and logging session activity** enabled in Systems Manager preferences, the CodeBuild service role must also have additional permissions. The permissions are different, depending on where the logs are stored.
CloudWatch Logs
If using CloudWatch Logs to store your logs, add the following permission to the CodeBuild service role:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:DescribeLogGroups",
"Resource": "arn:aws:logs:us-east-1:111122223333:log-group:*:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:us-east-1:111122223333:log-group:MyLogGroup:*"
}
]
}
```
Amazon S3
If using Amazon S3 to store your logs, add the following permission to the CodeBuild service role:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::",
"arn:aws:s3:::/*"
]
}
]
}
```
For more information, see [Auditing and logging session activity](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-logging-auditing.html) in the *AWS Systems Manager User Guide*.
## Pause the build
To pause the build, insert the **codebuild-breakpoint** command in any of the build phases in your buildspec file. The build will be paused at this point, which allows you to connect to the build container and view the container in its current state.
For example, add the following to the build phases in your buildspec file.
```
phases:
pre_build:
commands:
- echo Entered the pre_build phase...
- echo "Hello World" > /tmp/hello-world
- codebuild-breakpoint
```
This code creates the `/tmp/hello-world` file and then pauses the build at this point.
## Start the build
To allow Session Manager to be used with the build session, you must enable session connections for the build. To do this, when starting the build, follow these steps:
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. In the navigation pane, choose **Build projects**. Choose the build project, and then choose **Start build with overrides**.
1. Choose **Advanced build overrides**.
1. In the **Environment** section, choose the **Enable session connection** option. If this option is not selected, all of the **codebuild-breakpoint** and **codebuild-resume** commands are ignored.
1. Make any other desired changes, and choose **Start build**.
1. Monitor the build status in the console. When the session is available, the **AWS Session Manager** link appears in the **Build status** section.
## Connect to the build container
You can connect to the build container in one of two ways:
CodeBuild console
In a web browser, open the **AWS Session Manager** link to connect to the build container. A terminal session opens that allows you to browse and control the build container.
AWS CLI
Your local machine must have the Session Manager plugin installed for this procedure. For more information, see [Install the Session Manager Plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) in the AWS Systems Manager User Guide.
1. Call the **batch-get-builds** api with the build ID to get information about the build, including the session target identifier. The session target identifier property name varies depending on the output type of the `aws` command. This is why `--output json` is added to the command.
```
aws codebuild batch-get-builds --ids --region --output json
```
1. Copy the `sessionTarget` property value. The `sessionTarget` property name can vary depending on the output type of the `aws` command. This is why `--output json` is added to the command in the previous step.
1. Use the following command to connect to the build container.
```
aws ssm start-session --target --region
```
For this example, verify that the `/tmp/hello-world` file exists and contains the text `Hello World`.
## Resume the build
After you finish examining the build container, issue the **codebuild-resume** command from the container shell.
```
$ codebuild-resume
```